System Architecture — C4 Model

Visual models organized by zoom level, following the C4 model (Context → Containers → Components → Code). Each level targets a different stakeholder persona and abstracts away implementation details progressively as you zoom in.

Level 1: Context (Business Stakeholders & Product Managers)

Shows how SCHEMABOUND fits into your broader ecosystem — external systems, identity providers, and data layers. This is the “elevator pitch” architecture diagram that explains what SCHEMABOUND connects to without revealing internal implementation.

graph LR
    LLM["LLM<br>Agent"] --> SB["SCHEMABOUND<br>Middleware"]
    SB --> IdP["Identity<br>Provider (BYOI)"]
    SB --> DB["Data<br>Layer"]
    SB --> SIEM["SIEM<br>Platform"]

What it shows at a glance: SCHEMABOUND sits between your LLM Agent and four external systems — identity providers (BYOI), data stores, audit platforms, and telemetry backends. No internal implementation details are exposed at this level; those appear in the Container diagram below.

Level 2: Container (Frontend/Backend Developers & DevOps)

Illustrates the main boundaries and high-level data flow within SCHEMABOUND itself. This level is relevant when you’re configuring deployment, tuning workers, or integrating with observability platforms.

graph TB
    LLM["LLM<br>Agent"] --> gRPC["gRPC Server<br/>(:50051)"]
    IdP["Identity<br>Provider"] -->|"JWT/OIDC"| gRPC
    DB["Database"] -->|"Query results"| gRPC
    gRPC --> EB["Global<br>EventBus"]
    EB --> W["Data Resilience Workers<br/>Auto-Rewind + Chain Integrity"]

Key boundaries:

• gRPC Server accepts ExecuteStepRequest and SubmitPlanRequest from LLM Agents; validates JWT/OIDC tokens via BYOI identity layer
• Global EventBus is the typed event bus that fans out LlmToolCallAuditRecorded events to all registered handlers (audit log, query metrics, session activity)
• Data Resilience Workers run in background: Auto-Rewind handles schema topology refresh and historical replay; Chain Integrity verifies hash-chain anchor depths

Level 3: Component (Backend Engineers)

Maps internal structures and responsibilities within the SCHEMABOUND runtime. This level is relevant when you’re implementing custom handlers, extending the injection guard, or debugging query execution paths.

graph LR
    IG["Injection<br>Guard"] --> LM["LocalMapper<br>(SQLite)"]
    RC["Runtime Context"] --> TC["Tool Contract Policy Engine"]
    TC -->|"Intent: read/write/admin"| LM
    TC --> TM["TcpMapper<br>(Remote TCP/JSON-RPC)"]
    LM -->|QueryExecuted| AL["AuditLogHandler<br>(OCSF v1.1)"]
    TM -->|QueryExecuted| QM["QueryMetricsHandler<br>(AAU tracking)"]
    TC --> SA["SessionActivityHandler<br>(per-session memory)"]

Component responsibilities:

• Injection Guard filters traffic against regex pattern libraries (jailbreak_token, sql_template_injection) before the request reaches mappers; policy controlled by SCHEMABOUND_INJECTION_POLICY (observe vs. block)
• LocalMapper/ TcpMapper execute queries via SQLite or remote TCP transport with configurable timeouts (DEFAULT_TIMEOUT_SECONDS = 30s)
• Tool Contract Policy Engine classifies intent (Read=1x, Write=3x, Governed=5x AAU weight) and enforces governance rules per tool call
• Chain of Responsibility handlers receive QueryExecuted events: AuditLogHandler produces OCSF v1.1 records, QueryMetricsHandler tracks AAU totals, SessionActivityHandler captures per-session memory entries

Level 4: Code (Core Contributors)

Reserved for core contributors seeking exact implementation details — class hierarchies, trait implementations, and payload structures inside the sb-migrate compilation path. This level uses UML-style diagrams to show how domain objects transform into migration plan steps.

classDiagram
    TableSnapshot --> MigrationPlan : diff_snapshots()
    MigrationPlan *-- MigrationStep : contains
    MigrationParser --> MigrationPlan : parses
    
    class TableSnapshot {
        +columns: Vec<ColumnDef>
        +indexes: Vec<IndexDef>
        +diff_against(other) MigrationPlan
    }
    
    class MigrationPlan {
        +id: String
        +direction: MigrationDirection
        +steps: Vec<MigrationStep>
        +serialize() JSON
    }
    
    class MigrationStep {
        +action: StepAction
        +table_name: String
        +sql_dialect: DatabaseDialect
    }

Key transformations:

• TableSnapshot is produced by the MirrorProvider during schema introspection; contains columns, indexes, unique constraints, and field mappings with ORM convention detection (Hibernate vs EntityFramework)
• diff_snapshots() computes a MigrationPlan containing ordered MigrationStep payloads tagged with DatabaseDialect (PostgreSQL, MySQL, SQLite, Dolt)
• MigrationParser reads JSON from stdin via the sb-migrate binary protocol, validates dependency acyclicity, and emits typed migration steps for execution

Using These Diagrams in Documentation

When referencing SCHEMABOUND architecture in backlog issues or PR descriptions:

• Use Level 1 diagrams when explaining to non-engineers what SCHEMABOUND connects to
• Use Level 2 diagrams when configuring deployment, workers, or observability integration
• Use Level 3 diagrams when implementing custom handlers or debugging query paths
• Use Level 4 diagrams only in core contributor documentation — never expose this level in user-facing docs

Render these diagrams locally with mdbook (Mermaid is configured via mdbook-mermaid preprocessor) or paste into any Mermaid-compatible viewer.