flowchart TB
    IOS["iOS App"] & WEB["Web App"]
    GLB["Global HTTPS LB · TLS 1.3"]
    ARMOR["Cloud Armor WAF"]

    IOS & WEB --> GLB --> ARMOR

    subgraph VPC["GCP VPC — Private Network"]
        direction TB
        ARMOR --> API & WEBSERV

        API["beaver-api\n25+ endpoints\nmin:2 max:100"]
        WEBSERV["beaver-web"]

        API -->|"publish"| TOPICS
        WEBHOOK -->|"publish"| TOPICS

        TOPICS["Pub/Sub Topics\naccount · transfer · trade\nnotification · rebalance · recurring"]

        TOPICS -->|"subscribe"| WORKER & NOTIFIER
        TOPICS -.->|"failed"| DLQ["Dead Letter Topics\nP1 alert"]

        WORKER["beaver-worker\nTrades · Rebalance\nReconciliation"]
        NOTIFIER["beaver-notifier\nPush · Email · SMS"]
        SCHED["beaver-scheduler\nRecurring deposits\nDrift detection"]

        SCHED -->|"publish"| TOPICS

        API -->|"writes"| PRIMARY
        API -->|"reads"| REPLICA
        API <-->|"sessions · cache"| REDIS
        WORKER -->|"writes"| PRIMARY
        WORKER <-->|"locks"| REDIS
        SCHED -->|"reads"| REPLICA
        WEBHOOK -->|"dedup"| REDIS

        PRIMARY[("Cloud SQL Primary\nPostgreSQL 16 HA\n4vCPU · 16GB · 100GB")]
        REPLICA[("Read Replica\n2vCPU · 8GB")]
        REDIS[("Redis 7 HA 2GB")]
    end

    API <-->|"accounts · trading"| ALPACA
    API <-->|"bank link"| PLAID
    WORKER -->|"trade exec"| ALPACA

    ALPACA["Alpaca Broker API"] -->|"webhooks"| WEBHOOK
    PLAID["Plaid"] -->|"webhooks"| WEBHOOK
    P529["529 Provider"] -->|"webhooks"| WEBHOOK
    PIRA["IRA Custodian"] -->|"webhooks"| WEBHOOK
    WEBHOOK["beaver-webhook"]

    NOTIFIER --> APNS["APNs"] & SG["SendGrid"] & TW["Twilio"]

    API -.-> KMS["Cloud KMS"] & SECRETS["Secret Mgr"]
    SCHED --> GCS["Cloud Storage\n7yr WORM audit"]
    API -.-> OBS["Logging · Monitoring · Trace"]
    CICD["GitHub Actions\nCanary deploys"] -.-> API & WORKER & WEBHOOK & NOTIFIER

    style VPC fill:#f6f8fa,stroke:#d0d7de,stroke-width:2px
    style TOPICS fill:#F39C12,stroke:#D68910,color:#000
    style DLQ fill:#E74C3C,stroke:#C0392B,color:#fff
    style API fill:#34A853,stroke:#1E7E34,color:#fff
    style WEBSERV fill:#34A853,stroke:#1E7E34,color:#fff
    style WORKER fill:#34A853,stroke:#1E7E34,color:#fff
    style NOTIFIER fill:#34A853,stroke:#1E7E34,color:#fff
    style SCHED fill:#34A853,stroke:#1E7E34,color:#fff
    style WEBHOOK fill:#34A853,stroke:#1E7E34,color:#fff
    style PRIMARY fill:#8E44AD,stroke:#6C3483,color:#fff
    style REPLICA fill:#8E44AD,stroke:#6C3483,color:#fff
    style REDIS fill:#8E44AD,stroke:#6C3483,color:#fff
    style ALPACA fill:#5DADE2,stroke:#2E86C1,color:#fff
    style PLAID fill:#5DADE2,stroke:#2E86C1,color:#fff
    style P529 fill:#5DADE2,stroke:#2E86C1,color:#fff
    style PIRA fill:#5DADE2,stroke:#2E86C1,color:#fff
    style GLB fill:#E8913A,stroke:#B06D2B,color:#fff
    style ARMOR fill:#E8913A,stroke:#B06D2B,color:#fff
    style IOS fill:#4A90D9,stroke:#2C5F8A,color:#fff
    style WEB fill:#4A90D9,stroke:#2C5F8A,color:#fff
    style KMS fill:#566573,stroke:#2C3E50,color:#fff
    style SECRETS fill:#566573,stroke:#2C3E50,color:#fff
    style GCS fill:#566573,stroke:#2C3E50,color:#fff
    style OBS fill:#566573,stroke:#2C3E50,color:#fff
    style CICD fill:#2ECC71,stroke:#27AE60,color:#fff
    style APNS fill:#AF7AC5,stroke:#8E44AD,color:#fff
    style SG fill:#AF7AC5,stroke:#8E44AD,color:#fff
    style TW fill:#AF7AC5,stroke:#8E44AD,color:#fff
        

