# bairoy/financial-msa architecture

> Architecture diagram of the GitHub repository bairoy/financial-msa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bairoy/financial-msa
- Repository: https://github.com/bairoy/financial-msa

## Overview

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: [`backend/app/agents/supervisor.py`](https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/supervisor.py) (Supervisor), [`backend/app/config.py`](https://github.com/bairoy/financial-msa/blob/main/backend/app/config.py) (Config), [`backend/app/main.py`](https://github.com/bairoy/financial-msa/blob/main/backend/app/main.py) (App entry), [`backend/app/agents/shared/tools.py`](https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/shared/tools.py) (Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["App entry<br/>FastAPI bootstrap<br/>[main.py]"]
  node_backend_routes["REST API<br/>HTTP routes<br/>[routes.py]"]
  node_backend_ws["WebSocket<br/>streaming API<br/>[websocket.py]"]
end

subgraph group_agents["Agents"]
  node_supervisor{{"Supervisor<br/>agent router<br/>[supervisor.py]"}}
  node_market_agent{{"Market<br/>specialist agent<br/>[market_agent.py]"}}
  node_portfolio_agent{{"Portfolio<br/>specialist agent<br/>[portfolio_agent.py]"}}
  node_risk_agent{{"Risk<br/>specialist agent<br/>[risk_agent.py]"}}
  node_compliance_agent{{"Compliance<br/>specialist agent"}}
  node_shared_state["State<br/>[state.py]"]
  node_shared_tools["Tools<br/>[tools.py]"]
  node_shared_rag["RAG<br/>retrieval pipeline<br/>[rag.py]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["React app<br/>Vite UI<br/>[App.tsx]"]
  node_home_page["Home<br/>dashboard page<br/>[Home.tsx]"]
  node_api_client["API client<br/>backend client<br/>[api.ts]"]
end

subgraph group_infra["Infra"]
  node_backend_config["Config<br/>env settings<br/>[config.py]"]
  node_shared_memory[("Memory<br/>[memory.py]")]
  node_langsmith(("LangSmith<br/>tracing service"))
  node_openai(("OpenAI<br/>model provider"))
  node_postgres[("Postgres<br/>database<br/>[docker-compose.yml]")]
  node_faiss[("FAISS<br/>vector index")]
end

node_backend_main -->|"mounts"| node_backend_routes
node_backend_main -->|"mounts"| node_backend_ws
node_backend_main -->|"starts workflow"| node_supervisor
node_backend_routes -->|"invoke"| node_supervisor
node_backend_ws -->|"stream"| node_supervisor
node_supervisor -->|"reads/writes"| node_shared_state
node_supervisor -->|"uses"| node_shared_tools
node_supervisor -->|"handoff"| node_market_agent
node_supervisor -->|"handoff"| node_portfolio_agent
node_supervisor -->|"handoff"| node_risk_agent
node_supervisor -->|"handoff"| node_compliance_agent
node_market_agent -->|"uses"| node_shared_tools
node_portfolio_agent -->|"uses"| node_shared_tools
node_risk_agent -->|"uses"| node_shared_tools
node_compliance_agent -->|"uses"| node_shared_tools
node_shared_memory -->|"persists"| node_postgres
node_shared_memory -->|"indexes"| node_faiss
node_shared_rag -->|"retrieves"| node_faiss
node_shared_rag -->|"generates"| node_openai
node_supervisor -->|"checkpoints"| node_shared_memory
node_supervisor -->|"grounds answers"| node_shared_rag
node_backend_config -->|"configures"| node_openai
node_backend_config -->|"configures"| node_langsmith
node_backend_config -->|"loads into"| node_backend_main
node_backend_config -->|"configures"| node_shared_memory
node_backend_config -->|"configures"| node_shared_rag
node_backend_config -.->|"connects"| node_postgres
node_backend_main -->|"traces"| node_langsmith
node_supervisor -->|"traces"| node_langsmith
node_backend_ws -->|"events"| node_frontend_app
node_backend_routes -->|"responds to"| node_api_client
node_backend_ws -->|"streams to"| node_api_client
node_frontend_app -->|"renders"| node_home_page
node_home_page -->|"calls"| node_api_client

click node_backend_main "https://github.com/bairoy/financial-msa/blob/main/backend/app/main.py"
click node_backend_routes "https://github.com/bairoy/financial-msa/blob/main/backend/app/api/routes.py"
click node_backend_ws "https://github.com/bairoy/financial-msa/blob/main/backend/app/api/websocket.py"
click node_backend_config "https://github.com/bairoy/financial-msa/blob/main/backend/app/config.py"
click node_supervisor "https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/supervisor.py"
click node_market_agent "https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/market_agent.py"
click node_portfolio_agent "https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/portfolio_agent.py"
click node_risk_agent "https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/risk_agent.py"
click node_compliance_agent "https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/compliance_agent.py"
click node_shared_state "https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/shared/state.py"
click node_shared_tools "https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/shared/tools.py"
click node_shared_memory "https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/shared/memory.py"
click node_shared_rag "https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/shared/rag.py"
click node_postgres "https://github.com/bairoy/financial-msa/blob/main/backend/docker-compose.yml"
click node_frontend_app "https://github.com/bairoy/financial-msa/blob/main/src/App.tsx"
click node_home_page "https://github.com/bairoy/financial-msa/blob/main/src/pages/Home.tsx"
click node_api_client "https://github.com/bairoy/financial-msa/blob/main/src/lib/api.ts"

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_ws toneBlue
class node_supervisor,node_market_agent,node_portfolio_agent,node_risk_agent,node_compliance_agent,node_shared_state,node_shared_tools,node_shared_rag toneAmber
class node_frontend_app,node_home_page,node_api_client toneMint
class node_backend_config,node_shared_memory,node_langsmith,node_openai,node_postgres,node_faiss toneRose
```

## Components

### Backend

FastAPI app, agent workflow, and streaming API

- [App entry](https://github.com/bairoy/financial-msa/blob/main/backend/app/main.py): FastAPI bootstrap · Creates and starts the backend application · `backend/app/main.py`
- [REST API](https://github.com/bairoy/financial-msa/blob/main/backend/app/api/routes.py): HTTP routes · REST endpoints for chat and app operations · `backend/app/api/routes.py`
- [WebSocket](https://github.com/bairoy/financial-msa/blob/main/backend/app/api/websocket.py): streaming API · Real-time event stream for agent execution · `backend/app/api/websocket.py`

### Agents

Supervisor, specialist agents, and shared runtime

- [Supervisor](https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/supervisor.py): agent router · Routes requests to specialist agents and synthesizes answers · `backend/app/agents/supervisor.py`
- [Market](https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/market_agent.py): specialist agent · Market, pricing, and technical analysis · `backend/app/agents/market_agent.py`
- [Portfolio](https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/portfolio_agent.py): specialist agent · Allocation, metrics, and rebalancing · `backend/app/agents/portfolio_agent.py`
- [Risk](https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/risk_agent.py): specialist agent · VaR and stress testing · `backend/app/agents/risk_agent.py`
- [Compliance](https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/compliance_agent.py): specialist agent · KYC and regulatory-style review · `backend/app/agents/compliance_agent.py`
- [State](https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/shared/state.py): graph state · LangGraph state model shared across the workflow · `backend/app/agents/shared/state.py`
- [Tools](https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/shared/tools.py): financial tools · Reusable tools exposed to agents · `backend/app/agents/shared/tools.py`
- [RAG](https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/shared/rag.py): retrieval pipeline · Query rewrite, retrieval, grading, and grounded generation · `backend/app/agents/shared/rag.py`

### Frontend

React dashboard and chat client

- [React app](https://github.com/bairoy/financial-msa/blob/main/src/App.tsx): Vite UI · Frontend application shell · `src/App.tsx`
- [Home](https://github.com/bairoy/financial-msa/blob/main/src/pages/Home.tsx): dashboard page · Main dashboard and chat surface · `src/pages/Home.tsx`
- [API client](https://github.com/bairoy/financial-msa/blob/main/src/lib/api.ts): backend client · Encapsulates REST and streaming calls to the backend · `src/lib/api.ts`

### Infra

Runtime settings, persistence, and observability

- [Config](https://github.com/bairoy/financial-msa/blob/main/backend/app/config.py): env settings · OpenAI, LangSmith, and runtime configuration · `backend/app/config.py`
- [Memory](https://github.com/bairoy/financial-msa/blob/main/backend/app/agents/shared/memory.py): memory layer · Short-term, long-term, and audit persistence helpers · `backend/app/agents/shared/memory.py`
- **LangSmith**: tracing service · Execution tracing and nested span observability
- **OpenAI**: model provider · LLM and embedding provider
- [Postgres](https://github.com/bairoy/financial-msa/blob/main/backend/docker-compose.yml): database · Containerized local persistence via compose · `backend/docker-compose.yml`
- **FAISS**: vector index · Semantic retrieval store for knowledge-backed answers

## Connections

- 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
