# Network Diagram (/docs/internal/network-diagram) 

# Company Network Architecture Diagram [#company-network-architecture-diagram]

## Infrastructure Overview [#infrastructure-overview]

Your company operates a fully remote, cloud-native architecture built on AWS with multiple environments and sophisticated security protocols.

## Network Architecture Diagram [#network-architecture-diagram]

```mermaid
graph TB
    %% Remote Team Access
    subgraph "Remote Team Access"
        RT1[Remote Developer 1]
        RT2[Remote Developer 2]
        RTN[Remote Team N...]
    end

    %% Internet Gateway & DNS
    subgraph "DNS & CDN Layer"
        R53[Route 53 DNS]
        CF[CloudFront CDN]
        CERT[AWS Certificate Manager]
    end

    %% Load Balancers & API Gateway
    subgraph "Load Balancing & API Gateway"
        ALB[Application Load Balancer<br/>HTTP/HTTPS]
        APIGW[API Gateway v2<br/>Lambda Proxy]
        NLBINT[Internal Network LB]
    end

    %% Core Infrastructure (Replicated across all environments)
    subgraph "AWS Infrastructure - eu-west-2"
        subgraph "VPC (Multi-AZ)"
            subgraph "Public Subnets (3 AZs)"
                NAT1[NAT Gateway AZ-1]
                NAT2[NAT Gateway AZ-2]
                NAT3[NAT Gateway AZ-3]
            end
            
            subgraph "Private Subnets (3 AZs)"
                subgraph "Application Services"
                    WEBAPP1[Dashboard Service<br/>Merchant Portal]
                    WEBAPP2[Checkout Service<br/>Payment Processing]
                    WEBAPP3[Demo Store Service<br/>Customer Interface]
                    WEBAPP4[SDK Service<br/>JavaScript Distribution]
                    WEBAPP5[Documentation Service<br/>API Docs & Guides]
                    API1[Core API Service<br/>Business Logic]
                    API2[Microservices<br/>Event Processing]
                    AUTH[Authentication Service<br/>Identity & Access]
                end
            end
            
            subgraph "Isolated Subnets (3 AZs)"
                subgraph "Database Tier"
                    DDB[DynamoDB<br/>Multi-Region]
                    POSTGRES[PostgreSQL RDS<br/>Multi-AZ]
                    MONGO[MongoDB Atlas]
                end
                
                subgraph "Message Queue"
                    MSK[Managed Kafka<br/>Multi-AZ]
                    SQS1[Jobs Queue]
                    SQS2[Merchant Webhook Queue]
                    SQS3[Dead Letter Queues]
                end
                
                subgraph "Storage"
                    S3MAIN[S3 Buckets<br/>KMS Encrypted]
                    S3STATIC[Static Assets Bucket]
                    S3SDK[SDK Files Bucket]
                end
            end
        end
    end

    %% External Integrations
    subgraph "External Service Integrations"
        subgraph "Payment Processors"
            STRIPE[Stripe API<br/>TLS 1.3]
            SQUARE[Square API<br/>TLS 1.3]
            SHUTTLE[Shuttle API<br/>TLS 1.3]
            BRIDGERPAY[BridgerPay API<br/>TLS 1.3]
            ASIAPAY[AsiaPay API<br/>TLS 1.3]
            PCIPROXY[PCI Proxy<br/>TLS 1.3]
        end
        
        subgraph "Communication Services"
            TWILIO[Twilio SMS/Voice<br/>TLS 1.3]
            SLACK[Slack Webhooks<br/>TLS 1.3]
            EMAIL[AWS SES<br/>DMARC/SPF/DKIM]
        end
        
        subgraph "Analytics & Monitoring"
            POSTHOG[PostHog Analytics<br/>TLS 1.3]
            HUBSPOT[HubSpot CRM<br/>TLS 1.3]
            MAILCHIMP[Mailchimp Marketing<br/>TLS 1.3]
        end
        
        subgraph "Authentication Providers"
            GOOGLE[Google OAuth<br/>TLS 1.3 + PKCE]
            MICROSOFT[Microsoft Azure AD<br/>TLS 1.3 + PKCE]
        end
        
        subgraph "Development Tools"
            README[ReadMe API Docs<br/>TLS 1.3]
            OPENEXCHANGE[Open Exchange Rates<br/>TLS 1.3]
        end
    end

    %% Security Components
    subgraph "Security & Compliance"
        subgraph "AWS Security Services"
            KMS[AWS KMS<br/>AES-256]
            SECRETS[AWS Secrets Manager<br/>Encrypted]
            IAM[AWS IAM Roles & Policies]
            SG[Security Groups<br/>Firewall Rules]
        end
        
        subgraph "Monitoring & Compliance"
            CW[CloudWatch Logs & Metrics]
            CT[CloudTrail Audit Logs]
            CONFIG[AWS Config Compliance]
            GUARD[GuardDuty Threat Detection]
        end
    end

    %% Mobile & Desktop Clients
    subgraph "Client Applications"
        MOBILE[Mobile App<br/>React Native]
        DESKTOP[Desktop App<br/>Electron]
        BROWSER[Web Browsers<br/>Modern Browsers]
    end

    %% Connections with Security Protocols
    RT1 --> |HTTPS/TLS 1.3<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>Certificate Pinning| CF
    RT2 --> |HTTPS/TLS 1.3<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>Certificate Pinning| CF
    RTN --> |HTTPS/TLS 1.3<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>Certificate Pinning| CF
    
    CF --> |DNS over HTTPS DoH<br/>DNSSEC| R53
    CF --> |HTTP/2<br/>TLS 1.3<br/>HSTS Header| ALB
    
    ALB --> |HTTP/1.1<br/>Internal TLS 1.2<br/>AES-256-CBC| WEBAPP1
    ALB --> |HTTP/1.1<br/>Internal TLS 1.2<br/>AES-256-CBC| WEBAPP2
    ALB --> |HTTP/1.1<br/>Internal TLS 1.2<br/>AES-256-CBC| WEBAPP3
    
    APIGW --> |AWS SigV4<br/>Internal TLS 1.2<br/>AES-256-GCM| API1
    APIGW --> |AWS SigV4<br/>Internal TLS 1.2<br/>AES-256-GCM| AUTH
    
    API1 --> |DynamoDB Protocol<br/>AES-256 KMS Encryption<br/>IAM SigV4| DDB
    API1 --> |PostgreSQL Protocol<br/>SSL/TLS 1.2<br/>AES-256 RDS Encryption| POSTGRES
    API1 --> |Kafka Protocol<br/>SASL/SCRAM-SHA-512<br/>TLS 1.2| MSK
    API2 --> |Kafka Protocol<br/>SASL/SCRAM-SHA-512<br/>TLS 1.2| MSK
    API2 --> |DynamoDB Protocol<br/>AES-256 KMS Encryption<br/>IAM SigV4| DDB
    
    AUTH --> |DynamoDB Protocol<br/>AES-256 KMS Encryption<br/>IAM SigV4| DDB
    AUTH --> |SQS Protocol<br/>AES-256 KMS Encryption<br/>IAM SigV4| SQS1
    AUTH --> |AWS Secrets Manager API<br/>AES-256 KMS Encryption<br/>IAM SigV4| SECRETS
    
    %% External Service Connections with Full Security Stack
    API1 --> |HTTPS/TLS 1.3<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>Webhook Signature HMAC-SHA256| STRIPE
    API1 --> |HTTPS/TLS 1.3<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>OAuth 2.0 Bearer Token| SQUARE
    API1 --> |HTTPS/TLS 1.3<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>API Key + Signature| SHUTTLE
    API1 --> |HTTPS/TLS 1.3<br/>ChaCha20-Poly1305<br/>API Key Authentication| TWILIO
    
    WEBAPP1 --> |HTTPS/TLS 1.3<br/>OAuth 2.0 + PKCE<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>JWT RS256 Tokens| GOOGLE
    WEBAPP1 --> |HTTPS/TLS 1.3<br/>OAuth 2.0 + PKCE<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>JWT RS256 Tokens| MICROSOFT
    
    API1 --> |HTTPS/TLS 1.3<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>Webhook HMAC-SHA256| BRIDGERPAY
    API1 --> |HTTPS/TLS 1.3<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>Digital Signature Verification| ASIAPAY
    API1 --> |HTTPS/TLS 1.3<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>Basic Auth + TLS Client Cert| PCIPROXY
    
    API1 --> |HTTPS/TLS 1.3<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>Bearer Token Auth| POSTHOG
    API1 --> |HTTPS/TLS 1.3<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>Private App Token| HUBSPOT
    
    %% Client Application Connections
    MOBILE --> |HTTPS/TLS 1.3<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>Certificate Pinning<br/>App Attestation| CF
    DESKTOP --> |HTTPS/TLS 1.3<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>Certificate Pinning<br/>Code Signing Verification| CF
    BROWSER --> |HTTPS/TLS 1.3<br/>ECDHE-RSA-AES256-GCM-SHA384<br/>HSTS + CSP Headers| CF
    
    %% Internal Security Service Connections
    ALB --> |AWS Security Groups<br/>Stateful Firewall Rules<br/>Port-based Filtering| SG
    API1 --> |AWS IAM<br/>AssumeRole STS<br/>Temporary Credentials| IAM
    AUTH --> |AWS IAM<br/>AssumeRole STS<br/>Temporary Credentials| IAM
    S3MAIN --> |AWS KMS<br/>AES-256 Envelope Encryption<br/>CMK Rotation| KMS
    DDB --> |AWS KMS<br/>AES-256 Envelope Encryption<br/>CMK Rotation| KMS
    
    %% Email Security
    API1 --> |SMTP/TLS 1.2<br/>DKIM RSA-2048<br/>SPF Record Validation<br/>DMARC p=reject| EMAIL
```

