# aniketsarapai/supervisor-multi-agent architecture

> Architecture diagram of the GitHub repository aniketsarapai/supervisor-multi-agent, 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/aniketsarapai/supervisor-multi-agent
- Repository: https://github.com/aniketsarapai/supervisor-multi-agent

## Overview

1. **Overall shape**
This repo is a two-service Python application: a **FastAPI backend** handles auth, chat orchestration, persistence, and streaming; a **Streamlit frontend** provides the chat UI and login flow. The two services are intentionally separated and communicate over HTTP, with the frontend calling backend APIs through a configurable `BACKEND_URL`.

2. **Client-facing boundary**
The user interacts only with the Streamlit app. That UI is responsible for sign-in/sign-up, showing session history, sending chat requests, and consuming streamed responses. It does not run the agent logic itself; it is a thin presentation layer over backend APIs.

3. **Backend API boundary**
`backend/fastapi_backend.py` is the main service entry point. It exposes:
- public health and welcome endpoints,
- a token refresh endpoint,
- protected session/history endpoints,
- and the protected `/chat_stream` endpoint for real-time agent responses.
This is the main architectural boundary between external clients and the agent system.

4. **Authentication and request protection**
Auth is Supabase-based. The frontend uses Supabase auth for email/password sign-in. The backend validates incoming JWTs in `backend/auth.py` using Supabase issuer/audience/signing configuration, and protected routes require `Authorization: Bearer <token>`. This creates a clear trust boundary: only authenticated users can stream chats or access their session data.

5. **Conversation orchestration core**
The heart of the system is the LangGraph supervisor in `backend/ai_agent.py`, with supporting graph/state/tool definitions centralized in `utils.py`. The supervisor routes each user prompt to the best specialist agent rather than using one monolithic model. This is the key decision point in the architecture.

6. **Specialist agents**
The agent layer includes separate behaviors for greeting, query refinement, coding, math reasoning, and research. The supervisor delegates to one of these specialists based on the request. For an architecture diagram, this is best shown as one supervisor node feeding multiple specialist nodes, not as independent parallel services.

7. **Tool execution layer**
Specialist agents can invoke tools through the shared utility layer in `utils.py`. The tools include Tavily search, DuckDuckGo, Wikipedia, PubMed, a Python REPL, and a calculator via `numexpr`. This means the agent layer is not just model inference; it can branch into external knowledge and computation services when needed.

8. **Streaming data flow**
The primary runtime path is: Streamlit sends a chat request to FastAPI, FastAPI validates the JWT, resolves the session/thread, loads prior graph state, appends the user message, then streams LangGraph events back as **server-sent events (SSE)**. The frontend incrementally renders partial output as it arrives. This is a one-way streaming architecture, not bidirectional WebSockets.

9. **Session persistence**
There are two persistence concerns. First, chat history is stored per authenticated user via Supabase-backed helpers in `backend/supabase_database.py`. Second, LangGraph state can be checkpointed either in-memory for simple local runs or in Postgres when `SUPABASE_DB_URL` is configured. So the app persists both user-visible conversation history and agent execution state.

10. **Frontend responsibilities**
`frontend/streamlit_frontend.py` owns the UX: login forms, session list/sidebar, message composer, and live stream rendering. It also persists individual chat messages through backend session APIs, rather than writing directly to the database. That keeps all database writes behind the backend boundary.

11. **Deployment and runtime topology**
The repo is designed for containerized deployment. `Dockerfile.backend` and `Dockerfile.frontend` build separate images, `docker-compose.yml` runs them locally, and `cloudbuild.yaml` builds and deploys both to Google Cloud Run. In Cloud Run, the backend is deployed first and its URL is injected into the frontend as `BACKEND_URL`.

12. **Operational dependencies**
The architecture depends materially on external services: **Supabase** for auth and storage, **OpenRouter** (or optionally Groq/OpenAI) for model access, **Tavily** for web search, and optionally **LangSmith** for tracing. These are not incidental libraries; they define how the backend gets identity, model responses, tool access, and observability.

13. **What to emphasize in a diagram**
A useful diagram should show: user → Streamlit UI → FastAPI backend → JWT validation / session persistence → LangGraph supervisor → specialist agents → external tools/LLM provider → SSE stream back to UI. Supabase should appear as both auth provider and data store, and the optional Postgres checkpoint path should be shown separately from chat-history persistence.

14. **Key architectural boundary**
The most important boundary in the repo is between the **presentation layer** (Streamlit) and the **agent/orchestration layer** (FastAPI + LangGraph). Everything important about trust, persistence, streaming, and tool usage lives on the backend side, while the frontend remains mostly a stateful consumer of backend APIs.

