# chanduchowday25/agent-os architecture

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

- Interactive diagram: https://gitdiagram.com/chanduchowday25/agent-os
- Repository: https://github.com/chanduchowday25/agent-os

## Overview

AgentOS is a multi-agent workspace for document-grounded chat, analytics, and reports. Users interact through the React application; its chat service calls the FastAPI API, while the backend’s agent workflow coordinates specialized agents. Document Q&A stages include upload, extraction and chunking, embedding and indexing, hybrid retrieval, relevance gating, and grounded response with citations. The sampled source confirms ingestion, retrieval, embedding, and RAG internals; route-to-service wiring for uploads, analytics, reports, and persistence was not sampled, so those capabilities are shown without speculative connections.

Main entry points: [`agentos-scaffold/backend/api/v1/router.py`](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/api/v1/router.py) (API router), [`agentos-scaffold/frontend/src/App.jsx`](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/frontend/src/App.jsx) (React app), [`agentos-scaffold/backend/services/retrieval_service.py`](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/services/retrieval_service.py) (Hybrid retrieval), [`agentos-scaffold/backend/services/embedding_service.py`](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/services/embedding_service.py) (Embedding service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User workspace"]
  node_app["React app<br/>[App.jsx]"]
  node_workspace["Workspace<br/>[Workspace.jsx]"]
  node_analytics_ui["Analytics page<br/>[Analytics.jsx]"]
  node_reports_ui["Reports page<br/>[Reports.jsx]"]
  node_chat_hook["Chat state<br/>[useChat.js]"]
  node_chat_client["Chat API client<br/>[chatService.js]"]
end

subgraph group_api["API surface"]
  node_api_router["API router<br/>[router.py]"]
  node_chat_route["Chat endpoint<br/>[chat.py]"]
  node_upload_route["Upload endpoint<br/>[upload.py]"]
  node_analyze_route["Analysis endpoint<br/>[analyze.py]"]
  node_reports_route["Reports endpoint<br/>[reports.py]"]
  node_conversation_route["Conversation endpoints<br/>[conversations.py]"]
end

subgraph group_agents["Agent orchestration"]
  node_workflow["Agent workflow<br/>[agent_workflow.py]"]
  node_supervisor["Supervisor agent"]
  node_rag_agent["RAG agent<br/>[rag_agent.py]"]
  node_analytics_agent["Analytics agent<br/>[analytics_agent.py]"]
  node_research_agent["Research agent<br/>[research_agent.py]"]
end

subgraph group_documents["Document intelligence"]
  node_ingestion["Document ingestion"]
  node_retrieval["Hybrid retrieval"]
  node_chroma[("Vector index<br/>[chroma_client.py]")]
end

subgraph group_services["Shared services"]
  node_embedding["Embedding service"]
  node_llm["LLM service<br/>[llm_service.py]"]
end

node_user(("User"))
node_gemini["Gemini embeddings"]
node_groq["Groq model API"]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_workspace
node_app -->|"routes to"| node_analytics_ui
node_app -->|"routes to"| node_reports_ui
node_workspace -->|"uses"| node_chat_hook
node_chat_hook -->|"calls"| node_chat_client
node_chat_client -->|"HTTP request"| node_chat_route
node_api_router -->|"dispatches"| node_chat_route
node_api_router -->|"dispatches"| node_upload_route
node_api_router -->|"dispatches"| node_analyze_route
node_api_router -->|"dispatches"| node_reports_route
node_api_router -->|"dispatches"| node_conversation_route
node_ingestion -->|"embeds chunks"| node_embedding
node_ingestion -->|"indexes chunks"| node_chroma
node_retrieval -->|"embeds query"| node_embedding
node_retrieval -->|"searches index"| node_chroma
node_rag_agent -->|"retrieves context"| node_retrieval
node_rag_agent -->|"generates answer"| node_llm
node_embedding -->|"requests embeddings"| node_gemini
node_llm -->|"requests completion"| node_groq

click node_app "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/frontend/src/App.jsx"
click node_workspace "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/frontend/src/pages/Workspace.jsx"
click node_analytics_ui "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/frontend/src/pages/Analytics.jsx"
click node_reports_ui "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/frontend/src/pages/Reports.jsx"
click node_chat_hook "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/frontend/src/hooks/useChat.js"
click node_chat_client "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/frontend/src/services/chatService.js"
click node_api_router "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/api/v1/router.py"
click node_chat_route "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/api/v1/routes/chat.py"
click node_upload_route "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/api/v1/routes/upload.py"
click node_analyze_route "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/api/v1/routes/analyze.py"
click node_reports_route "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/api/v1/routes/reports.py"
click node_conversation_route "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/api/v1/routes/conversations.py"
click node_workflow "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/workflows/agent_workflow.py"
click node_supervisor "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/agents/supervisor_agent.py"
click node_rag_agent "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/agents/rag_agent.py"
click node_analytics_agent "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/agents/analytics_agent.py"
click node_research_agent "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/agents/research_agent.py"
click node_ingestion "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/services/document_ingestion_service.py"
click node_retrieval "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/services/retrieval_service.py"
click node_chroma "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/database/chroma_client.py"
click node_embedding "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/services/embedding_service.py"
click node_llm "https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/services/llm_service.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_analytics_ui,node_reports_ui,node_chat_hook,node_chat_client,node_user toneBlue
class node_api_router,node_chat_route,node_upload_route,node_analyze_route,node_reports_route,node_conversation_route toneAmber
class node_workflow,node_supervisor,node_rag_agent,node_analytics_agent,node_research_agent,node_groq toneMint
class node_ingestion,node_retrieval,node_chroma toneRose
class node_embedding,node_llm,node_gemini toneIndigo
```

## Components

### User workspace

- [React app](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/frontend/src/App.jsx): `agentos-scaffold/frontend/src/App.jsx`
- [Workspace](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/frontend/src/pages/Workspace.jsx): `agentos-scaffold/frontend/src/pages/Workspace.jsx`
- [Analytics page](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/frontend/src/pages/Analytics.jsx): `agentos-scaffold/frontend/src/pages/Analytics.jsx`
- [Reports page](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/frontend/src/pages/Reports.jsx): `agentos-scaffold/frontend/src/pages/Reports.jsx`
- [Chat state](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/frontend/src/hooks/useChat.js): `agentos-scaffold/frontend/src/hooks/useChat.js`
- [Chat API client](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/frontend/src/services/chatService.js): `agentos-scaffold/frontend/src/services/chatService.js`

### API surface

- [API router](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/api/v1/router.py): `agentos-scaffold/backend/api/v1/router.py`
- [Chat endpoint](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/api/v1/routes/chat.py): `agentos-scaffold/backend/api/v1/routes/chat.py`
- [Upload endpoint](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/api/v1/routes/upload.py): `agentos-scaffold/backend/api/v1/routes/upload.py`
- [Analysis endpoint](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/api/v1/routes/analyze.py): `agentos-scaffold/backend/api/v1/routes/analyze.py`
- [Reports endpoint](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/api/v1/routes/reports.py): `agentos-scaffold/backend/api/v1/routes/reports.py`
- [Conversation endpoints](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/api/v1/routes/conversations.py): `agentos-scaffold/backend/api/v1/routes/conversations.py`

### Agent orchestration

- [Agent workflow](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/workflows/agent_workflow.py): `agentos-scaffold/backend/workflows/agent_workflow.py`
- [Supervisor agent](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/agents/supervisor_agent.py): `agentos-scaffold/backend/agents/supervisor_agent.py`
- [RAG agent](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/agents/rag_agent.py): `agentos-scaffold/backend/agents/rag_agent.py`
- [Analytics agent](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/agents/analytics_agent.py): `agentos-scaffold/backend/agents/analytics_agent.py`
- [Research agent](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/agents/research_agent.py): `agentos-scaffold/backend/agents/research_agent.py`

### Document intelligence

- [Document ingestion](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/services/document_ingestion_service.py): `agentos-scaffold/backend/services/document_ingestion_service.py`
- [Hybrid retrieval](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/services/retrieval_service.py): `agentos-scaffold/backend/services/retrieval_service.py`
- [Vector index](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/database/chroma_client.py): `agentos-scaffold/backend/database/chroma_client.py`

### Shared services

- [Embedding service](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/services/embedding_service.py): `agentos-scaffold/backend/services/embedding_service.py`
- [LLM service](https://github.com/chanduchowday25/agent-os/blob/main/agentos-scaffold/backend/services/llm_service.py): `agentos-scaffold/backend/services/llm_service.py`

### Other components

- **User**
- **Gemini embeddings**
- **Groq model API**

## Connections

- User → React app: uses
- React app → Workspace: routes to
- React app → Analytics page: routes to
- React app → Reports page: routes to
- Workspace → Chat state: uses
- Chat state → Chat API client: calls
- Chat API client → Chat endpoint: HTTP request
- API router → Chat endpoint: dispatches
- API router → Upload endpoint: dispatches
- API router → Analysis endpoint: dispatches
- API router → Reports endpoint: dispatches
- API router → Conversation endpoints: dispatches
- Document ingestion → Embedding service: embeds chunks
- Document ingestion → Vector index: indexes chunks
- Hybrid retrieval → Embedding service: embeds query
- Hybrid retrieval → Vector index: searches index
- RAG agent → Hybrid retrieval: retrieves context
- RAG agent → LLM service: generates answer
- Embedding service → Gemini embeddings: requests embeddings
- LLM service → Groq model API: requests completion