Integration Map: 12 Real Integrations¶

The pitch in one line

Every integration is implemented, tested, and evidenced -- not a single stub.

At a glance¶

Data & State AI & LLM Frontend & Streaming Infra & Ops

Integration	What it does	Tests / evidence
PostgreSQL	8 tables: OLTP state, metrics catalog, layouts, SQL audit log	`db/init.sql` (schema DDL)
Redis	3 roles: KPI hot cache, pub/sub fan-out, widget data cache	`redis_client.py`, `cache.py`
Databricks	3 live Asurion metrics, pooled client, health probe	`databricks/client.py`

Integration	What it does	Tests / evidence
AWS Bedrock	2 tiers, 4 call sites: intent, spec synth, critic, SQL gen	`llm.py` (two-tier factory)
LangGraph	8-node Clarifier with HITL interrupt + InMemorySaver	`widgets/graph.py`
sqlglot	7 safety checks, Databricks dialect, 18 tests / 25 cases	`sql_gen/safety.py`

Integration	What it does	Tests / evidence
SSE	5 event types: stage, gaps, questions, result, error	`widgets/routes.py`
:material-websocket:{ style="color: #14b8a6" } WebSocket	Real-time dashboard via Redis pub/sub channel	`main.py:278`
@babel/standalone	Browser TSX compile in sealed scope (React + Icon only)	`CustomWidgetRenderer.tsx`

Integration	What it does	Tests / evidence
Docker Compose	5 core services + optional Langfuse (6 more)	`docker-compose.yml`
Langfuse	LLM trace per call, per-node spans, no-op when off	`telemetry.py`
Eval harness	7 static checks + tsc, full Bedrock capture, artifact persistence	`scripts/clarifier_eval/`

End-to-end data flow¶

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#1e3a5f', 'primaryTextColor': '#ffffff', 'lineColor': '#64748b', 'fontFamily': 'Inter, system-ui, sans-serif', 'actorBkg': '#1e3a5f', 'actorTextColor': '#ffffff', 'actorLineColor': '#3b82f6', 'activationBkgColor': '#e0f2fe', 'activationBorderColor': '#3b82f6', 'signalColor': '#334155', 'signalTextColor': '#0f172a', 'noteBkgColor': '#fef3c7', 'noteTextColor': '#92400e', 'noteBorderColor': '#f59e0b'}}}%%
sequenceDiagram
    participant User as fa:fa-user Operator
    participant UI as fa:fa-desktop React UI
    participant API as fa:fa-server FastAPI
    participant LG as fa:fa-sitemap LangGraph
    participant BR as fa:fa-brain Bedrock
    participant PG as fa:fa-database Postgres
    participant SG as fa:fa-code SQL Gen
    participant SQ as fa:fa-shield sqlglot
    participant DB as fa:fa-warehouse Databricks
    participant RC as fa:fa-bolt Redis

    rect rgb(239, 246, 255)
        Note over User,LG: Widget Clarifier (SSE streaming)
        User->>UI: "Show claim volume by region"
        UI->>API: POST /v1/widgets/clarify (SSE)
        API->>LG: Start graph (8 nodes)
        LG->>BR: Intent extraction (fast tier)
        BR-->>LG: Structured intent
        LG->>PG: Metric catalog match
        PG-->>LG: Matched metric
        LG-->>UI: Stream questions (SSE)
        User->>UI: Answer question
        UI->>API: POST /v1/widgets/clarify/respond
        LG->>BR: Spec synthesis (reasoning tier)
        BR-->>LG: WidgetSpec
        LG-->>UI: Stream result (SSE)
    end

    rect rgb(240, 253, 244)
        Note over UI,RC: Data Resolution + Caching
        UI->>API: POST /v1/widgets (persist)
        UI->>API: POST /v1/widgets/{id}/data
        API->>RC: Cache check (miss)
        API->>SG: Generate SQL
        SG->>BR: Bedrock (fast tier)
        BR-->>SG: Generated SQL
        SG->>SQ: Validate (7 safety checks)
        SQ-->>SG: Validated
        SG->>DB: Execute query
        DB-->>SG: Result rows
        SG-->>RC: Cache result (TTL)
        SG-->>UI: Data + source: databricks
    end

    Note over UI: Render with purple SourceBadge

Integration architecture¶

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#1e3a5f', 'primaryTextColor': '#fff', 'primaryBorderColor': '#0d253f', 'lineColor': '#64748b', 'fontFamily': 'Inter, system-ui, sans-serif'}}}%%
graph TB
    classDef frontend fill:#3b82f6,stroke:#1d4ed8,color:#fff,stroke-width:2px,font-weight:bold
    classDef api fill:#1e3a5f,stroke:#0d253f,color:#fff,stroke-width:2px,font-weight:bold
    classDef data fill:#10b981,stroke:#059669,color:#fff,stroke-width:2px
    classDef ai fill:#8b5cf6,stroke:#6d28d9,color:#fff,stroke-width:2px
    classDef cache fill:#ef4444,stroke:#b91c1c,color:#fff,stroke-width:2px
    classDef obs fill:#f59e0b,stroke:#d97706,color:#fff,stroke-width:2px
    classDef safety fill:#06b6d4,stroke:#0891b2,color:#fff,stroke-width:2px

    Browser["fa:fa-desktop Browser<br/>React + Tailwind + Babel"]:::frontend
    Nginx["fa:fa-server Nginx :3080"]:::frontend

    subgraph Core ["FastAPI :8000"]
        direction TB
        API["fa:fa-bolt API Layer<br/>REST + SSE + WebSocket"]:::api
        LG["fa:fa-sitemap LangGraph<br/>8-node Clarifier"]:::api
        SG["fa:fa-code SQL Gen<br/>+ sqlglot safety"]:::safety
    end

    PG["fa:fa-database Postgres 16<br/>8 tables"]:::data
    DB["fa:fa-warehouse Databricks<br/>SQL Warehouse"]:::ai
    Redis["fa:fa-bolt Redis 7<br/>cache + pub/sub"]:::cache
    Bedrock["fa:fa-brain AWS Bedrock<br/>Sonnet 4.6 / Opus 4.7"]:::ai
    Langfuse["fa:fa-chart-timeline Langfuse<br/>LLM observability"]:::obs

    Browser -->|"HTTP + SSE + WS"| Nginx
    Nginx --> API
    API --> LG
    API --> SG
    API --> PG
    API --> Redis
    LG --> Bedrock
    SG --> Bedrock
    SG --> DB
    API -.->|"opt-in"| Langfuse
    Redis -->|"pub/sub"| API
    API -->|"WebSocket"| Browser

Speaker notes (45-60s)

Point to the tabs: "12 integrations across four categories. Every one is real. Every one has a test file you can open."
Walk the sequence diagram top to bottom: "User describes a widget in plain English. LangGraph orchestrates 8 nodes. Bedrock generates the spec. sqlglot validates the SQL with 7 safety checks. Databricks executes against real Asurion data. Redis caches. The tile renders with a purple badge proving it came from the warehouse."
Drop the number: "106 backend tests, 70 frontend tests, 18 ADRs. This is not a prototype that calls an API once."
See integration-map.md for full file-path citations.