## Security Protocols & Encryption [#security-protocols--encryption]

### Transport Layer Security [#transport-layer-security]

* **TLS 1.3** for all external API communications with forward secrecy
* **Cipher Suites**: ECDHE-RSA-AES256-GCM-SHA384, ChaCha20-Poly1305
* **HTTPS** enforced across all web applications with HSTS headers
* **Certificate Management** via AWS Certificate Manager with auto-renewal
* **Certificate Pinning** for mobile and desktop applications

### Data Encryption [#data-encryption]

* **At Rest**: AES-256 envelope encryption using AWS KMS with customer-managed keys
* **In Transit**: TLS 1.3 for external, TLS 1.2+ for internal AWS services
* **Database Encryption**:
  * DynamoDB with KMS encryption and key rotation
  * PostgreSQL RDS with AES-256 encryption
  * Kafka with SASL/SCRAM-SHA-512 authentication

### Authentication & Authorization [#authentication--authorization]

* **OAuth 2.0 with PKCE** for external identity providers (Google, Microsoft)
* **JWT Tokens** with RS256 signing (RSA-2048 keys) for API authentication
* **AWS IAM Roles** with least-privilege access and temporary credentials
* **Multi-Factor Authentication** enforced for AWS console access
* **API Authentication**: Bearer tokens, HMAC-SHA256 signatures, digital signatures

