C4 模型

C4 模型从四个缩放层级描述系统——上下文 → 容器 → 组件 → 代码——以及一个部署视图。每个层级在不脱离上一层级脉络的前提下逐步深入细节。

第 1 层——系统上下文

谁在使用 MyBotBox，以及它与哪些外部系统交互。

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

第 2 层——容器

构成平台的可部署单元。

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

部署——Google Cloud

容器的运行位置。预发布环境与生产环境使用独立的 GCP 项目；Firebase Hosting 分别为每个 Cloud Run 服务提供前端接入。

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

第 3 层——组件（请求安全管道）

每个 API 请求在执行任何业务逻辑之前，都会经过相同的可复用关卡。完整流程请参阅请求管道。

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]

第 4 层——代码（两个契约）

最底层：所有模块接入的类型契约。每个外部服务都是一个端口，通过环境变量选择可替换的适配器；每个块都是一个处理器，实现同一接口并由执行器进行调度。

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

新增提供商或块类型是累加式的——只需实现端口、注册适配器，现有调用方无需任何改动。这正是保持平台可替换性和自托管能力的关键所在。