_private/qwestly-private-docs/SOC2/network/Network Architecture Diagram.md

Table of Contents

Qwestly Network Architecture Diagram

Document Version: 1.1
Date: July 25, 2025
Owner: Dominick Pham, CTO
Classification: Internal Use - SOC2 Compliance

Executive Summary

This document provides comprehensive network diagrams for Qwestly's infrastructure to satisfy SOC 2 Type II audit requirements. Our cloud-native architecture leverages multiple managed services across different providers to ensure security, availability, and scalability while maintaining clear security boundaries and controls.

1. High-Level System Architecture

graph TB
    subgraph "External Users"
        EU[End Users/Candidates]
        HM[Hiring Managers]
        DEV[Developers]
    end

    subgraph "Internet Boundary"
        DNS[DNS Resolution]
        INTERNET[Internet Gateway]
    end

    subgraph "Vercel Edge Network (Global)"
        subgraph "Edge Infrastructure"
            EDGE[Vercel Edge Network]
            LB[Load Balancer]
            CDN[Built-in CDN]
        end
        
        subgraph "Frontend Applications"
            MW[Marketing Website
qwestly.com]
            CA[Candidate Portal
discover.qwestly.com]
            HMP[Hiring Manager Portal
hire.qwestly.com]
        end
        
        subgraph "API Layer"
            API[Python API
Vercel Functions]
            NJS[Next.js API Routes]
        end
    end

    subgraph "AWS CloudFront + S3 (US-West-1)"
        CF[CloudFront Distribution]
        S3STATIC[S3 Static Assets Bucket]
        S3UPLOAD[S3 User Uploads Bucket]
    end

    subgraph "Authentication & Identity - Auth0 (US)"
        AUTH[Auth0 Identity Provider]
        MFA[Multi-Factor Authentication]
        SSO[Single Sign-On]
    end

    subgraph "Data Layer"
        subgraph "MongoDB Atlas (US-West-1)"
            MONG[(Primary Database)]
            MONGR[(Read Replicas)]
        end
        
        subgraph "Supabase (US-West)"
            SUPDB[(Vector Database)]
            SUPAUTH[Authentication API]
            SUPSTORE[File Storage]
        end
        
        subgraph "AWS S3 (US-West-1)"
            S3LOG[Log Storage]
            S3DOC[Document Storage]
            S3BACKUP[Backup Storage]
        end
    end

    subgraph "External AI Services"
        ANTHROPIC[Anthropic Claude]
        OPENAI[OpenAI GPT]
        GOOGLE[Google Vertex AI]
        GROQ[Groq]
        MISTRAL[Mistral AI]
    end

    subgraph "Monitoring & Compliance"
        subgraph "GitHub (Security)"
            GH[GitHub Repositories]
            GHACT[GitHub Actions CI/CD]
            GHSEC[Security Scanning]
        end
        
        VERMON[Vercel Analytics]
        POSTHOG[PostHog Analytics]
        SENDGRID[SendGrid Email]
    end

    %% User flows
    EU --> DNS
    HM --> DNS
    DEV --> GH
    
    %% DNS and edge routing
    DNS --> EDGE
    EDGE --> LB
    LB --> CDN
    
    %% CDN to applications
    CDN --> MW
    CDN --> CA
    CDN --> HMP
    
    %% Static asset flows
    EU --> CF
    HM --> CF
    CF --> S3STATIC
    CF --> S3UPLOAD
    
    %% Application interconnections
    MW --> API
    CA --> API
    HMP --> API
    MW --> NJS
    CA --> NJS
    HMP --> NJS
    
    %% Authentication flows
    CA --> AUTH
    HMP --> AUTH
    AUTH --> MFA
    AUTH --> SSO
    
    %% Data flows
    API --> MONG
    API --> SUPDB
    API --> S3DOC
    API --> S3UPLOAD
    NJS --> MONG
    NJS --> SUPDB
    
    %% AI service connections
    API --> ANTHROPIC
    API --> OPENAI
    API --> GOOGLE
    API --> GROQ
    API --> MISTRAL
    
    %% Logging and monitoring
    API --> S3LOG
    NJS --> S3LOG
    MW --> VERMON
    CA --> VERMON
    HMP --> VERMON
    API --> POSTHOG
    
    %% Email services
    API --> SENDGRID
    NJS --> SENDGRID
    
    %% CI/CD flows
    DEV --> GHACT
    GHACT --> GHSEC
    GHACT --> MW
    GHACT --> CA
    GHACT --> HMP
    GHACT --> API

    %% Styling
    classDef frontend fill:#e1f5fe
    classDef backend fill:#f3e5f5
    classDef database fill:#e8f5e8
    classDef external fill:#fff3e0
    classDef security fill:#ffebee
    classDef aws fill:#ff9800
    
    class MW,CA,HMP frontend
    class API,NJS backend
    class MONG,MONGR,SUPDB,S3LOG,S3DOC,S3BACKUP database
    class ANTHROPIC,OPENAI,GOOGLE,GROQ,MISTRAL external
    class AUTH,MFA,SSO,GHSEC security
    class CF,S3STATIC,S3UPLOAD aws