### Network Security [#network-security]

* **VPC Security Groups** acting as stateful firewalls with port-based filtering
* **NACLs** for subnet-level network filtering
* **Private Subnets** for all application and database tiers
* **NAT Gateways** for secure outbound internet access
* **AWS WAF** for application-layer protection

### Message Security [#message-security]

* **Webhook Security**: HMAC-SHA256 signature verification
* **Email Security**: DKIM RSA-2048, SPF records, DMARC p=reject
* **Queue Encryption**: SQS messages encrypted with KMS
* **Event Streaming**: Kafka with TLS 1.2 and SASL authentication

## Application Architecture [#application-architecture]

### Frontend Applications [#frontend-applications]

* **Dashboard**: Next.js application for merchant management
* **Checkout**: Payment processing interface
* **Demo Store**: Customer-facing demo application
* **Mobile App**: React Native cross-platform application
* **Desktop App**: Electron-based desktop client

### Backend Services [#backend-services]

* **API Gateway**: Serverless API routing and authentication
* **Core API Service**: Business logic and data processing
* **Authentication Service**: Identity management and access control
* **Microservices**: Event processing and specialized functions
* **Blue/Green Deployments**: Zero-downtime deployments with automated rollback

### Data Layer [#data-layer]

* **DynamoDB**: NoSQL database for user sessions, auth, and payments
* **PostgreSQL RDS**: Relational data with Multi-AZ deployment
* **MongoDB**: Document store for specific use cases
* **Apache Kafka (MSK)**: Event streaming and message processing

