How crisap94/cadre-chat-bot works
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: routes API routes · graph.py Agent graph · chat.py Chat ingress · components Chat UI
Components 29
Backend
FastAPI service, graph orchestration, persistence, and streaming adaptation.
- App entry · Starts the backend service and wires middleware, routes, and runtime setup.
backend/main.py - API routes · Top-level service boundary for chat, conversations, handoff, health, and widget init.
backend/routes - Chat ingress · Main entry point for message turns and streaming responses.
backend/routes/chat.py - Conversations · Exposes persisted conversation state and turn history.
backend/routes/conversations.py - Handoff API · Surfaces escalation and human handoff records.
backend/routes/handoff.py - Widget init · Serves widget bootstrap and client configuration.
backend/routes/widget.py - Health probe · Operational readiness and liveness endpoint.
backend/routes/health.py - Agent graph · Coordinates routing, expert paths, fallback, and handoff decisions.
backend/graph.py - Graph state · Defines the shared conversation and routing state passed through the graph.
backend/state.py - Router node · Classifies intent and confidence, then chooses expert or fallback branches.
backend/nodes/router.py - Expert nodes · Domain-specific response paths for services, booking, and technical help.
backend/nodes/experts.py - Handoff node · Short-circuits the graph when a human handoff is needed.
backend/nodes/handoff.py - Prompt set · Separated prompt content for router, experts, booking, and fallback behavior.
backend/prompts - Stream adapter · Shapes LangGraph output into the widget-visible streaming protocol.
backend/transport.py - Message events · Defines client-visible assistant and token event structures.
backend/messages.py - Postgres layer · Relational persistence boundary for chat state and checkpointing.
backend/db.py - Data models · Database entities used by the backend persistence layer.
backend/models.py - Special stores · Fingerprint and handoff stores for identity and escalation tracking.
backend/fingerprint_store.py - Runtime config · Centralized environment-driven settings, auth rules, and model selection.
backend/config.py - Security layer · CORS, HSTS, rate limiting, and security logging controls.
backend/middleware
Widget
Embeddable React runtime shipped as a standalone bundle.
- Widget app · Standalone embeddable chat client built as a single script bundle.
widget/src/main.tsx - Widget shell · Top-level widget composition and runtime wiring.
widget/src/Widget.tsx - Chat UI · Launcher, window, conversation, consent, offline, and rate-limit views.
widget/src/components - Session 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 · Static marketing and landing experience that includes the built widget artifact.
frontend/src/pages/index.astro - Static assets · Public fallback page and built widget delivery assets.
frontend/public
Docs
Architecture, product, API, and QA references.
- Architecture docs · Canonical system shape and design references.
docs/architecture/ARCHITECTURE-SPINE.md - API spec · Service contract and request/response expectations.
docs/api/API-SPEC.md - QA scenarios · Executable product scenarios for chat, streaming, conversations, handoff, health, and widget init.
docs/qa
Connections 34
- 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.