2. Network Security Zones and Data Flow

graph TB
    subgraph "Internet Zone (Public)"
        USERS[Users/Candidates/HMs]
        BOTS[Search Engine Bots]
        THREAT[Potential Threats]
    end

    subgraph "Edge/CDN Zone (Vercel + AWS)"
        subgraph "Vercel Edge Network"
            VEDGE[Vercel Edge Locations]
            VLB[Vercel Load Balancer]
            VCDN[Vercel CDN Cache]
            VSSL[SSL/TLS Termination]
        end
        
        subgraph "AWS CloudFront"
            CFEDGE[CloudFront Edge Locations]
            CFCACHE[CloudFront Cache]
            CFSSL[CloudFront SSL/TLS]
        end
    end

    subgraph "Application DMZ (Vercel Infrastructure)"
        subgraph "Compute Environment"
            LAMBDA[Serverless Functions]
            CONTAINER[Container Runtime]
            STATIC[Static File Serving]
        end
        
        subgraph "Network Security"
            NETFW[Network Firewall Rules]
            NACL[Network ACLs]
            HEADERS[Security Headers]
        end
    end

    subgraph "Application Zone (Internal)"
        subgraph "Frontend Applications"
            FE1[Marketing Site]
            FE2[Candidate Portal]
            FE3[HM Portal]
        end
        
        subgraph "API Services"
            API1[Python FastAPI]
            API2[Next.js API Routes]
            API3[Authentication API]
        end
    end

    subgraph "Data Zone (Private)"
        subgraph "Primary Databases"
            DB1[(MongoDB Primary)]
            DB2[(Supabase Vector DB)]
        end
        
        subgraph "AWS Storage Systems"
            S31[Document Storage S3]
            S32[Log Storage S3]
            S33[User Upload S3]
            S34[Static Assets S3]
        end
        
        subgraph "Database Security"
            DBFW[Database Firewall]
            VPC[VPC Connections]
            ENCRYPT[Encryption at Rest]
        end
    end

    subgraph "External Services Zone"
        subgraph "AI/ML Providers"
            AI1[Anthropic]
            AI2[OpenAI]
            AI3[Google]
        end
        
        subgraph "SaaS Services"
            SAAS1[Auth0]
            SAAS2[SendGrid]
            SAAS3[PostHog]
        end
    end

    subgraph "Management Zone (Restricted)"
        subgraph "CI/CD Pipeline"
            GITHUB[GitHub Actions]
            DEPLOY[Deployment System]
            MONITOR[Monitoring]
        end
        
        subgraph "Administrative Access"
            ADMIN[Admin Console]
            AWS_CONSOLE[AWS Console]
            AUDIT[Audit Logging]
        end
    end

    %% Data flow arrows with security annotations
    USERS -->|HTTPS/TLS 1.3| VEDGE
    USERS -->|Static Assets| CFEDGE
    VEDGE -->|Filtered Traffic| VCDN
    CFEDGE -->|Cached Assets| S34
    VCDN -->|Clean Traffic| VLB
    VLB -->|Internal HTTPS| LAMBDA
    LAMBDA -->|Secure API| FE1
    LAMBDA -->|Secure API| FE2
    LAMBDA -->|Secure API| FE3
    
    FE1 -->|Auth Required| API1
    FE2 -->|Auth Required| API2
    FE3 -->|Auth Required| API3
    
    API1 -->|VPC Connection| DB1
    API2 -->|Encrypted Connection| DB2
    API3 -->|IAM Authenticated| S31
    API3 -->|Upload Handler| S33
    
    API1 -->|API Keys| AI1
    API2 -->|OAuth 2.0| SAAS1
    API3 -->|API Keys| SAAS2
    
    GITHUB -->|Webhook| DEPLOY
    DEPLOY -->|CI/CD Pipeline| LAMBDA
    MONITOR -->|Metrics Collection| AUDIT

    %% Security annotations
    classDef publicZone fill:#ffcdd2
    classDef edgeZone fill:#fff3e0
    classDef appZone fill:#e8f5e8
    classDef dataZone fill:#e3f2fd
    classDef externalZone fill:#f3e5f5
    classDef mgmtZone fill:#fce4ec
    
    class USERS,BOTS,THREAT publicZone
    class VEDGE,VLB,VCDN,CFEDGE,CFCACHE edgeZone
    class FE1,FE2,FE3,API1,API2,API3 appZone
    class DB1,DB2,S31,S32,S33,S34 dataZone
    class AI1,AI2,AI3,SAAS1,SAAS2,SAAS3 externalZone
    class GITHUB,DEPLOY,MONITOR,ADMIN mgmtZone