### Integration Layer [#integration-layer]

* **Payment Processors**: Stripe, Square, Shuttle, BridgerPay, AsiaPay
* **Communication**: Twilio (SMS/Voice), AWS SES (Email), Slack
* **Analytics**: PostHog, HubSpot
* **Authentication**: Google OAuth, Microsoft Azure AD

## Deployment Environments [#deployment-environments]

This entire architecture is replicated across multiple isolated environments:

### Production [#production]

* **Region**: eu-west-2 (London)
* **Multi-AZ**: 3 Availability Zones
* **NAT Strategy**: One per AZ for high availability
* **Retention**: Resources retained on stack deletion
* **Domain**: `*.handsin.com`

### Staging [#staging]

* **Region**: eu-west-2 (London)
* **Multi-AZ**: 3 Availability Zones
* **Purpose**: Pre-production testing and validation
* **Domain**: `*.staging.handsin.com`

### Development [#development]

* **Region**: eu-west-2 (London)
* **Single NAT**: Cost-optimized configuration
* **Purpose**: Development and integration testing
* **Domain**: `*.development.handsin.com`

### Sandbox [#sandbox]

* **Region**: eu-west-2 (London)
* **Purpose**: Sandbox testing environment
* **Domain**: `*.sandbox.handsin.com`

### Local Development [#local-development]

* **Docker Compose**: Local service orchestration
* **Port Mapping**: Standardized ports across services
* **Hot Reload**: Development productivity features
* **Domain**: `localhost` with different ports

## Monitoring & Observability [#monitoring--observability]

### Application Monitoring [#application-monitoring]

* **CloudWatch**: Metrics, logs, and alarms
* **PostHog**: User analytics and feature flags

### Infrastructure Monitoring [#infrastructure-monitoring]

* **CloudWatch**: Infrastructure metrics and logs
* **AWS Config**: Compliance and configuration monitoring
* **GuardDuty**: Threat detection and security monitoring

### Deployment Monitoring [#deployment-monitoring]

* **CodeDeploy**: Blue/green deployment monitoring
* **CloudWatch Alarms**: Automated rollback triggers
* **SNS Notifications**: Deployment status alerts

## Remote Team Considerations [#remote-team-considerations]

### Access Patterns [#access-patterns]

* **Zero-Trust Architecture**: All access through authenticated endpoints
* **VPN-Free**: Direct internet access through CloudFront and ALB
* **Multi-Region**: Disaster recovery and performance optimization

### Development Workflow [#development-workflow]

* **GitOps**: Infrastructure as Code with SST
* **CI/CD**: Automated testing and deployment pipelines
* **Environment Parity**: Consistent environments across stages

### Security for Remote Work [#security-for-remote-work]

* **IAM Roles**: Granular permissions per team member
* **MFA Required**: Multi-factor authentication enforced
* **Audit Logging**: All access logged via CloudTrail
* **Secret Management**: Centralized secrets via AWS Secrets Manager

This architecture provides a robust, secure, and scalable foundation for your fully remote team while maintaining high availability, security, and compliance standards.