Architecture overview
This overview describes the current runtime architecture of the web client and API platform.Runtime architecture (request path)
Background pipeline architecture
Key runtime flows
Authenticated API request
The web client reads session tokens from client state, attaches
Authorization: Bearer ..., and sends same-origin /api/* requests through a shared API client.401 recovery policy
The frontend API client calls
/api/auth/refresh once on 401 and retries the original request once. If refresh still fails, it clears local auth state and logs out.Chat streaming path
POST /api/chat/send returns SSE. The frontend stream reader parses data: frames, while backend chat routes persist user/assistant messages and emit structured SSE envelopes.System components
Frontend shell
React + TanStack Query + Zustand state. Uses one API client for auth-aware fetches and SSE chat consumption.
API gateway
FastAPI app with centralized middleware, router composition, schema validation, and request-scoped identity enforcement.
Domain services
Chat orchestration (including v2 planner path), onboarding services, integration services, and prompt registry lifecycle.
Data + jobs
AsyncPG-backed reads/writes with background-job pipelines for metrics, actions, opportunities, reports, and integration sync state.
Component responsibility map
| Layer | Component | Responsibility |
|---|---|---|
| Client | React app shell | Renders product surfaces and routes user actions to API clients. |
| Client | API client module | Adds auth headers, executes refresh-on-401 logic, normalizes errors. |
| Client | SSE stream parser | Parses streaming assistant responses for Coach chat UX. |
| API | FastAPI middleware | Adds request IDs, captures errors, and emits operational notifications. |
| API | Auth routes | Login/refresh/logout/me plus OIDC callback handling. |
| API | Product routes | Coach, Money, Growth, onboarding, settings, integrations, tasking endpoints. |
| Service | Background job orchestration | Executes async workflows and scheduled materialization jobs. |
| Data | PostgreSQL schemas | Stores identity/session, chat history, metrics/actions/opps, projects, and task runs. |
For production readiness reviews, pair this overview with Security posture and Authentication.