# aastik0303/orchestrator_system architecture

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

- Interactive diagram: https://gitdiagram.com/aastik0303/orchestrator_system
- Repository: https://github.com/aastik0303/orchestrator_system

## Overview

This is a runnable multi-agent chat starter: a user submits a message, optional files, and an agent choice; the chat API persists the conversation, invokes the LangGraph workflow, and returns the selected worker’s response. The workflow routes, validates, retries, and falls back. The repository also includes a React dashboard with workspace and operational pages. Several worker capabilities are scaffolded; frontend-to-backend wiring and some worker internals were not shown, so uncertain connections are omitted.

Main entry points: [`backend/app/orchestrator/langgraph_flow.py`](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/orchestrator/langgraph_flow.py) (LangGraph workflow), [`backend/app/orchestrator/supervisor.py`](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/orchestrator/supervisor.py) (Agent registry), [`backend/app/routes/chat.py`](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/routes/chat.py) (Chat and uploads), [`frontend/src/App.tsx`](https://github.com/aastik0303/orchestrator_system/blob/main/frontend/src/App.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["App shell<br/>[App.tsx]"]
  node_workspace["Chat workspace<br/>[WorkspacePage.tsx]"]
  node_dashboard["Dashboard<br/>[DashboardPage.tsx]"]
  node_ops_pages["Operations pages"]
  node_api_client["API client<br/>[apiClient.ts]"]
end

subgraph group_api["Chat API and state"]
  node_main["FastAPI app<br/>[main.py]"]
  node_chat_api["Chat and uploads<br/>[chat.py]"]
  node_chat_store[("Chat session store<br/>[chat_store.py]")]
  node_runtime_metrics["Runtime snapshots<br/>[chat.py]"]
end

subgraph group_workflow["Orchestration"]
  node_request_models["Request and response models<br/>[models.py]"]
  node_graph["LangGraph workflow<br/>[langgraph_flow.py]"]
  node_agent_router["Agent selection<br/>[router.py]"]
  node_supervisor["Agent registry<br/>[supervisor.py]"]
  node_validation["Response validation<br/>[langgraph_flow.py]"]
  node_retry_fallback["Retry and fallback<br/>[langgraph_flow.py]"]
  node_checkpointer[("Workflow checkpointer<br/>[langgraph_flow.py]")]
end

subgraph group_workers["Worker agents"]
  node_general_research["Chat and research<br/>[general_chat.py]"]
  node_document_rag["Document RAG<br/>[document_rag.py]"]
  node_youtube_rag["YouTube RAG<br/>[youtube_rag.py]"]
  node_code_dev["Code development<br/>[code_dev.py]"]
  node_data_analyst["Data analysis<br/>[data_analyst.py]"]
  node_groq_client["Groq client<br/>[groq_client.py]"]
end

node_user(("Chat user"))
node_groq["Groq API"]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_workspace
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_ops_pages
node_main -->|"registers"| node_chat_api
node_main -->|"initializes"| node_graph
node_main -->|"initializes"| node_chat_store
node_chat_api -->|"reads and writes"| node_chat_store
node_chat_api -->|"invokes"| node_graph
node_chat_api -->|"constructs"| node_request_models
node_chat_api -->|"records runtime data"| node_runtime_metrics
node_graph -->|"processes"| node_request_models
node_graph -->|"selects agent"| node_agent_router
node_graph -->|"dispatches through"| node_supervisor
node_graph -->|"validates response"| node_validation
node_validation -->|"routes invalid response"| node_retry_fallback
node_graph -->|"persists workflow state"| node_checkpointer
node_supervisor -->|"registers worker"| node_general_research
node_supervisor -->|"registers worker"| node_document_rag
node_supervisor -->|"registers worker"| node_youtube_rag
node_supervisor -->|"registers worker"| node_code_dev
node_supervisor -->|"registers worker"| node_data_analyst
node_document_rag -->|"requests completion"| node_groq_client
node_general_research -->|"uses completion"| node_groq_client
node_code_dev -->|"uses completion"| node_groq_client
node_groq_client -->|"calls"| node_groq
node_workspace -.->|"uses"| node_api_client
node_api_client -.->|"sends chat requests"| node_chat_api

click node_app "https://github.com/aastik0303/orchestrator_system/blob/main/frontend/src/App.tsx"
click node_workspace "https://github.com/aastik0303/orchestrator_system/blob/main/frontend/src/components/workspace/WorkspacePage.tsx"
click node_dashboard "https://github.com/aastik0303/orchestrator_system/blob/main/frontend/src/components/dashboard/DashboardPage.tsx"
click node_ops_pages "https://github.com/aastik0303/orchestrator_system/tree/main/frontend/src/pages"
click node_api_client "https://github.com/aastik0303/orchestrator_system/blob/main/frontend/src/services/apiClient.ts"
click node_main "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/main.py"
click node_chat_api "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/routes/chat.py"
click node_chat_store "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/services/chat_store.py"
click node_runtime_metrics "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/routes/chat.py"
click node_request_models "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/models.py"
click node_graph "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/orchestrator/langgraph_flow.py"
click node_agent_router "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/orchestrator/router.py"
click node_supervisor "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/orchestrator/supervisor.py"
click node_validation "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/orchestrator/langgraph_flow.py"
click node_retry_fallback "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/orchestrator/langgraph_flow.py"
click node_checkpointer "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/orchestrator/langgraph_flow.py"
click node_general_research "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/agents/general_chat.py"
click node_document_rag "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/agents/document_rag.py"
click node_youtube_rag "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/agents/youtube_rag.py"
click node_code_dev "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/agents/code_dev.py"
click node_data_analyst "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/agents/data_analyst.py"
click node_groq_client "https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/services/groq_client.py"

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_app,node_workspace,node_dashboard,node_ops_pages,node_api_client,node_user toneBlue
class node_main,node_chat_api,node_chat_store,node_runtime_metrics toneAmber
class node_request_models,node_graph,node_agent_router,node_supervisor,node_validation,node_retry_fallback,node_checkpointer,node_groq toneMint
class node_general_research,node_document_rag,node_youtube_rag,node_code_dev,node_data_analyst,node_groq_client toneRose
```

## Components

### Web client

- [App shell](https://github.com/aastik0303/orchestrator_system/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Chat workspace](https://github.com/aastik0303/orchestrator_system/blob/main/frontend/src/components/workspace/WorkspacePage.tsx): `frontend/src/components/workspace/WorkspacePage.tsx`
- [Dashboard](https://github.com/aastik0303/orchestrator_system/blob/main/frontend/src/components/dashboard/DashboardPage.tsx): `frontend/src/components/dashboard/DashboardPage.tsx`
- [Operations pages](https://github.com/aastik0303/orchestrator_system/tree/main/frontend/src/pages): `frontend/src/pages`
- [API client](https://github.com/aastik0303/orchestrator_system/blob/main/frontend/src/services/apiClient.ts): `frontend/src/services/apiClient.ts`

### Chat API and state

- [FastAPI app](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/main.py): `backend/app/main.py`
- [Chat and uploads](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/routes/chat.py): `backend/app/routes/chat.py`
- [Chat session store](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/services/chat_store.py): `backend/app/services/chat_store.py`
- [Runtime snapshots](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/routes/chat.py): `backend/app/routes/chat.py`

### Orchestration

- [Request and response models](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/models.py): `backend/app/models.py`
- [LangGraph workflow](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/orchestrator/langgraph_flow.py): `backend/app/orchestrator/langgraph_flow.py`
- [Agent selection](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/orchestrator/router.py): `backend/app/orchestrator/router.py`
- [Agent registry](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/orchestrator/supervisor.py): `backend/app/orchestrator/supervisor.py`
- [Response validation](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/orchestrator/langgraph_flow.py): `backend/app/orchestrator/langgraph_flow.py`
- [Retry and fallback](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/orchestrator/langgraph_flow.py): `backend/app/orchestrator/langgraph_flow.py`
- [Workflow checkpointer](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/orchestrator/langgraph_flow.py): `backend/app/orchestrator/langgraph_flow.py`

### Worker agents

- [Chat and research](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/agents/general_chat.py): `backend/app/agents/general_chat.py`
- [Document RAG](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/agents/document_rag.py): `backend/app/agents/document_rag.py`
- [YouTube RAG](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/agents/youtube_rag.py): `backend/app/agents/youtube_rag.py`
- [Code development](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/agents/code_dev.py): `backend/app/agents/code_dev.py`
- [Data analysis](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/agents/data_analyst.py): `backend/app/agents/data_analyst.py`
- [Groq client](https://github.com/aastik0303/orchestrator_system/blob/main/backend/app/services/groq_client.py): `backend/app/services/groq_client.py`

### Other components

- **Chat user**
- **Groq API**

## Connections

- Chat user → App shell: uses (evidence: `README.md`)
- App shell → Chat workspace: routes to (evidence: `frontend/src/App.tsx`)
- App shell → Dashboard: routes to (evidence: `frontend/src/App.tsx`)
- App shell → Operations pages: routes to (evidence: `frontend/src/App.tsx`)
- FastAPI app → Chat and uploads: registers (evidence: `backend/app/main.py`)
- FastAPI app → LangGraph workflow: initializes (evidence: `backend/app/main.py`)
- FastAPI app → Chat session store: initializes (evidence: `backend/app/main.py`)
- Chat and uploads → Chat session store: reads and writes (evidence: `backend/app/routes/chat.py`)
- Chat and uploads → LangGraph workflow: invokes (evidence: `backend/app/routes/chat.py`)
- Chat and uploads → Request and response models: constructs (evidence: `backend/app/routes/chat.py`)
- Chat and uploads → Runtime snapshots: records runtime data (evidence: `backend/app/routes/chat.py`)
- LangGraph workflow → Request and response models: processes (evidence: `backend/app/orchestrator/langgraph_flow.py`)
- LangGraph workflow → Agent selection: selects agent (evidence: `backend/app/orchestrator/langgraph_flow.py`)
- LangGraph workflow → Agent registry: dispatches through (evidence: `backend/app/orchestrator/langgraph_flow.py`)
- LangGraph workflow → Response validation: validates response (evidence: `backend/app/orchestrator/langgraph_flow.py`)
- Response validation → Retry and fallback: routes invalid response (evidence: `backend/app/orchestrator/langgraph_flow.py`)
- LangGraph workflow → Workflow checkpointer: persists workflow state (evidence: `backend/app/orchestrator/langgraph_flow.py`)
- Agent registry → Chat and research: registers worker (evidence: `backend/app/orchestrator/supervisor.py`)
- Agent registry → Document RAG: registers worker (evidence: `backend/app/orchestrator/supervisor.py`)
- Agent registry → YouTube RAG: registers worker (evidence: `backend/app/orchestrator/supervisor.py`)
- Agent registry → Code development: registers worker (evidence: `backend/app/orchestrator/supervisor.py`)
- Agent registry → Data analysis: registers worker (evidence: `backend/app/orchestrator/supervisor.py`)
- Document RAG → Groq client: requests completion (evidence: `backend/app/agents/document_rag.py`)
- Chat and research → Groq client: uses completion (evidence: `backend/app/agents/general_chat.py`)
- Code development → Groq client: uses completion (evidence: `backend/app/agents/code_dev.py`)
- Groq client → Groq API: calls (evidence: `backend/app/services/groq_client.py`)
- Chat workspace → API client: uses
- API client → Chat and uploads: sends chat requests
