# ayushgupta-h/ai_reasearch architecture

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

- Interactive diagram: https://gitdiagram.com/ayushgupta-h/ai_reasearch
- Repository: https://github.com/ayushgupta-h/ai_reasearch

## Overview

Research AI is a multi-agent research product, exposed through a web client and backend services as well as a Python/CLI workflow. Its documented research run moves from query planning through evidence retrieval and analysis to report writing, peer review, revision, and export. The backend also exposes session, document, review, and report capabilities, with persistence and execution infrastructure supporting runs. Workflow stages follow the README’s architecture; some implementation details and API wiring are unsampled, so those links are omitted.

Main entry points: [`backend/app/services/research_service.py`](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/services/research_service.py) (Research Service), [`backend/orchestrator.py`](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/orchestrator.py) (Peer Review), [`backend/research_tasks.py`](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/research_tasks.py) (Task Worker), [`backend/app/infrastructure/research_executor.py`](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/infrastructure/research_executor.py) (Research Executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_web["Research UI<br/>[index.tsx]"]
  node_api_client["API Client<br/>[client.ts]"]
end

subgraph group_backend["Backend Services"]
  node_routes["Backend API"]
  node_research_service["Research Service"]
  node_report_service["Report Services"]
  node_review_service["Review Service<br/>[review_service.py]"]
end

subgraph group_research["Research Workflow"]
  node_query["Query Intake<br/>[query_intake.py]"]
  node_search["Source Search<br/>[search_sources.py]"]
  node_reader["Deep Reader<br/>[agent.py]"]
  node_analyst["Fact Analysis<br/>[orchestrator.py]"]
  node_writer["Report Writing<br/>[orchestrator.py]"]
  node_critic["Peer Review<br/>[orchestrator.py]"]
  node_refiner["Revision<br/>[orchestrator.py]"]
  node_exporter["Report Export<br/>[report_exporter.py]"]
  node_backend_pipeline["Research Pipeline<br/>[pipeline.py]"]
end

subgraph group_support["Runtime Support"]
  node_executor["Research Executor"]
  node_task_worker["Task Worker<br/>[research_tasks.py]"]
  node_events["Run Events<br/>[service.py]"]
end

subgraph group_persistence["Persistence"]
  node_sessions[("Session Manager<br/>[session_manager.py]")]
  node_database[("Application Database<br/>[session.py]")]
  node_storage["Document Storage<br/>[storage_service.py]"]
end

node_user(("Researcher"))

node_user -->|"submits research"| node_web
node_web -->|"requests data"| node_api_client
node_api_client -.->|"calls API"| node_routes
node_routes -.->|"handles research"| node_research_service
node_research_service -->|"executes run"| node_executor
node_executor -->|"builds orchestrator"| node_backend_pipeline
node_backend_pipeline -->|"starts workflow"| node_query
node_query -->|"plans then searches"| node_search
node_search -->|"finds pages for"| node_reader
node_reader -->|"supplies evidence"| node_analyst
node_analyst -->|"synthesizes for"| node_writer
node_writer -->|"submits report"| node_critic
node_critic -->|"requests revision"| node_refiner
node_refiner -->|"returns revision"| node_critic
node_critic -->|"approves report"| node_exporter
node_research_service -.->|"dispatches work"| node_task_worker
node_task_worker -->|"runs research"| node_executor
node_task_worker -->|"publishes outcomes"| node_events
node_research_service -->|"manages sessions"| node_sessions
node_report_service -->|"stores reports"| node_storage
node_review_service -->|"reads review data"| node_database

click node_web "https://github.com/ayushgupta-h/ai_reasearch/blob/main/frontend/src/pages/index.tsx"
click node_api_client "https://github.com/ayushgupta-h/ai_reasearch/blob/main/frontend/src/api/client.ts"
click node_routes "https://github.com/ayushgupta-h/ai_reasearch/tree/main/backend/app/api"
click node_research_service "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/services/research_service.py"
click node_report_service "https://github.com/ayushgupta-h/ai_reasearch/tree/main/backend/app/services"
click node_review_service "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/services/review_service.py"
click node_query "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/query_intake.py"
click node_search "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/search_sources.py"
click node_reader "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/agent.py"
click node_analyst "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/orchestrator.py"
click node_writer "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/orchestrator.py"
click node_critic "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/orchestrator.py"
click node_refiner "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/orchestrator.py"
click node_exporter "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/report_exporter.py"
click node_backend_pipeline "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/orchestration/pipeline.py"
click node_executor "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/infrastructure/research_executor.py"
click node_task_worker "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/research_tasks.py"
click node_events "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/events/service.py"
click node_sessions "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/session_manager.py"
click node_database "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/database/session.py"
click node_storage "https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/services/storage_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_web,node_api_client toneBlue
class node_routes,node_research_service,node_report_service,node_review_service toneAmber
class node_query,node_search,node_reader,node_analyst,node_writer,node_critic,node_refiner,node_exporter,node_backend_pipeline toneMint
class node_executor,node_task_worker,node_events toneRose
class node_sessions,node_database,node_storage,node_user toneIndigo
```

## Components

### Client

- [Research UI](https://github.com/ayushgupta-h/ai_reasearch/blob/main/frontend/src/pages/index.tsx): `frontend/src/pages/index.tsx`
- [API Client](https://github.com/ayushgupta-h/ai_reasearch/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Backend Services

- [Backend API](https://github.com/ayushgupta-h/ai_reasearch/tree/main/backend/app/api): `backend/app/api`
- [Research Service](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/services/research_service.py): `backend/app/services/research_service.py`
- [Report Services](https://github.com/ayushgupta-h/ai_reasearch/tree/main/backend/app/services): `backend/app/services`
- [Review Service](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/services/review_service.py): `backend/app/services/review_service.py`

### Research Workflow

- [Query Intake](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/query_intake.py): `backend/query_intake.py`
- [Source Search](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/search_sources.py): `backend/search_sources.py`
- [Deep Reader](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/agent.py): `backend/agent.py`
- [Fact Analysis](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/orchestrator.py): `backend/orchestrator.py`
- [Report Writing](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/orchestrator.py): `backend/orchestrator.py`
- [Peer Review](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/orchestrator.py): `backend/orchestrator.py`
- [Revision](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/orchestrator.py): `backend/orchestrator.py`
- [Report Export](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/report_exporter.py): `backend/report_exporter.py`
- [Research Pipeline](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/orchestration/pipeline.py): `backend/app/orchestration/pipeline.py`

### Runtime Support

- [Research Executor](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/infrastructure/research_executor.py): `backend/app/infrastructure/research_executor.py`
- [Task Worker](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/research_tasks.py): `backend/research_tasks.py`
- [Run Events](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/events/service.py): `backend/app/events/service.py`

### Persistence

- [Session Manager](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/session_manager.py): `backend/session_manager.py`
- [Application Database](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/database/session.py): `backend/app/database/session.py`
- [Document Storage](https://github.com/ayushgupta-h/ai_reasearch/blob/main/backend/app/services/storage_service.py): `backend/app/services/storage_service.py`

### Other components

- **Researcher**

## Connections

- Researcher → Research UI: submits research (evidence: `README.md`)
- Research UI → API Client: requests data (evidence: `frontend/src/pages/index.tsx`)
- API Client → Backend API: calls API
- Backend API → Research Service: handles research
- Research Service → Research Executor: executes run (evidence: `backend/app/services/research_service.py`)
- Research Executor → Research Pipeline: builds orchestrator (evidence: `backend/app/infrastructure/research_executor.py`)
- Research Pipeline → Query Intake: starts workflow (evidence: `backend/app/orchestration/pipeline.py`)
- Query Intake → Source Search: plans then searches (evidence: `README.md`)
- Source Search → Deep Reader: finds pages for (evidence: `README.md`)
- Deep Reader → Fact Analysis: supplies evidence (evidence: `README.md`)
- Fact Analysis → Report Writing: synthesizes for (evidence: `README.md`)
- Report Writing → Peer Review: submits report (evidence: `README.md`)
- Peer Review → Revision: requests revision (evidence: `README.md`)
- Revision → Peer Review: returns revision (evidence: `README.md`)
- Peer Review → Report Export: approves report (evidence: `README.md`)
- Research Service → Task Worker: dispatches work
- Task Worker → Research Executor: runs research (evidence: `backend/research_tasks.py`)
- Task Worker → Run Events: publishes outcomes (evidence: `backend/research_tasks.py`)
- Research Service → Session Manager: manages sessions (evidence: `backend/app/services/research_service.py`)
- Report Services → Document Storage: stores reports (evidence: `backend/app/services/storage_service.py`)
- Review Service → Application Database: reads review data
