# crisap94/cadre-chat-bot architecture

> Architecture diagram of the GitHub repository crisap94/cadre-chat-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crisap94/cadre-chat-bot
- Repository: https://github.com/crisap94/cadre-chat-bot

## Overview

1. **System shape**
   - This repo is a 3-part product: a **FastAPI backend**, an **embeddable React widget**, and an **Astro landing page** that hosts the built widget bundle.
   - The core business logic lives in the backend; the frontend pieces are thin shells around that API.

2. **Primary request flow**
   - A user types in the widget, which sends chat traffic to the backend over `/chat` and `/chat/stream`.
   - The backend runs a **LangGraph StateGraph** that classifies the message, chooses an expert path, or escalates to human handoff.
   - Responses stream back using the **assistant-stream / assistant-ui** protocol, so the widget can render tokens without a custom parser.

3. **Backend API boundary**
   - `backend/routes/` exposes the service surface: chat, conversations, handoff, health, and widget initialization.
   - `routes/chat.py` is the main ingress for message turns and streaming.
   - `routes/conversations.py` and `routes/handoff.py` expose persisted conversation and escalation data.
   - `routes/widget.py` likely serves the widget bootstrap/config needed by embedded clients.
   - `routes/health.py` is the operational probe.

4. **Conversation orchestration**
   - `backend/graph.py`, `backend/state.py`, `backend/nodes/`, and `backend/prompts/` form the agent pipeline.
   - The router node classifies intent and confidence, then branches to one of the expert nodes or to fallback/handoff.
   - Expert nodes are split by domain: **services**, **booking**, and **technical**.
   - The handoff node short-circuits when the user explicitly requests a human.

5. **Persistence and session identity**
   - The system persists conversational state in **Postgres** using LangGraph’s checkpointing plus SQLAlchemy/Alembic-managed schema.
   - `backend/db.py`, `backend/models.py`, and `alembic/` are the relational persistence boundary.
   - `backend/fingerprint_store.py` tracks browser fingerprinting so returning visitors can be recognized.
   - `backend/handoff_store.py` stores escalation/ticket state separately from normal chat turns.

6. **LLM and prompt configuration**
   - `backend/llm_config.py` centralizes model selection and provider settings.
   - The same codebase can point at different OpenAI-compatible providers by changing environment variables only.
   - Prompt content is separated by role/domain in `backend/prompts/` so router, expert, fallback, and booking behaviors are independently managed.

7. **Security and request hygiene**
   - `backend/middleware/` contains cross-cutting controls: CORS, HSTS, rate limiting, and security logging.
   - `backend/auth.py` and `backend/config.py` define origin/site restrictions and secret-driven runtime settings.
   - `backend/sanitize.py`, `backend/errors.py`, and `backend/constants.py` support safe input handling and consistent failure behavior.

8. **Streaming transport**
   - `backend/transport.py` and `backend/messages.py` are the adaptation layer between LangGraph output and the widget’s stream format.
   - This is where backend state, token streaming, and client-visible message events are shaped into the assistant-ui-compatible response stream.

9. **Widget runtime**
   - `widget/` is a separate **React 19 + Vite** application that builds into a single embeddable script.
   - Key UI boundaries are `ChatLauncher`, `ChatWindow`, `Conversation`, consent/offline/rate-limit notices, and session/state helpers.
   - The widget is designed to be embedded on arbitrary sites via a script tag and a `data-api-base` pointing at the backend.

10. **Landing page and delivery**
    - `frontend/` is an **Astro static site** that presents the marketing/landing experience and includes the widget bundle from `frontend/public/js/`.
    - `frontend/public/fallback.html` suggests a graceful no-JS or degraded-mode fallback.
    - The landing page is separate from the chat backend; it is deployed as static content and only consumes the built widget artifact.

11. **Operational constraints**
    - The backend needs an **always-on process** because it maintains long-lived streams and a persistent Postgres pool.
    - Postgres is not just storage; it is part of the graph execution model through LangGraph checkpointing.
    - Deploy configuration is therefore sensitive to hosting choice, pool type, and environment-variable parity.