3. Authentication and Access Control Flow

sequenceDiagram
    participant U as User
    participant VE as Vercel Edge
    participant FE as Frontend App
    participant AUTH as Auth0
    participant API as API Services
    participant DB as Database
    participant LOG as Audit Logs

    Note over U,LOG: Authentication Flow with Audit Trail

    U->>+VE: HTTPS Request
    VE->>VE: Edge Security Check
    VE->>+FE: Forward Request
    
    FE->>FE: Check Auth State
    alt Not Authenticated
        FE->>+AUTH: Redirect to Login
        AUTH->>AUTH: Multi-Factor Authentication
        AUTH->>-U: MFA Challenge
        U->>+AUTH: MFA Response
        AUTH->>AUTH: Validate Credentials
        AUTH->>+LOG: Log Auth Event
        AUTH->>-FE: Return JWT Token
    end
    
    FE->>+API: API Request + JWT
    API->>API: Validate JWT Signature
    API->>AUTH: Verify Token (if needed)
    AUTH->>API: Token Valid
    
    API->>+DB: Query with User Context
    DB->>DB: Apply Row-Level Security
    DB->>-API: Return Authorized Data
    
    API->>+LOG: Log Data Access
    API->>-FE: Return Response
    FE->>-VE: Response
    VE->>-U: Final Response

    Note over U,LOG: All actions logged for audit compliance

4. Data Flow and Storage Architecture

graph LR
    subgraph "Data Sources"
        USER[User Input]
        UPLOAD[File Uploads]
        FORMS[Form Data]
        API_DATA[API Responses]
    end

    subgraph "Processing Layer"
        subgraph "Data Validation"
            VALIDATE[Input Validation]
            SANITIZE[Data Sanitization]
            ENCRYPT[Encryption]
        end
        
        subgraph "Business Logic"
            LOGIC[Application Logic]
            AI_PROC[AI Processing]
            TRANSFORM[Data Transformation]
        end
    end

    subgraph "Storage Systems"
        subgraph "MongoDB Atlas (Primary - US-West-1)"
            MONGO_P[(Primary Cluster)]
            MONGO_S1[(Secondary 1)]
            MONGO_S2[(Secondary 2)]
            MONGO_BACKUP[(Automated Backups)]
        end
        
        subgraph "Supabase (Vector/Embeddings - US-West)"
            VECTOR[(Vector Database)]
            EMBED[Embedding Generation]
            SEARCH[Semantic Search]
        end
        
        subgraph "AWS S3 (Object Storage - US-West-1)"
            S3_DOCS[Document Storage]
            S3_LOGS[Audit Logs]
            S3_BACKUP[Data Backups]
            S3_UPLOADS[User Uploads]
        end
        
        subgraph "AWS CloudFront"
            CF_DIST[CloudFront Distribution]
            CF_CACHE[Edge Cache]
        end
    end

    subgraph "Data Protection Controls"
        subgraph "Encryption"
            ENC_TRANSIT[TLS 1.3 in Transit]
            ENC_REST[AES-256 at Rest]
            KEY_MGMT[Key Management]
        end
        
        subgraph "Access Controls"
            RBAC[Role-Based Access]
            RLS[Row-Level Security]
            IAM[AWS IAM Policies]
        end
        
        subgraph "Compliance"
            AUDIT_TRAIL[Audit Trail]
            RETENTION[Data Retention]
            GDPR[GDPR Compliance]
        end
    end

    %% Data flow paths
    USER --> VALIDATE
    UPLOAD --> SANITIZE
    FORMS --> VALIDATE
    API_DATA --> ENCRYPT
    
    VALIDATE --> LOGIC
    SANITIZE --> AI_PROC
    ENCRYPT --> TRANSFORM
    
    LOGIC --> MONGO_P
    AI_PROC --> VECTOR
    TRANSFORM --> S3_DOCS
    UPLOAD --> S3_UPLOADS
    
    MONGO_P --> MONGO_S1
    MONGO_P --> MONGO_S2
    MONGO_P --> MONGO_BACKUP
    
    S3_UPLOADS --> CF_DIST
    CF_DIST --> CF_CACHE
    
    VECTOR --> EMBED
    VECTOR --> SEARCH
    
    S3_DOCS --> S3_BACKUP
    
    %% Security controls
    MONGO_P -.-> RBAC
    VECTOR -.-> RLS
    S3_DOCS -.-> IAM
    S3_UPLOADS -.-> IAM
    
    MONGO_P -.-> ENC_REST
    VECTOR -.-> ENC_TRANSIT
    S3_DOCS -.-> KEY_MGMT
    CF_DIST -.-> ENC_TRANSIT
    
    MONGO_P -.-> AUDIT_TRAIL
    VECTOR -.-> RETENTION
    S3_DOCS -.-> GDPR

    %% Styling
    classDef dataSource fill:#e3f2fd
    classDef processing fill:#f3e5f5
    classDef storage fill:#e8f5e8
    classDef security fill:#ffebee
    classDef aws fill:#ff9800
    
    class USER,UPLOAD,FORMS,API_DATA dataSource
    class VALIDATE,SANITIZE,ENCRYPT,LOGIC,AI_PROC,TRANSFORM processing
    class MONGO_P,MONGO_S1,MONGO_S2,VECTOR,S3_DOCS storage
    class RBAC,RLS,ENC_REST,ENC_TRANSIT,AUDIT_TRAIL security
    class S3_UPLOADS,CF_DIST,CF_CACHE,IAM aws

