# adityamhaske/multi-agent-research-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/adityamhaske/multi-agent-research-assistant
- Repository: https://github.com/adityamhaske/multi-agent-research-assistant

## Overview

Multi-Agent Research Assistant is a self-hostable and desktop research product. A user submits a question, reviews and approves the proposed plan before research, then reviews the cited draft before approval freezes a verifiable report artifact. The graph preserves the distinct planning, evidence gathering, critique, synthesis, human-review, and verification stages, plus corpus and grounded-chat capabilities. Source excerpts are partial, so some subsystem links follow the README’s documented workflow rather than inspected call sites; uncertain internal wiring is omitted.

Main entry points: [`backend/app/api/v1/router.py`](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/api/v1/router.py) (Versioned API), [`backend/app/api/v1/runs.py`](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/api/v1/runs.py) (Run endpoints), [`backend/app/workers/pipeline_runner.py`](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/workers/pipeline_runner.py) (Pipeline worker), [`backend/research_engine/graph.py`](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/research_engine/graph.py) (Agent pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interfaces"]
  node_research_ui["Research workspace<br/>[page.tsx]"]
  node_run_ui["Run review<br/>[page.tsx]"]
  node_session_ui["Live session<br/>[SessionView.tsx]"]
  node_chat_ui["Project chat<br/>[page.tsx]"]
end

subgraph group_service["Application services"]
  node_api["Versioned API<br/>[router.py]"]
  node_research_api["Research endpoints<br/>[research.py]"]
  node_runs_api["Run endpoints<br/>[runs.py]"]
  node_corpus_api["Corpus endpoints<br/>[corpus.py]"]
  node_chat_api["Chat endpoints<br/>[chat.py]"]
  node_worker["Pipeline worker<br/>[pipeline_runner.py]"]
  node_export["Artifact export<br/>[export.py]"]
end

subgraph group_engine["Research engine"]
  node_runner["Research orchestrator<br/>[runner.py]"]
  node_agents["Agent pipeline<br/>[graph.py]"]
  node_tools["Research tools<br/>[tools.py]"]
  node_corpus["Project corpus<br/>[corpus.py]"]
  node_verifier["Offline verifier<br/>[verify_bundle.py]"]
end

subgraph group_records["Research records"]
  node_reports[("Report and claims<br/>[research.py]")]
  node_reviews[("Reviews and approvals<br/>[review.py]")]
end

node_user(("Researcher"))
node_provider["Model providers"]
node_web["Web sources"]
node_store[("Application database")]

node_user -->|"asks question"| node_research_ui
node_research_ui -->|"starts research"| node_research_api
node_run_ui -->|"reviews run"| node_runs_api
node_session_ui -->|"streams events"| node_research_api
node_chat_ui -->|"asks follow-up"| node_chat_api
node_api -->|"routes requests"| node_research_api
node_api -->|"routes requests"| node_runs_api
node_api -->|"routes requests"| node_corpus_api
node_api -->|"routes requests"| node_chat_api
node_research_api -->|"dispatches run"| node_worker
node_runs_api -->|"resumes run"| node_worker
node_worker -->|"runs or resumes"| node_runner
node_runner -->|"executes graph"| node_agents
node_agents -->|"invokes tools"| node_tools
node_tools -.->|"searches and reads"| node_web
node_agents -.->|"calls models"| node_provider
node_corpus_api -->|"ingests documents"| node_corpus
node_corpus -->|"supplies evidence"| node_agents
node_runner -->|"records research"| node_reports
node_runs_api -->|"records decisions"| node_reviews
node_reports -->|"persists records"| node_store
node_reviews -->|"persists approvals"| node_store
node_export -->|"exports report"| node_reports
node_export -->|"includes approval"| node_reviews
node_verifier -->|"checks bundle offline"| node_user
node_worker -.->|"resolves model routes"| node_provider

click node_research_ui "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/frontend/app/(app)/research/page.tsx"
click node_run_ui "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/frontend/app/(app)/research/run/page.tsx"
click node_session_ui "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/frontend/components/session/SessionView.tsx"
click node_chat_ui "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/frontend/app/(app)/chat/page.tsx"
click node_api "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/api/v1/router.py"
click node_research_api "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/api/v1/research.py"
click node_runs_api "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/api/v1/runs.py"
click node_corpus_api "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/api/v1/corpus.py"
click node_chat_api "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/api/v1/chat.py"
click node_worker "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/workers/pipeline_runner.py"
click node_runner "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/research_engine/runner.py"
click node_agents "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/research_engine/graph.py"
click node_tools "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/research_engine/tools.py"
click node_corpus "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/research_engine/corpus.py"
click node_reports "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/models/research.py"
click node_reviews "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/models/review.py"
click node_export "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/services/export.py"
click node_verifier "https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/research_engine/verify_bundle.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_research_ui,node_run_ui,node_session_ui,node_chat_ui toneBlue
class node_api,node_research_api,node_runs_api,node_corpus_api,node_chat_api,node_worker,node_export,node_store toneAmber
class node_runner,node_agents,node_tools,node_corpus,node_verifier toneMint
class node_reports,node_reviews toneRose
class node_user,node_provider,node_web toneIndigo
```

## Components

### User interfaces

- [Research workspace](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/frontend/app/(app)/research/page.tsx): `frontend/app/(app)/research/page.tsx`
- [Run review](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/frontend/app/(app)/research/run/page.tsx): `frontend/app/(app)/research/run/page.tsx`
- [Live session](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/frontend/components/session/SessionView.tsx): `frontend/components/session/SessionView.tsx`
- [Project chat](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/frontend/app/(app)/chat/page.tsx): `frontend/app/(app)/chat/page.tsx`

### Application services

- [Versioned API](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Research endpoints](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/api/v1/research.py): `backend/app/api/v1/research.py`
- [Run endpoints](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/api/v1/runs.py): `backend/app/api/v1/runs.py`
- [Corpus endpoints](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/api/v1/corpus.py): `backend/app/api/v1/corpus.py`
- [Chat endpoints](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/api/v1/chat.py): `backend/app/api/v1/chat.py`
- [Pipeline worker](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/workers/pipeline_runner.py): `backend/app/workers/pipeline_runner.py`
- [Artifact export](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/services/export.py): `backend/app/services/export.py`

### Research engine

- [Research orchestrator](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/research_engine/runner.py): `backend/research_engine/runner.py`
- [Agent pipeline](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/research_engine/graph.py): `backend/research_engine/graph.py`
- [Research tools](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/research_engine/tools.py): `backend/research_engine/tools.py`
- [Project corpus](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/research_engine/corpus.py): `backend/research_engine/corpus.py`
- [Offline verifier](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/research_engine/verify_bundle.py): `backend/research_engine/verify_bundle.py`

### Research records

- [Report and claims](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/models/research.py): `backend/app/models/research.py`
- [Reviews and approvals](https://github.com/adityamhaske/multi-agent-research-assistant/blob/main/backend/app/models/review.py): `backend/app/models/review.py`

### Other components

- **Researcher**
- **Model providers**
- **Web sources**
- **Application database**

## Connections

- Researcher → Research workspace: asks question
- Research workspace → Research endpoints: starts research
- Run review → Run endpoints: reviews run
- Live session → Research endpoints: streams events
- Project chat → Chat endpoints: asks follow-up
- Versioned API → Research endpoints: routes requests
- Versioned API → Run endpoints: routes requests
- Versioned API → Corpus endpoints: routes requests
- Versioned API → Chat endpoints: routes requests
- Research endpoints → Pipeline worker: dispatches run
- Run endpoints → Pipeline worker: resumes run
- Pipeline worker → Research orchestrator: runs or resumes
- Research orchestrator → Agent pipeline: executes graph
- Agent pipeline → Research tools: invokes tools
- Research tools → Web sources: searches and reads
- Agent pipeline → Model providers: calls models
- Corpus endpoints → Project corpus: ingests documents
- Project corpus → Agent pipeline: supplies evidence
- Research orchestrator → Report and claims: records research
- Run endpoints → Reviews and approvals: records decisions
- Report and claims → Application database: persists records
- Reviews and approvals → Application database: persists approvals
- Artifact export → Report and claims: exports report
- Artifact export → Reviews and approvals: includes approval
- Offline verifier → Researcher: checks bundle offline
- Pipeline worker → Model providers: resolves model routes