12. **Quality and documentation boundary**
    - `backend/tests/` covers unit and end-to-end behavior for chat, streaming, conversations, handoff, health, and widget initialization.
    - `docs/qa/*.feature` maps directly to product scenarios, so the architecture is tightly coupled to executable acceptance criteria.
    - `docs/architecture`, `docs/prd`, and `CLAUDE.md` are the canonical references for intended system behavior and constraints.

Main entry points: [`backend/routes`](https://github.com/crisap94/cadre-chat-bot/tree/main/backend/routes) (API routes), [`backend/graph.py`](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/graph.py) (Agent graph), [`backend/routes/chat.py`](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/routes/chat.py) (Chat ingress), [`widget/src/components`](https://github.com/crisap94/cadre-chat-bot/tree/main/widget/src/components) (Chat UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["App entry<br/>FastAPI app<br/>[main.py]"]
  node_backend_routes["API routes<br/>HTTP surface"]
  node_backend_chat["Chat ingress<br/>chat API<br/>[chat.py]"]
  node_backend_conversations["Conversations<br/>conversation API<br/>[conversations.py]"]
  node_backend_handoff_route["Handoff API<br/>[handoff.py]"]
  node_backend_widget_route["Widget init<br/>bootstrap API<br/>[widget.py]"]
  node_backend_health["Health probe<br/>ops API<br/>[health.py]"]
  node_backend_graph["Agent graph<br/>LangGraph pipeline<br/>[graph.py]"]
  node_backend_state["Graph state<br/>state model<br/>[state.py]"]
  node_backend_router_node["Router node<br/>intent router<br/>[router.py]"]
  node_backend_experts["Expert nodes<br/>domain handlers<br/>[experts.py]"]
  node_backend_handoff_node["Handoff node<br/>escalation handler<br/>[handoff.py]"]
  node_backend_prompts["Prompt set<br/>prompt library"]
  node_backend_transport["Stream adapter<br/>assistant-ui transport<br/>[transport.py]"]
  node_backend_messages["Message events<br/>stream schema<br/>[messages.py]"]
  node_backend_db[("Postgres layer<br/>SQLAlchemy persistence<br/>[db.py]")]
  node_backend_models["Data models<br/>ORM schema<br/>[models.py]"]
  node_backend_stores["Special stores<br/>state stores"]
  node_backend_config["Runtime config<br/>settings<br/>[config.py]"]
  node_backend_security["Security layer<br/>middleware"]
end

subgraph group_widget["Widget"]
  node_widget_app["Widget app<br/>React 19 + Vite<br/>[main.tsx]"]
  node_widget_shell["Widget shell<br/>chat UI<br/>[Widget.tsx]"]
  node_widget_ui["Chat UI<br/>ui components"]
  node_widget_state["Session state<br/>client state<br/>[state.ts]"]
end

subgraph group_frontend["Landing Page"]
  node_frontend_site["Landing site<br/>Astro site<br/>[index.astro]"]
  node_frontend_assets["Static assets<br/>site assets"]
end

subgraph group_docs["Docs"]
  node_docs_arch["Architecture docs<br/>reference docs"]
  node_docs_api["API spec<br/>contract docs<br/>[API-SPEC.md]"]
  node_docs_qa["QA scenarios<br/>acceptance specs"]
end

node_backend_main -->|"applies"| node_backend_security
node_backend_main -->|"loads"| node_backend_config
node_backend_main -->|"mounts"| node_backend_routes
node_backend_routes -->|"includes"| node_backend_chat
node_backend_routes -->|"includes"| node_backend_conversations
node_backend_routes -->|"includes"| node_backend_handoff_route
node_backend_routes -->|"includes"| node_backend_widget_route
node_backend_routes -->|"includes"| node_backend_health
node_backend_chat -->|"invokes"| node_backend_graph
node_backend_graph -->|"uses"| node_backend_state
node_backend_graph -->|"branches to"| node_backend_router_node
node_backend_graph -->|"branches to"| node_backend_experts
node_backend_graph -->|"branches to"| node_backend_handoff_node
node_backend_router_node -->|"reads"| node_backend_prompts
node_backend_experts -->|"reads"| node_backend_prompts
node_backend_handoff_node -->|"writes"| node_backend_stores
node_backend_graph -->|"checkpointed in"| node_backend_db
node_backend_db -->|"maps"| node_backend_models
node_backend_stores -->|"persists in"| node_backend_db
node_backend_chat -->|"streams via"| node_backend_transport
node_backend_transport -->|"formats"| node_backend_messages
node_widget_app -->|"renders"| node_widget_shell
node_widget_shell -->|"composes"| node_widget_ui
node_widget_shell -->|"uses"| node_widget_state
node_widget_ui -->|"initializes from"| node_backend_widget_route
node_widget_ui -->|"sends"| node_backend_chat
node_widget_ui -->|"consumes"| node_backend_transport
node_frontend_site -->|"includes"| node_frontend_assets
node_frontend_site -->|"embeds"| node_widget_app
node_docs_arch -.->|"describes"| node_backend_graph
node_docs_api -.->|"specifies"| node_backend_routes
node_docs_qa -.->|"covers"| node_backend_chat
node_docs_qa -.->|"covers"| node_backend_handoff_route
node_docs_qa -.->|"covers"| node_backend_widget_route

click node_backend_main "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/main.py"
click node_backend_routes "https://github.com/crisap94/cadre-chat-bot/tree/main/backend/routes"
click node_backend_chat "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/routes/chat.py"
click node_backend_conversations "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/routes/conversations.py"
click node_backend_handoff_route "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/routes/handoff.py"
click node_backend_widget_route "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/routes/widget.py"
click node_backend_health "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/routes/health.py"
click node_backend_graph "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/graph.py"
click node_backend_state "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/state.py"
click node_backend_router_node "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/nodes/router.py"
click node_backend_experts "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/nodes/experts.py"
click node_backend_handoff_node "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/nodes/handoff.py"
click node_backend_prompts "https://github.com/crisap94/cadre-chat-bot/tree/main/backend/prompts"
click node_backend_transport "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/transport.py"
click node_backend_messages "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/messages.py"
click node_backend_db "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/db.py"
click node_backend_models "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/models.py"
click node_backend_stores "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/fingerprint_store.py"
click node_backend_config "https://github.com/crisap94/cadre-chat-bot/blob/main/backend/config.py"
click node_backend_security "https://github.com/crisap94/cadre-chat-bot/tree/main/backend/middleware"
click node_widget_app "https://github.com/crisap94/cadre-chat-bot/blob/main/widget/src/main.tsx"
click node_widget_shell "https://github.com/crisap94/cadre-chat-bot/blob/main/widget/src/Widget.tsx"
click node_widget_ui "https://github.com/crisap94/cadre-chat-bot/tree/main/widget/src/components"
click node_widget_state "https://github.com/crisap94/cadre-chat-bot/blob/main/widget/src/state.ts"
click node_frontend_site "https://github.com/crisap94/cadre-chat-bot/blob/main/frontend/src/pages/index.astro"
click node_frontend_assets "https://github.com/crisap94/cadre-chat-bot/tree/main/frontend/public"
click node_docs_arch "https://github.com/crisap94/cadre-chat-bot/blob/main/docs/architecture/ARCHITECTURE-SPINE.md"
click node_docs_api "https://github.com/crisap94/cadre-chat-bot/blob/main/docs/api/API-SPEC.md"
click node_docs_qa "https://github.com/crisap94/cadre-chat-bot/tree/main/docs/qa"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_backend_main,node_backend_routes,node_backend_chat,node_backend_conversations,node_backend_handoff_route,node_backend_widget_route,node_backend_health,node_backend_graph,node_backend_state,node_backend_router_node,node_backend_experts,node_backend_handoff_node,node_backend_prompts,node_backend_transport,node_backend_messages,node_backend_db,node_backend_models,node_backend_stores,node_backend_config,node_backend_security toneBlue
class node_widget_app,node_widget_shell,node_widget_ui,node_widget_state toneAmber
class node_frontend_site,node_frontend_assets toneMint
class node_docs_arch,node_docs_api,node_docs_qa toneRose
```

## Components

### Backend

FastAPI service, graph orchestration, persistence, and streaming adaptation.

- [App entry](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/main.py): FastAPI app · Starts the backend service and wires middleware, routes, and runtime setup. · `backend/main.py`
- [API routes](https://github.com/crisap94/cadre-chat-bot/tree/main/backend/routes): HTTP surface · Top-level service boundary for chat, conversations, handoff, health, and widget init. · `backend/routes`
- [Chat ingress](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/routes/chat.py): chat API · Main entry point for message turns and streaming responses. · `backend/routes/chat.py`
- [Conversations](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/routes/conversations.py): conversation API · Exposes persisted conversation state and turn history. · `backend/routes/conversations.py`
- [Handoff API](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/routes/handoff.py): handoff API · Surfaces escalation and human handoff records. · `backend/routes/handoff.py`
- [Widget init](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/routes/widget.py): bootstrap API · Serves widget bootstrap and client configuration. · `backend/routes/widget.py`
- [Health probe](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/routes/health.py): ops API · Operational readiness and liveness endpoint. · `backend/routes/health.py`
- [Agent graph](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/graph.py): LangGraph pipeline · Coordinates routing, expert paths, fallback, and handoff decisions. · `backend/graph.py`
- [Graph state](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/state.py): state model · Defines the shared conversation and routing state passed through the graph. · `backend/state.py`
- [Router node](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/nodes/router.py): intent router · Classifies intent and confidence, then chooses expert or fallback branches. · `backend/nodes/router.py`
- [Expert nodes](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/nodes/experts.py): domain handlers · Domain-specific response paths for services, booking, and technical help. · `backend/nodes/experts.py`
- [Handoff node](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/nodes/handoff.py): escalation handler · Short-circuits the graph when a human handoff is needed. · `backend/nodes/handoff.py`
- [Prompt set](https://github.com/crisap94/cadre-chat-bot/tree/main/backend/prompts): prompt library · Separated prompt content for router, experts, booking, and fallback behavior. · `backend/prompts`
- [Stream adapter](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/transport.py): assistant-ui transport · Shapes LangGraph output into the widget-visible streaming protocol. · `backend/transport.py`
- [Message events](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/messages.py): stream schema · Defines client-visible assistant and token event structures. · `backend/messages.py`
- [Postgres layer](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/db.py): SQLAlchemy persistence · Relational persistence boundary for chat state and checkpointing. · `backend/db.py`
- [Data models](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/models.py): ORM schema · Database entities used by the backend persistence layer. · `backend/models.py`
- [Special stores](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/fingerprint_store.py): state stores · Fingerprint and handoff stores for identity and escalation tracking. · `backend/fingerprint_store.py`
- [Runtime config](https://github.com/crisap94/cadre-chat-bot/blob/main/backend/config.py): settings · Centralized environment-driven settings, auth rules, and model selection. · `backend/config.py`
- [Security layer](https://github.com/crisap94/cadre-chat-bot/tree/main/backend/middleware): middleware · CORS, HSTS, rate limiting, and security logging controls. · `backend/middleware`

### Widget

Embeddable React runtime shipped as a standalone bundle.

- [Widget app](https://github.com/crisap94/cadre-chat-bot/blob/main/widget/src/main.tsx): React 19 + Vite · Standalone embeddable chat client built as a single script bundle. · `widget/src/main.tsx`
- [Widget shell](https://github.com/crisap94/cadre-chat-bot/blob/main/widget/src/Widget.tsx): chat UI · Top-level widget composition and runtime wiring. · `widget/src/Widget.tsx`
- [Chat UI](https://github.com/crisap94/cadre-chat-bot/tree/main/widget/src/components): ui components · Launcher, window, conversation, consent, offline, and rate-limit views. · `widget/src/components`
- [Session state](https://github.com/crisap94/cadre-chat-bot/blob/main/widget/src/state.ts): client state · Session identity, local state, hooks, and type definitions for embedding. · `widget/src/state.ts`

### Landing Page

Astro marketing site that hosts the built widget artifact.

- [Landing site](https://github.com/crisap94/cadre-chat-bot/blob/main/frontend/src/pages/index.astro): Astro site · Static marketing and landing experience that includes the built widget artifact. · `frontend/src/pages/index.astro`
- [Static assets](https://github.com/crisap94/cadre-chat-bot/tree/main/frontend/public): site assets · Public fallback page and built widget delivery assets. · `frontend/public`

### Docs

Architecture, product, API, and QA references.

- [Architecture docs](https://github.com/crisap94/cadre-chat-bot/blob/main/docs/architecture/ARCHITECTURE-SPINE.md): reference docs · Canonical system shape and design references. · `docs/architecture/ARCHITECTURE-SPINE.md`
- [API spec](https://github.com/crisap94/cadre-chat-bot/blob/main/docs/api/API-SPEC.md): contract docs · Service contract and request/response expectations. · `docs/api/API-SPEC.md`
- [QA scenarios](https://github.com/crisap94/cadre-chat-bot/tree/main/docs/qa): acceptance specs · Executable product scenarios for chat, streaming, conversations, handoff, health, and widget init. · `docs/qa`

## Connections

- App entry → Security layer: applies · Registers cross-cutting request protections.
- App entry → Runtime config: loads · Reads runtime settings and environment-driven policy.
- App entry → API routes: mounts · Exposes the service API surface.
- API routes → Chat ingress: includes · Message ingress and streaming turns.
- API routes → Conversations: includes · Conversation persistence endpoints.
- API routes → Handoff API: includes · Escalation endpoints.
- API routes → Widget init: includes · Widget bootstrap/config endpoint.
- API routes → Health probe: includes · Operational probe endpoint.
- Chat ingress → Agent graph: invokes · Submits turns into the LangGraph pipeline.
- Agent graph → Graph state: uses · Carries shared conversation and routing state.
- Agent graph → Router node: branches to · Classifies the message and selects the next path.
- Agent graph → Expert nodes: branches to · Routes to domain expertise when appropriate.
- Agent graph → Handoff node: branches to · Escalates explicitly requested human handoff.
- Router node → Prompt set: reads · Uses router-specific prompt guidance.
- Expert nodes → Prompt set: reads · Uses domain prompt variants.
- Handoff node → Special stores: writes · Persists escalation state and related identity data.
- Agent graph → Postgres layer: checkpointed in · Conversation state is persisted through Postgres-backed checkpointing.
- Postgres layer → Data models: maps · ORM schema defines stored entities.
- Special stores → Postgres layer: persists in · Fingerprint and handoff state use the relational store.
- Chat ingress → Stream adapter: streams via · Adapts backend output to assistant-ui compatible streaming.
- Stream adapter → Message events: formats · Converts graph output into client-visible message events.
- Widget app → Widget shell: renders · Bootstraps the chat experience.
- Widget shell → Chat UI: composes · Uses launcher, window, conversation, and notices.
- Widget shell → Session state: uses · Manages session identity and local interaction state.
- Chat UI → Widget init: initializes from · Fetches widget configuration and bootstrap data from the backend.
- Chat UI → Chat ingress: sends · Posts user turns to the chat ingress.
- Chat UI → Stream adapter: consumes · Renders assistant-ui compatible streamed responses.
- Landing site → Static assets: includes · Serves static fallback and built artifact assets.
- Landing site → Widget app: embeds · Hosts the widget bundle in the landing experience.
- Architecture docs → Agent graph: describes · Documents the orchestration spine.
- API spec → API routes: specifies · Defines the service contract.
- QA scenarios → Chat ingress: covers · Acceptance scenarios for chat and streaming.
- QA scenarios → Handoff API: covers · Acceptance scenarios for escalation.
- QA scenarios → Widget init: covers · Acceptance scenarios for widget initialization.