5. CI/CD Security Pipeline Architecture

graph TB
    subgraph "Developer Environment"
        DEV[Developer Workstation]
        IDE[IDE/Code Editor]
        LOCAL[Local Testing]
    end

    subgraph "Source Control (GitHub)"
        REPO[Git Repository]
        BRANCH[Feature Branch]
        PR[Pull Request]
        MAIN[Main Branch]
    end

    subgraph "CI/CD Pipeline (GitHub Actions)"
        subgraph "Security Gates"
            TRIVY[Trivy Vulnerability Scan]
            TRUFFLEHOG[TruffleHog Secret Scan]
            SARIF[SARIF Security Reports]
        end
        
        subgraph "Quality Gates"
            LINT[ESLint/Code Quality]
            TEST[Unit/Integration Tests]
            BUILD[Build Verification]
        end
        
        subgraph "Compliance Gates"
            SOC2[SOC2 Compliance Check]
            AUDIT[Audit Trail Generation]
            APPROVE[Required Approvals]
        end
    end

    subgraph "Deployment Environment (Vercel)"
        subgraph "Staging"
            PREVIEW[Preview Deployment]
            STAGING_TEST[Staging Tests]
        end
        
        subgraph "Production"
            PROD_DEPLOY[Production Deployment]
            HEALTH[Health Checks]
            ROLLBACK[Rollback Capability]
        end
    end

    subgraph "Static Asset Pipeline (AWS)"
        S3_DEPLOY[S3 Asset Upload]
        CF_INVALIDATE[CloudFront Invalidation]
        ASSET_HEALTH[Asset Health Check]
    end

    subgraph "Monitoring & Security"
        MONITOR[Application Monitoring]
        SECURITY_MON[Security Monitoring]
        ALERTS[Alert System]
        LOGS[Centralized Logging]
    end

    %% Development flow
    DEV --> REPO
    IDE --> BRANCH
    LOCAL --> PR
    
    %% CI/CD triggers
    PR --> TRIVY
    PR --> TRUFFLEHOG
    PR --> LINT
    
    TRIVY --> SARIF
    TRUFFLEHOG --> SARIF
    LINT --> TEST
    TEST --> BUILD
    
    BUILD --> SOC2
    SOC2 --> AUDIT
    AUDIT --> APPROVE
    
    %% Deployment flow
    APPROVE --> PREVIEW
    PREVIEW --> STAGING_TEST
    
    MAIN --> PROD_DEPLOY
    MAIN --> S3_DEPLOY
    S3_DEPLOY --> CF_INVALIDATE
    CF_INVALIDATE --> ASSET_HEALTH
    
    PROD_DEPLOY --> HEALTH
    HEALTH --> MONITOR
    
    %% Security monitoring
    PROD_DEPLOY --> SECURITY_MON
    SECURITY_MON --> ALERTS
    MONITOR --> LOGS
    
    %% Emergency procedures
    ALERTS -.->|If Issues| ROLLBACK
    HEALTH -.->|Health Check Fail| ROLLBACK

    %% Styling
    classDef development fill:#e3f2fd
    classDef source fill:#f3e5f5
    classDef security fill:#ffebee
    classDef deployment fill:#e8f5e8
    classDef monitoring fill:#fff3e0
    classDef aws fill:#ff9800
    
    class DEV,IDE,LOCAL development
    class REPO,BRANCH,PR,MAIN source
    class TRIVY,TRUFFLEHOG,SARIF,SOC2,SECURITY_MON security
    class PREVIEW,STAGING_TEST,PROD_DEPLOY,HEALTH deployment
    class MONITOR,ALERTS,LOGS monitoring
    class S3_DEPLOY,CF_INVALIDATE,ASSET_HEALTH aws