sequenceDiagram
    actor User as iOS User
    participant API as beaver-api
    participant ALP as Alpaca API
    participant PS as Pub/Sub
    participant WH as beaver-webhook
    participant WK as beaver-worker
    participant DB as Cloud SQL
    participant RD as Redis
    participant NT as beaver-notifier

    User->>API: POST /transactions/deposit ($500)
    API->>DB: Create pending transaction
    API->>ALP: POST /transfers (ACH INCOMING)
    ALP-->>API: transfer_id, QUEUED
    API->>PS: publish transfer.initiated
    API-->>User: 200 OK — deposit pending

    Note over ALP: ACH processing (1-3 business days)

    ALP->>WH: Webhook: transfer COMPLETE
    WH->>RD: Dedup check (event_id)
    WH->>DB: Log webhook
    WH->>PS: publish transfer.completed

    PS->>WK: subscribe: transfer.completed
    WK->>RD: Acquire distributed lock (fund_id)
    WK->>DB: Update transaction + create ledger entry

    Note over WK: Auto-invest per fund allocation

    WK->>ALP: Buy $300 VTI (60%)
    WK->>ALP: Buy $150 VXUS (30%)
    WK->>ALP: Buy $50 BND (10%)
    WK->>RD: Release lock
    WK->>PS: publish notification.send

    PS->>NT: subscribe: notification.send
    NT-->>User: Push: "$500 deposited and invested!"
        

flowchart TB
    subgraph SERVICES["Cloud Run Services"]
        API["beaver-api\nreads + writes"]
        WORKER["beaver-worker\nwrites only"]
        SCHED["beaver-scheduler\nreads only"]
    end

    subgraph POOL["PgBouncer Connection Pooling"]
        PG1["Sidecar\npool=transaction\n10 conn/instance"]
        PG2["Sidecar"]
        PG3["Sidecar"]
    end

    subgraph CLOUDSQL["Cloud SQL PostgreSQL 16"]
        PRIMARY[("PRIMARY — HA\n4 vCPU · 16GB · 100GB\nCMEK · PITR 30d")]
        REPLICA[("READ REPLICA\n2 vCPU · 8GB\nlag less than 1s")]
        PRIMARY -->|"async replication"| REPLICA
    end

    subgraph SCHEMAS["Database Schemas"]
        PUB["public\nusers · funds · transactions\nledger_entries · beneficiaries"]
        PII["pii\nuser_ssn · beneficiary_ssn\nrestricted access · audited"]
        AUD["audit\naudit_log · webhook_log\nINSERT only"]
        AN["analytics\nmaterialized views\ndaily aggregations"]
    end

    API --> PG1 --> PRIMARY
    API -.-> REPLICA
    WORKER --> PG2 --> PRIMARY
    SCHED --> PG3 --> REPLICA

    PRIMARY --- PUB & PII & AUD & AN

    KMS["Cloud KMS"] -.->|"CMEK"| PRIMARY
    GCS["Cloud Storage 7yr WORM"] -.->|"nightly export"| AUD

    style PRIMARY fill:#8E44AD,stroke:#6C3483,color:#fff
    style REPLICA fill:#8E44AD,stroke:#6C3483,color:#fff
    style PII fill:#E74C3C,stroke:#C0392B,color:#fff
    style AUD fill:#F39C12,stroke:#D68910,color:#000
    style PUB fill:#34A853,stroke:#1E7E34,color:#fff
    style AN fill:#5DADE2,stroke:#2E86C1,color:#fff
    style KMS fill:#566573,stroke:#2C3E50,color:#fff
    style GCS fill:#566573,stroke:#2C3E50,color:#fff
        

flowchart LR
    subgraph G1["Gate 1: Quality"]
        LINT["golangci-lint"] --> VET["go vet"] --> TEST["go test -race\ncoverage 80%+"]
    end
    subgraph G2["Gate 2: Security"]
        VULN["govulncheck"] --> TRIVY["Trivy scan\nCRITICAL + HIGH"]
    end
    subgraph G3["Gate 3: Build"]
        BUILD["Build 4 images\nin parallel"] --> AR["Push to\nArtifact Registry"]
    end
    subgraph G4["Gate 4: Staging"]
        MIG["Migrations"] --> DEP["Deploy all\nservices"] --> E2E["E2E tests"]
    end
    subgraph G5["Gate 5: Canary"]
        CAN["Canary deploy\n10% traffic"] --> SOAK["5-min soak\nmonitor errors"]
    end
    subgraph G6["Gate 6: Prod"]
        APR["Manual\napproval"] --> MIGP["Migrations"] --> ROLL["Full\nrollout"]
    end

    PUSH["git push\nmain"] --> G1 & G2
    G1 & G2 --> G3 --> G4 --> G5 --> G6

    style PUSH fill:#4A90D9,stroke:#2C5F8A,color:#fff
    style APR fill:#E74C3C,stroke:#C0392B,color:#fff
    style ROLL fill:#34A853,stroke:#1E7E34,color:#fff
    style E2E fill:#F39C12,stroke:#D68910,color:#000
    style CAN fill:#F39C12,stroke:#D68910,color:#000
        

timeline
    title Beaver Infrastructure Evolution
    section Bootstrap
        Solo founder : Cloud Run free tier
                     : Neon PostgreSQL free
                     : $0/mo
    section MVP (1K users)
        Solo founder : Cloud SQL micro
                 : Single Cloud Run service
                 : ~$14/mo
    section Growth (10K users)
        5-8 engineers : Add Redis + Cloud Armor
                      : Terraform IaC
                      : ~$120/mo
    section Scale (100K users)
        10-15 engineers : 6 Cloud Run services
                        : Pub/Sub event bus
                        : HA + Read replica
                        : SOC2 Type II
                        : ~$1,400/mo
    section Next (500K+ users)
        20+ engineers : Evaluate GKE
                      : Multi-region
                      : BigQuery + ML
                      : $2,500+/mo