C4モデル

C4モデルは、システムを4つのズームレベル — Context → Container → Component → Code — とDeploymentビューで記述します。各レベルは、上位レベルとの繋がりを保ちながら詳細を追加していきます。

レベル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

Deployment — 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 — コード（2つのコントラクト）

最下位レベル：すべてのものが接続する型コントラクト。すべての外部サービスは環境によって選択されるスワップ可能なアダプターを持つポートであり、すべてのブロックはエグゼキューターがディスパッチする1つのインターフェースの背後にあるハンドラーです。

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

新しいプロバイダーやブロックタイプの追加は追加的です — ポートを実装し、アダプターを登録するだけで、既存の呼び出し箇所は変更不要です。これにより、プラットフォームのスワップ可能性とセルフホスティング対応が維持されます。