# kkm121/multi-agent-research-assistant architecture

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

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

## Overview

This is a research-assistant application: a user submits a topic, optionally with a document, through the Chainlit chat; the UI streams progress and a final report from the FastAPI service. The LangGraph workflow generates expert personas, gathers facts, outlines and synthesizes a report, then critiques it and may revise it. The README also documents multi-user chat persistence and quantitative Ragas evaluation. The graph’s workflow and service links are shown in source; optional provider and database internals are represented only where excerpts support them.

Main entry points: [`ai_core/agents.py`](https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/agents.py) (Agent Operations), [`frontend/app.py`](https://github.com/kkm121/multi-agent-research-assistant/blob/main/frontend/app.py) (Chainlit Chat), [`ai_core/graph.py`](https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/graph.py) (LangGraph Workflow), [`backend/main.py`](https://github.com/kkm121/multi-agent-research-assistant/blob/main/backend/main.py) (FastAPI Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_chat["Chainlit Chat<br/>[app.py]"]
  node_chatdb[("Chat Persistence<br/>[app.py]")]
end

subgraph group_service["API Service"]
  node_api["FastAPI Service<br/>[main.py]"]
end

subgraph group_research["Research Workflow"]
  node_orchestrator["LangGraph Workflow<br/>[graph.py]"]
  node_personas["Persona Generation<br/>[graph.py]"]
  node_researchstage["Fact Research<br/>[graph.py]"]
  node_outlining["Report Outline<br/>[graph.py]"]
  node_synthesis["Report Synthesis<br/>[graph.py]"]
  node_critique["Critique Revision<br/>[graph.py]"]
  node_agents["Agent Operations<br/>[agents.py]"]
  node_schemas["Research Models<br/>[models.py]"]
  node_search["Search Tools<br/>[tools.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval["Ragas Evaluation<br/>[ragas_eval.py]"]
end

node_user(("Researcher"))
node_semantic["Semantic Scholar"]
node_duckduckgo["DuckDuckGo Search"]
node_llm["LLM Providers"]

node_user -->|"submits research"| node_chat
node_chat -->|"reads and writes"| node_chatdb
node_chat -->|"streams request"| node_api
node_api -->|"mounts UI"| node_chat
node_api -->|"invokes workflow"| node_orchestrator
node_orchestrator -->|"starts at"| node_personas
node_personas -->|"then researches"| node_researchstage
node_researchstage -->|"then outlines"| node_outlining
node_outlining -->|"then synthesizes"| node_synthesis
node_synthesis -->|"then critiques"| node_critique
node_critique -->|"revises if needed"| node_synthesis
node_personas -->|"generates personas"| node_agents
node_researchstage -->|"gathers facts"| node_agents
node_outlining -->|"generates outline"| node_agents
node_synthesis -->|"drafts report"| node_agents
node_critique -->|"reviews report"| node_agents
node_agents -->|"uses typed models"| node_schemas
node_orchestrator -->|"uses workflow state"| node_schemas
node_agents -->|"runs queries"| node_search
node_search -->|"searches papers"| node_semantic
node_search -->|"falls back to"| node_duckduckgo
node_agents -->|"calls model providers"| node_llm
node_eval -->|"evaluates output"| node_orchestrator

click node_chat "https://github.com/kkm121/multi-agent-research-assistant/blob/main/frontend/app.py"
click node_chatdb "https://github.com/kkm121/multi-agent-research-assistant/blob/main/frontend/app.py"
click node_api "https://github.com/kkm121/multi-agent-research-assistant/blob/main/backend/main.py"
click node_orchestrator "https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/graph.py"
click node_personas "https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/graph.py"
click node_researchstage "https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/graph.py"
click node_outlining "https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/graph.py"
click node_synthesis "https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/graph.py"
click node_critique "https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/graph.py"
click node_agents "https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/agents.py"
click node_schemas "https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/models.py"
click node_search "https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/tools.py"
click node_eval "https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/ragas_eval.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_chat,node_chatdb toneBlue
class node_api toneAmber
class node_orchestrator,node_personas,node_researchstage,node_outlining,node_synthesis,node_critique,node_agents,node_schemas,node_search toneMint
class node_eval toneRose
class node_user,node_semantic,node_duckduckgo,node_llm toneIndigo
```

## Components

### User Experience

- [Chainlit Chat](https://github.com/kkm121/multi-agent-research-assistant/blob/main/frontend/app.py): `frontend/app.py`
- [Chat Persistence](https://github.com/kkm121/multi-agent-research-assistant/blob/main/frontend/app.py): `frontend/app.py`

### API Service

- [FastAPI Service](https://github.com/kkm121/multi-agent-research-assistant/blob/main/backend/main.py): `backend/main.py`

### Research Workflow

- [LangGraph Workflow](https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/graph.py): `ai_core/graph.py`
- [Persona Generation](https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/graph.py): `ai_core/graph.py`
- [Fact Research](https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/graph.py): `ai_core/graph.py`
- [Report Outline](https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/graph.py): `ai_core/graph.py`
- [Report Synthesis](https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/graph.py): `ai_core/graph.py`
- [Critique Revision](https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/graph.py): `ai_core/graph.py`
- [Agent Operations](https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/agents.py): `ai_core/agents.py`
- [Research Models](https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/models.py): `ai_core/models.py`
- [Search Tools](https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/tools.py): `ai_core/tools.py`

### Evaluation

- [Ragas Evaluation](https://github.com/kkm121/multi-agent-research-assistant/blob/main/ai_core/ragas_eval.py): `ai_core/ragas_eval.py`

### Other components

- **Researcher**
- **Semantic Scholar**
- **DuckDuckGo Search**
- **LLM Providers**

## Connections

- Researcher → Chainlit Chat: submits research (evidence: `frontend/app.py`)
- Chainlit Chat → Chat Persistence: reads and writes (evidence: `frontend/app.py`)
- Chainlit Chat → FastAPI Service: streams request (evidence: `frontend/app.py`)
- FastAPI Service → Chainlit Chat: mounts UI (evidence: `backend/main.py`)
- FastAPI Service → LangGraph Workflow: invokes workflow (evidence: `backend/main.py`)
- LangGraph Workflow → Persona Generation: starts at (evidence: `ai_core/graph.py`)
- Persona Generation → Fact Research: then researches (evidence: `ai_core/graph.py`)
- Fact Research → Report Outline: then outlines (evidence: `ai_core/graph.py`)
- Report Outline → Report Synthesis: then synthesizes (evidence: `ai_core/graph.py`)
- Report Synthesis → Critique Revision: then critiques (evidence: `ai_core/graph.py`)
- Critique Revision → Report Synthesis: revises if needed (evidence: `ai_core/graph.py`)
- Persona Generation → Agent Operations: generates personas (evidence: `ai_core/graph.py`)
- Fact Research → Agent Operations: gathers facts (evidence: `ai_core/graph.py`)
- Report Outline → Agent Operations: generates outline (evidence: `ai_core/graph.py`)
- Report Synthesis → Agent Operations: drafts report (evidence: `ai_core/graph.py`)
- Critique Revision → Agent Operations: reviews report (evidence: `ai_core/graph.py`)
- Agent Operations → Research Models: uses typed models (evidence: `ai_core/agents.py`)
- LangGraph Workflow → Research Models: uses workflow state (evidence: `ai_core/graph.py`)
- Agent Operations → Search Tools: runs queries (evidence: `ai_core/agents.py`)
- Search Tools → Semantic Scholar: searches papers (evidence: `ai_core/tools.py`)
- Search Tools → DuckDuckGo Search: falls back to (evidence: `ai_core/tools.py`)
- Agent Operations → LLM Providers: calls model providers (evidence: `ai_core/agents.py`)
- Ragas Evaluation → LangGraph Workflow: evaluates output (evidence: `ai_core/ragas_eval.py`)
