System Architecture

Full system architecture with source file references for every component.

Overview

BrainstormRouter is a multi-tenant AI API gateway with built-in intelligence systems. Every box in the diagram below links to a real source file.

%%{init: {'theme': 'dark', 'themeVariables': {'primaryColor': '#d97706', 'lineColor': '#9494a8', 'primaryTextColor': '#e8e8ee'}}}%%
graph TB
    Client([Client / OpenAI SDK]) --> Gateway

    subgraph Gateway["Gateway — src/gateway/"]
        Auth["Auth\nsrc/gateway/auth.ts"]
        Boot["Boot\nsrc/gateway/boot.ts"]
        APIMount["API Mount\nsrc/gateway/api-mount.ts"]
    end

    Gateway --> API

    subgraph API["API Layer — src/api/"]
        Guardian["Guardian Middleware\nsrc/api/middleware/guardian.ts"]
        Routes["Hono Routes\nsrc/api/routes/"]
        Completions["Completions\nsrc/api/routes/completions.ts"]
    end

    API --> Router

    subgraph Router["Router — src/router/"]
        Bandit["Thompson Sampling\nsrc/router/model-bandit.ts"]
        CB["Circuit Breakers\nsrc/router/circuit-breaker.ts"]
        Cascade["Cascade\nsrc/router/model-cascade.ts"]
        AutoSelect["Auto-Selector\nsrc/router/model-auto-selector.ts"]
        SemanticCache["Semantic Cache\nsrc/router/model-semantic-cache.ts"]
        CostOpt["Cost Optimizer\nsrc/router/cost-optimizer.ts"]
    end

    Router --> Providers

    subgraph Providers["Provider Adapters"]
        Anthropic["Anthropic\nanthropic-messages"]
        OpenAI["OpenAI\nopenai-completions"]
        Google["Google\ngoogle-generative-ai"]
    end

    API --> Soul

    subgraph Soul["The Soul — src/agents/pi-embedded-runner/"]
        Run["Execution Loop\nrun.ts"]
        History["Turn Management\nhistory.ts"]
        Compact["Compaction\ncompact.ts"]
        Lanes["Session Routing\nlanes.ts"]
    end

    Soul --> Memory

    subgraph Memory["Memory — src/db/"]
        ExtractionQueue["Extraction Queue\nstores/memory-extraction-store.ts"]
        TenantALS["Tenant Context\ntenant-als.ts"]
        RLS["Row-Level Security\nschema/tenants.ts"]
    end

    subgraph Security["Security — src/security/"]
        RBAC["RBAC\nrbac.ts"]
        PII["PII Scanning\npii-scanner.ts"]
        Anomaly["Anomaly Detection\nanomaly.ts"]
        StreamGuard["Streaming Guardrails\nstreaming-guardrails.ts"]
        GovValidator["Governance Validator\ngovernance-validator.ts"]
        Airgap["PII Air Gap\npii-airgap.ts"]
        Egress["Egress Allowlist\negress-allowlist.ts"]
        SIEMExport["SIEM Export\nsiem-export.ts"]
    end

    API --> Security
    Providers -->|Streaming response| StreamGuard
    StreamGuard --> SIEMExport

Layer responsibilities

Gateway (`src/gateway/`)

The HTTP/WebSocket server. Handles TLS termination, authentication, boot sequencing, and hot config reload. Exposes OpenAI-compatible endpoints via openai-http.ts. The API mount handler (api-mount.ts) forwards /api/, /v1/, /auth/*, and /health to the Hono app.

API (`src/api/`)

Hono-based REST API. Every completion request passes through Guardian middleware for cost prediction and consumption protection before hitting the router. Key route groups: auth, billing, usage, provider keys, workspace files, and OpenAI-compatible completions.

Router (`src/router/`)

The routing core. Nine intelligence systems work together:

System	File	Role
Thompson Sampling	`model-bandit.ts`	Bayesian model selection
Auto-Selector	`model-auto-selector.ts`	Complexity-based routing
Performance Tracker	`intelligence/model-performance.ts`	Per-model quality metrics
Cascade	`model-cascade.ts`	Tier escalation on failure
Validity Scorer	`validity-scorer.ts`	Response quality scoring
Budget Forecaster	`budget-forecaster.ts`	Spend prediction + graceful degradation
Cost Optimizer	`cost-optimizer.ts`	Pareto-optimal price/quality frontier
Circuit Breaker	`circuit-breaker.ts`	Failure isolation
Semantic Cache	`model-semantic-cache.ts`	Deduplication of similar requests

The Soul (`src/agents/pi-embedded-runner/`)

The central intelligence engine. runEmbeddedPiAgent executes multi-turn agent runs with tool use, streaming, session management, and autonomous memory extraction. Key subsystems:

run.ts — execution loop
compact.ts — session compaction (300s timeout)
history.ts — turn management
lanes.ts — session routing

Security (`src/security/`)

Phased rollout across four trust levels (L0-L3). L0: event logging, TLS enforcement, rate limiting. L1: egress allowlists. L2: secrets management, policy engine, PII scanning, RBAC. L3: tenant isolation, session binding, anomaly detection.

Key security subsystems:

System	File	Role
Streaming Guardrails	`streaming-guardrails.ts`	Token-by-token output scanning with truncate/redact/replace
Governance Validator	`governance-validator.ts`	Deterministic keyword enforcement on streaming chunks
PII Scanner	`pii-scanner.ts`	Pluggable PII detection (built-in regex + external backends)
PII Air Gap	`pii-airgap.ts`	Scrub → tokenize → external process → rehydrate
Egress Allowlist	`egress-allowlist.ts`	Per-service outbound domain restrictions
SIEM Export	`siem-export.ts`	CEF + ECS JSON structured security event export

See Streaming Security: Code vs Reality for the full streaming interception pipeline.

Production topology

%%{init: {'theme': 'dark', 'themeVariables': {'primaryColor': '#d97706', 'lineColor': '#9494a8', 'primaryTextColor': '#e8e8ee'}}}%%
graph LR
    CF["Cloudflare\napi.brainstormrouter.com"] --> ALB["ALB\nHTTPS:443"]
    ALB --> ECS["ECS Fargate\nPort 18790"]
    ECS --> RDS["RDS Postgres 16\npgvector"]
    ECS --> Redis["ElastiCache\nRedis Serverless"]
    ECS --> EFS["EFS\n/home/node/.brainstormrouter"]
    ECS --> SM["Secrets Manager\nProvider API keys"]

Component	Detail
Region	us-east-1
Container port	18790
Database	Postgres 16 with pgvector (db.t4g.micro)
Cache	ElastiCache Serverless
Persistent storage	EFS at `/home/node/.brainstormrouter`
Secrets	AWS Secrets Manager (`brainstorm-router/production/*`)
Deploys	Automatic via GitHub Actions on push to `main`

System Architecture

Overview

Layer responsibilities

Gateway (src/gateway/)

API (src/api/)

Router (src/router/)