Main entry points: [`utils.py`](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/utils.py) (Tools), [`backend/ai_agent.py`](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/ai_agent.py) (Supervisor), [`backend/fastapi_backend.py`](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/fastapi_backend.py) (API server), [`frontend/streamlit_frontend.py`](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/frontend/streamlit_frontend.py) (Chat UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_streamlit_ui["Chat UI<br/>streamlit app"]
end

subgraph group_backend["Backend"]
  node_backend_api["API server<br/>fastapi service<br/>[fastapi_backend.py]"]
  node_jwt_auth["JWT auth<br/>auth middleware<br/>[auth.py]"]
  node_session_store[("Session store<br/>database helper")]
  node_agent_graph{{"Supervisor<br/>langgraph orchestrator<br/>[ai_agent.py]"}}
  node_agent_state["Graph state<br/>state and checkpoints<br/>[utils.py]"]
  node_greeting_agent["Greeting<br/>specialist agent<br/>[ai_agent.py]"]
  node_refine_agent["Refiner<br/>specialist agent<br/>[ai_agent.py]"]
  node_coding_agent["Coding<br/>specialist agent<br/>[ai_agent.py]"]
  node_math_agent["Math<br/>specialist agent<br/>[ai_agent.py]"]
  node_research_agent["Research<br/>specialist agent<br/>[ai_agent.py]"]
  node_toolkit{{"Tools<br/>tool layer<br/>[utils.py]"}}
end

subgraph group_integrations["External services"]
  node_llm_provider(("Model API<br/>llm provider"))
  node_supabase[("Supabase<br/>auth and data platform")]
  node_search_services["Search APIs<br/>web research"]
  node_python_calc{{"Python exec<br/>compute tool"}}
end

subgraph group_deployment["Deployment"]
  node_cloudrun_backend["Backend image<br/>container<br/>[Dockerfile.backend]"]
  node_cloudrun_frontend["Frontend image<br/>container"]
  node_compose["Compose<br/>local runtime<br/>[docker-compose.yml]"]
  node_cloudbuild["Cloud build<br/>ci cd<br/>[cloudbuild.yaml]"]
end

node_user(("User<br/>actor"))

node_user -->|"uses"| node_streamlit_ui
node_streamlit_ui -->|"HTTP API"| node_backend_api
node_backend_api -->|"protects"| node_jwt_auth
node_jwt_auth -->|"verifies"| node_supabase
node_backend_api -->|"reads/writes"| node_session_store
node_backend_api -->|"streams"| node_agent_graph
node_agent_graph -->|"uses"| node_agent_state
node_agent_graph -->|"routes to"| node_greeting_agent
node_agent_graph -->|"routes to"| node_refine_agent
node_agent_graph -->|"routes to"| node_coding_agent
node_agent_graph -->|"routes to"| node_math_agent
node_agent_graph -->|"routes to"| node_research_agent
node_greeting_agent -.->|"may call"| node_toolkit
node_refine_agent -.->|"may call"| node_toolkit
node_coding_agent -.->|"may call"| node_toolkit
node_math_agent -.->|"may call"| node_toolkit
node_research_agent -.->|"may call"| node_toolkit
node_toolkit -->|"uses"| node_llm_provider
node_toolkit -->|"uses"| node_search_services
node_toolkit -->|"uses"| node_python_calc
node_backend_api -->|"history/auth data"| node_supabase
node_streamlit_ui -->|"SSE stream"| node_backend_api
node_compose -.->|"runs"| node_cloudrun_backend
node_compose -.->|"runs"| node_cloudrun_frontend
node_cloudbuild -->|"builds"| node_cloudrun_backend
node_cloudbuild -->|"builds"| node_cloudrun_frontend
node_cloudrun_frontend -->|"BACKEND_URL"| node_backend_api

click node_streamlit_ui "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/frontend/streamlit_frontend.py"
click node_backend_api "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/fastapi_backend.py"
click node_jwt_auth "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/auth.py"
click node_session_store "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/supabase_database.py"
click node_agent_graph "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/ai_agent.py"
click node_agent_state "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/utils.py"
click node_greeting_agent "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/ai_agent.py"
click node_refine_agent "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/ai_agent.py"
click node_coding_agent "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/ai_agent.py"
click node_math_agent "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/ai_agent.py"
click node_research_agent "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/ai_agent.py"
click node_toolkit "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/utils.py"
click node_cloudrun_backend "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/Dockerfile.backend"
click node_cloudrun_frontend "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/Dockerfile.frontend"
click node_compose "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/docker-compose.yml"
click node_cloudbuild "https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/cloudbuild.yaml"

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_streamlit_ui toneBlue
class node_backend_api,node_jwt_auth,node_session_store,node_agent_graph,node_agent_state,node_greeting_agent,node_refine_agent,node_coding_agent,node_math_agent,node_research_agent,node_toolkit toneAmber
class node_llm_provider,node_supabase,node_search_services,node_python_calc toneMint
class node_cloudrun_backend,node_cloudrun_frontend,node_compose,node_cloudbuild toneRose
class node_user toneNeutral
```

## Components

### Frontend

Streamlit presentation layer and chat UX

- [Chat UI](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/frontend/streamlit_frontend.py): streamlit app · Login, session list, message composer, and live response rendering · `frontend/streamlit_frontend.py`

### Backend

FastAPI API, auth, orchestration, and persistence

- [API server](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/fastapi_backend.py): fastapi service · Main HTTP boundary for auth, history, and chat streaming · `backend/fastapi_backend.py`
- [JWT auth](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/auth.py): auth middleware · Validates Supabase-issued bearer tokens for protected routes · `backend/auth.py`
- [Session store](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/supabase_database.py): database helper · Persists user-visible chat history and session metadata · `backend/supabase_database.py`
- [Supervisor](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/ai_agent.py): langgraph orchestrator · Routes each prompt to the best specialist agent · `backend/ai_agent.py`
- [Graph state](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/utils.py): state and checkpoints · Shared message/state definitions and checkpointing setup · `utils.py`
- [Greeting](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/ai_agent.py): specialist agent · Handles friendly openings and simple conversational turns · `backend/ai_agent.py`
- [Refiner](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/ai_agent.py): specialist agent · Rewrites or clarifies user questions before deeper handling · `backend/ai_agent.py`
- [Coding](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/ai_agent.py): specialist agent · Supports programming and code-oriented requests · `backend/ai_agent.py`
- [Math](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/ai_agent.py): specialist agent · Performs reasoning and calculation-heavy tasks · `backend/ai_agent.py`
- [Research](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/backend/ai_agent.py): specialist agent · Answers with search-backed and source-backed assistance · `backend/ai_agent.py`
- [Tools](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/utils.py): tool layer · Shared external tools for search, lookup, and computation · `utils.py`

### External services

Identity, model, search, and observability dependencies

- **Model API**: llm provider · OpenRouter or alternate model backend used by agents
- **Supabase**: auth and data platform · Email/password auth, JWT issuer, and application data storage
- **Search APIs**: web research · Tavily, DuckDuckGo, Wikipedia, and PubMed lookups
- **Python exec**: compute tool · Python REPL and numexpr-based calculation support

### Deployment

Container and cloud runtime entrypoints

- [Backend image](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/Dockerfile.backend): container · Built backend runtime for Cloud Run or local compose · `Dockerfile.backend`
- [Frontend image](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/Dockerfile.frontend): container · Built frontend runtime for Cloud Run or local compose · `Dockerfile.frontend`
- [Compose](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/docker-compose.yml): local runtime · Runs backend and frontend together for local development · `docker-compose.yml`
- [Cloud build](https://github.com/aniketsarapai/supervisor-multi-agent/blob/main/cloudbuild.yaml): ci cd · Builds and deploys both services to Cloud Run · `cloudbuild.yaml`

### Other components

- **User**: actor · Signs in and chats through the UI

## Connections

- User → Chat UI: uses · User interacts with the chat application
- Chat UI → API server: HTTP API · Frontend sends login, session, and chat requests to the backend
- API server → JWT auth: protects · Protected routes validate bearer tokens before access
- JWT auth → Supabase: verifies · JWT issuer, audience, and signing config come from Supabase
- API server → Session store: reads/writes · Stores and fetches user-visible session history
- API server → Supervisor: streams · Requests are handed to the LangGraph supervisor for orchestration
- Supervisor → Graph state: uses · Supervisor loads state and checkpointing context
- Supervisor → Greeting: routes to · Delegates simple conversational turns
- Supervisor → Refiner: routes to · Delegates query clarification and rewriting
- Supervisor → Coding: routes to · Delegates programming tasks
- Supervisor → Math: routes to · Delegates reasoning and calculation tasks
- Supervisor → Research: routes to · Delegates research-oriented tasks
- Greeting → Tools: may call · Specialists can use shared tools when needed
- Refiner → Tools: may call · Specialists can use shared tools when needed
- Coding → Tools: may call · Specialists can use shared tools when needed
- Math → Tools: may call · Specialists can use shared tools when needed
- Research → Tools: may call · Specialists can use shared tools when needed
- Tools → Model API: uses · Agents obtain model responses from the configured provider
- Tools → Search APIs: uses · Research tools query external knowledge sources
- Tools → Python exec: uses · Math and code tools execute local computation
- API server → Supabase: history/auth data · Backend persists user-related data through Supabase-backed helpers
- Chat UI → API server: SSE stream · Frontend consumes streamed chat events incrementally
- Compose → Backend image: runs · Local composition includes the backend service image
- Compose → Frontend image: runs · Local composition includes the frontend service image
- Cloud build → Backend image: builds · CI builds and deploys the backend container
- Cloud build → Frontend image: builds · CI builds and deploys the frontend container
- Frontend image → API server: BACKEND_URL · Frontend runtime targets the deployed backend over HTTP
