C4 Model

The C4 model describes a system at four zoom levels — Context → Container → Component → Code — plus a Deployment view. Each level adds detail without losing the thread from the one above.

Level 1 — System Context

Who uses MyBotBox and what it talks to.

flowchart TB
    Builder([Builder<br/>designs & runs workflows])
    Admin([Org Admin<br/>members · permissions · billing])
    MBB[["MyBotBox<br/>visual AI workflow platform"]]
    Firebase[Firebase<br/>auth + realtime]
    LLM[LLM Providers<br/>17 adapters]
    Integrations[90+ Integrations<br/>Slack · Gmail · GitHub · …]
    Stripe[Stripe<br/>subscriptions + usage]

    Builder --> MBB
    Admin --> MBB
    MBB --> Firebase
    MBB --> LLM
    MBB --> Integrations
    MBB --> Stripe

Level 2 — Containers

The deployable units that make up the platform.

flowchart TB
    User([Builder])
    Edge[Route 53 → Firebase Hosting<br/>edge rewrite]

    subgraph CR ["Cloud Run — Next.js"]
        Web[Web App<br/>editor · dashboard · SSR]
        API[API Routes<br/>workflows · auth · billing]
        Exec[Executor<br/>DAG + 30 handlers]
    end

    Tasks[Cloud Tasks + 6 Functions<br/>async + polling]
    PG[(Cloud SQL<br/>PostgreSQL 17 + pgvector)]
    Redis[(Memorystore Redis<br/>rate-limit + cache)]
    GCS[(Cloud Storage)]
    Auth[Firebase Auth]
    FS[(Firestore<br/>realtime collab)]

    User --> Edge --> Web
    Web --> API
    API --> Exec
    API --> Tasks --> Exec
    API --> PG
    Exec --> PG
    API --> Redis
    API --> GCS
    Web --> Auth
    Web --> FS

Deployment — Google Cloud

Where the containers run. Staging and production are separate GCP projects; Firebase Hosting fronts each Cloud Run service.

flowchart TB
    User([User browser])
    DNS[AWS Route 53]
    FH[Firebase Hosting<br/>__session cookie only]

    subgraph STG ["Staging · ystudio-core · us-central1"]
        SRUN[Cloud Run: mybotbox-app<br/>min 1 · 80 concurrency]
        SVPC[VPC connector]
        SREDIS[(Memorystore Redis 7)]
        SSQL[(Cloud SQL · PostgreSQL 17)]
        STASK[Cloud Tasks + 6 Functions]
        SSEC[Secret Manager]
        SGCS[(Cloud Storage)]
    end

    subgraph PRD ["Production · mybotbox-prod · us-central1"]
        PRUN[Cloud Run: mybotbox-app]
        PSQL[(Cloud SQL · mybotbox-db)]
    end

    User --> DNS --> FH
    FH --> SRUN
    FH --> PRUN
    SRUN --> SVPC --> SREDIS
    SRUN --> SSQL
    SRUN --> STASK --> SRUN
    SRUN --> SSEC
    SRUN --> SGCS
    PRUN --> PSQL

Level 3 — Components (request security pipeline)

Every API request passes the same reusable gates before any business logic runs. See Request pipeline for the full walk-through.

flowchart LR
    Caller([Caller]) --> MW[Middleware<br/>session · CSP]
    MW --> Guards[API Guards<br/>auth + workspace access]
    Guards --> Authn[Auth<br/>Firebase verify]
    Guards --> RBAC[RBAC<br/>entity-scoped grant]
    Guards --> RL[Rate Limiter<br/>sliding window]
    Guards --> Handler[Route Handler<br/>Zod-validated]
    Handler --> Exec[Executor]

Level 4 — Code (the two contracts)

The lowest level: the type contracts everything plugs into. Every external service is a port with swappable adapters chosen by environment; every block is a handler behind one interface the executor dispatches to.

classDiagram
    direction LR

    class EmailProvider {
        <<port>>
        +send(message) Result
    }
    class SendgridAdapter
    class ResendAdapter
    class AzureAdapter
    EmailProvider <|.. SendgridAdapter
    EmailProvider <|.. ResendAdapter
    EmailProvider <|.. AzureAdapter

    class BlockHandler {
        <<port>>
        +canHandle(block) bool
        +execute(ctx, block) BlockOutput
    }
    class AgentHandler
    class FunctionHandler
    class ApiHandler
    class RouterHandler
    BlockHandler <|.. AgentHandler
    BlockHandler <|.. FunctionHandler
    BlockHandler <|.. ApiHandler
    BlockHandler <|.. RouterHandler

Adding a new provider or block type is additive — implement the port, register the adapter, and existing call sites are unchanged. This is what keeps the platform swappable and self-hostable.