How bairoy/financial-msa works
1. This repo is a two-tier financial assistant: a Python FastAPI backend that runs the agentic workflow, and a React/TypeScript frontend that provides the dashboard and chat experience. The architectural center is the backend’s LangGraph orchestration layer; the frontend is primarily a presentation and streaming client.
2. The backend entrypoint is backend/app/main.py, with API surface split into REST routes (backend/app/api/routes.py) and WebSocket streaming (backend/app/api/websocket.py). backend/app/config.py holds environment-driven settings for OpenAI, LangSmith, and deployment/runtime configuration. backend/run.py and backend/docker-compose.yml support local startup and infra bootstrapping.
3. The core domain boundary is the agent layer under backend/app/agents/. A supervisor.py agent acts as the router and delegates to specialist agents: market analysis, portfolio management, risk assessment, and compliance monitoring. This is the main control plane for user requests; it decides which specialist handles the query and then synthesizes the final answer.
4. Specialist agents are separated by responsibility, not by UI or endpoint. market_agent.py handles market/pricing/technical analysis; portfolio_agent.py handles allocation, metrics, and rebalancing; risk_agent.py covers VaR and stress testing; compliance_agent.py handles KYC/SEC-style compliance questions. Each agent is wrapped as a handoff tool so the supervisor can call it as part of a single LangGraph workflow.
5. Shared agent infrastructure lives in backend/app/agents/shared/. state.py defines the graph state, tools.py contains financial tools exposed to agents, memory.py implements the memory system, and rag.py contains retrieval-augmented generation logic. This shared layer is the main dependency boundary for all agents.
6. Memory is explicitly multi-layered. Short-term conversation state is kept with LangGraph’s checkpointer (MemorySaver), long-term user context lives in a store (InMemoryStore per the README), episodic/audit history is append-only event data, and semantic knowledge is backed by a FAISS vector index for RAG. This means the system separates conversational continuity, user profile persistence, auditability, and knowledge retrieval.
7. The RAG path is a distinct sub-flow, not just a single search call. rag.py implements a self-correcting loop: rewrite the query, retrieve documents from FAISS, grade relevance, retry if needed, then generate a grounded answer. That makes knowledge-backed answers a separate retrieval/generation pipeline inside the broader agent system.
8. Human-in-the-loop behavior is part of the execution model. The README indicates LangGraph interrupt() is used to pause execution for trade approval, risk overrides, or compliance review, then resume from the same state. Architecturally, this is a stateful checkpointed workflow rather than a stateless request/response chain.
9. Streaming is a first-class interaction path. The backend emits real-time events over WebSocket at /ws, and also exposes an SSE-style streaming route at /api/chat/stream. The frontend receives token/tool events and renders them incrementally, so the UI is coupled to agent execution events rather than only final responses.
10. LangSmith tracing is an observability boundary around all agent execution. Because the repo is built on LangGraph/LangChain, each supervisor and specialist invocation can be traced as nested spans for debugging, latency analysis, and routing inspection. This is important to the architecture because it supports understanding and auditing multi-agent behavior in production.
11. The frontend under src/ is a Vite-based React app with shadcn/ui components and Tailwind styling. src/pages/Home.tsx appears to host the main dashboard/chat surface, while src/lib/api.ts encapsulates backend calls. The frontend is intentionally thin: it consumes the backend’s chat, memory, and knowledge endpoints and renders agent activity.
12. Operationally, the project expects external services and stateful infrastructure. OpenAI is the model provider, LangSmith is optional but strongly integrated for tracing, and PostgreSQL is started via Docker Compose for local/prod-like persistence. The architecture therefore combines cloud LLM dependencies with local containerized state and a vector-search knowledge layer.
Main entry points: supervisor.py Supervisor · config.py Config · main.py App entry · tools.py Tools
Components 20
Backend
FastAPI app, agent workflow, and streaming API
Agents
Supervisor, specialist agents, and shared runtime
- Supervisor · Routes requests to specialist agents and synthesizes answers
backend/app/agents/supervisor.py - Market · Market, pricing, and technical analysis
backend/app/agents/market_agent.py - Portfolio · Allocation, metrics, and rebalancing
backend/app/agents/portfolio_agent.py - Risk · VaR and stress testing
backend/app/agents/risk_agent.py - Compliance · KYC and regulatory-style review
backend/app/agents/compliance_agent.py - State · LangGraph state model shared across the workflow
backend/app/agents/shared/state.py - Tools · Reusable tools exposed to agents
backend/app/agents/shared/tools.py - RAG · Query rewrite, retrieval, grading, and grounded generation
backend/app/agents/shared/rag.py
Frontend
React dashboard and chat client
- React app · Frontend application shell
src/App.tsx - Home · Main dashboard and chat surface
src/pages/Home.tsx - API client · Encapsulates REST and streaming calls to the backend
src/lib/api.ts
Infra
Runtime settings, persistence, and observability
- Config · OpenAI, LangSmith, and runtime configuration
backend/app/config.py - Memory · Short-term, long-term, and audit persistence helpers
backend/app/agents/shared/memory.py - LangSmith · Execution tracing and nested span observability
- OpenAI · LLM and embedding provider
- Postgres · Containerized local persistence via compose
backend/docker-compose.yml - FAISS · Semantic retrieval store for knowledge-backed answers
Connections 34
- App entry → REST API: mounts · Registers the HTTP API surface
- App entry → WebSocket: mounts · Registers streaming endpoints
- App entry → Supervisor: starts workflow · Hands user requests into LangGraph orchestration
- REST API → Supervisor: invoke · Sends chat and task requests into the agent graph
- WebSocket → Supervisor: stream · Streams agent events and partial results
- Supervisor → State: reads/writes · Uses shared graph state across turns
- Supervisor → Tools: uses · Calls financial tools during routing and synthesis
- Supervisor → Market: handoff · Delegates market questions to specialist agent
- Supervisor → Portfolio: handoff · Delegates portfolio questions to specialist agent
- Supervisor → Risk: handoff · Delegates risk questions to specialist agent
- Supervisor → Compliance: handoff · Delegates compliance questions to specialist agent
- Market → Tools: uses · Reads market tools and helpers
- Portfolio → Tools: uses · Reads portfolio tools and helpers
- Risk → Tools: uses · Reads risk tools and helpers
- Compliance → Tools: uses · Reads compliance-adjacent tools and helpers
- Memory → Postgres: persists · Stores durable application data and history
- Memory → FAISS: indexes · Backs semantic knowledge retrieval
- RAG → FAISS: retrieves · Searches the vector index for grounded context
- RAG → OpenAI: generates · Uses the model for rewrite, grading, and answer synthesis
- Supervisor → Memory: checkpoints · Depends on stateful memory and resume points
- Supervisor → RAG: grounds answers · Routes knowledge-heavy questions through RAG
- Config → OpenAI: configures · Provides API keys and model settings
- Config → LangSmith: configures · Provides tracing and deployment settings
- Config → App entry: loads into · Supplies runtime settings at startup
- Config → Memory: configures · Controls persistence and memory behavior
- Config → RAG: configures · Supplies model and retrieval settings
- Config → Postgres: connects · Coordinates local infra settings
- App entry → LangSmith: traces · Emits observability spans during execution
- Supervisor → LangSmith: traces · Nested spans for routing and specialist calls
- WebSocket → React app: events · Sends token and tool events to the UI
- REST API → API client: responds to · Frontend client consumes REST responses
- WebSocket → API client: streams to · Frontend client consumes streaming events
- React app → Home: renders · Hosts the main dashboard page
- Home → API client: calls · Uses backend client for chat and streaming