Network Security Controls Summary

1. Boundary Definitions

  • Internet Boundary: Direct HTTPS connections to Vercel Edge Network and AWS CloudFront
  • Application Boundary: Vercel serverless infrastructure with built-in security
  • Data Boundary: Private VPC connections to databases with encryption
  • Administrative Boundary: GitHub and CI/CD systems with MFA and RBAC
  • Asset Boundary: AWS CloudFront + S3 for user-uploaded static content

2. Network Devices and Security Controls

  • Vercel Edge Network: Global load balancing, DDoS protection, SSL termination, serverless compute
  • AWS CloudFront: Global CDN for static assets with edge caching and SSL/TLS
  • Database Firewalls: MongoDB Atlas and Supabase built-in security controls
  • AWS S3: IAM-based access control, bucket policies, encryption at rest
  • GitHub Actions: Security scanning, secret detection, compliance validation

3. Network Zones

  • Public Zone: Internet-facing with direct HTTPS access
  • Edge Zone: Vercel edge infrastructure and AWS CloudFront
  • Application Zone: Serverless functions and applications
  • Data Zone: Private databases and storage systems
  • Management Zone: CI/CD and administrative systems

4. Data Flow Security

  • Encrypted in Transit: TLS 1.3 for all external communications
  • Encrypted at Rest: AES-256 encryption for all stored data
  • Authentication: Auth0 with MFA for user access
  • Authorization: JWT tokens with role-based access control
  • API Security: Rate limiting, input validation, secure headers

5. Critical System Inclusion

  • Primary Database: MongoDB Atlas with replica sets and backups
  • Vector Database: Supabase for AI/ML workloads
  • Object Storage: AWS S3 with lifecycle management and CloudFront distribution
  • AI Services: External API integrations with secure authentication
  • Static Assets: CloudFront-distributed user uploads and application assets

6. Physical Locations

  • Primary Region: US-West-1 (N. California) for AWS services
  • Vercel Infrastructure: Global edge network with US primary
  • MongoDB Atlas: US-West-1 region deployment
  • Supabase: US-West region deployment
  • Compliance: All data stored in US jurisdictions

7. Redundancy and Failover

  • Database Replication: MongoDB replica sets with automatic failover
  • CDN Redundancy: Vercel global edge network and CloudFront edge locations
  • Application Redundancy: Serverless auto-scaling and load balancing
  • Backup Systems: Automated daily backups with point-in-time recovery
  • Asset Availability: CloudFront global edge caching for static content

8. Monitoring and Logging

  • Security Monitoring: Continuous vulnerability scanning and threat detection
  • Application Monitoring: Real-time performance and error tracking via Vercel Analytics
  • Audit Logging: Comprehensive audit trail for all system activities
  • Compliance Reporting: Automated SOC 2 evidence collection
  • Asset Monitoring: CloudFront access logs and S3 access tracking

Compliance Alignment

This network architecture addresses the following SOC 2 Trust Service Criteria:

  • CC6.1 - Logical and physical access controls through multi-layered security
  • CC6.2 - System boundaries clearly defined with proper network segmentation
  • CC6.3 - Access control systems with Auth0, MFA, and RBAC implementation
  • CC6.7 - Data transmission security with end-to-end encryption
  • CC7.1 - System monitoring through comprehensive logging and alerting
  • CC7.2 - Security event detection via automated scanning and monitoring
  • A1.2 - Availability controls through redundancy and failover mechanisms

Document Prepared By: Dominick Pham, CTO
Review Date: July 25, 2025
Next Review: October 25, 2025
Classification: Internal Use - SOC2 Audit Evidence