# hardikagarwal23/multi-agent-ai-research-system architecture

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

- Interactive diagram: https://gitdiagram.com/hardikagarwal23/multi-agent-ai-research-system
- Repository: https://github.com/hardikagarwal23/multi-agent-ai-research-system

## Overview

This is a multi-agent research assistant with Streamlit and CLI entry points. Its main workflow plans queries, searches the web, pauses for human source triage, drafts and reviews a report with bounded retries, then publishes the result. The graph owns agent routing; the nodes perform research stages and use Gemini, Tavily, and structured review output. The README documents the HITL gate and major capabilities; source-level evidence is available for the graph, UI, agents, and model integrations, but not every runtime detail.

Main entry points: [`graph.py`](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/graph.py) (Research graph), [`nodes.py`](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/nodes.py) (Fact reviewer), [`llm.py`](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/llm.py) (Gemini adapter), [`app.py`](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/app.py) (Source review gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_streamlit["Streamlit UI<br/>[app.py]"]
  node_cli["CLI interface<br/>[main.py]"]
  node_source_gate["Source review gate<br/>[app.py]"]
  node_report_view["Final report display<br/>[app.py]"]
end

subgraph group_orchestration["Workflow orchestration"]
  node_workflow["Research graph<br/>[graph.py]"]
end

subgraph group_research["Research stages"]
  node_planner["Query planner<br/>[nodes.py]"]
  node_search["Web search<br/>[nodes.py]"]
  node_writer["Report drafter<br/>[nodes.py]"]
  node_reviewer["Fact reviewer<br/>[nodes.py]"]
  node_publisher["Report publisher<br/>[nodes.py]"]
end

subgraph group_support["State and AI services"]
  node_research_state["Research state<br/>[state.py]"]
  node_review_schema["Review result schema<br/>[schema.py]"]
  node_llm_adapter["Gemini adapter<br/>[llm.py]"]
end

node_user(("Research user"))
node_gemini{{"Google Gemini"}}
node_tavily{{"Tavily Search"}}

node_user -->|"enters topic"| node_streamlit
node_user -->|"enters topic"| node_cli
node_streamlit -->|"builds and invokes"| node_workflow
node_cli -->|"builds and invokes"| node_workflow
node_workflow -->|"dispatches"| node_planner
node_workflow -->|"dispatches"| node_search
node_workflow -->|"dispatches"| node_writer
node_workflow -->|"dispatches"| node_reviewer
node_workflow -->|"dispatches"| node_publisher
node_workflow -->|"pauses after search"| node_source_gate
node_planner -->|"provides queries"| node_search
node_search -->|"presents sources"| node_source_gate
node_source_gate -->|"approves sources"| node_writer
node_writer -->|"submits draft"| node_reviewer
node_reviewer -->|"requests rewrite"| node_writer
node_reviewer -->|"approves draft"| node_publisher
node_publisher -->|"produces report"| node_report_view
node_planner -->|"requests completions"| node_llm_adapter
node_writer -->|"requests completions"| node_llm_adapter
node_reviewer -->|"requests evaluation"| node_llm_adapter
node_publisher -->|"requests formatting"| node_llm_adapter
node_llm_adapter -->|"calls model"| node_gemini
node_search -->|"submits queries"| node_tavily
node_reviewer -->|"validates output"| node_review_schema
node_workflow -->|"uses typed state"| node_research_state
node_planner -->|"reads and updates"| node_research_state

click node_streamlit "https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/app.py"
click node_cli "https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/main.py"
click node_workflow "https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/graph.py"
click node_source_gate "https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/app.py"
click node_planner "https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/nodes.py"
click node_search "https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/nodes.py"
click node_writer "https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/nodes.py"
click node_reviewer "https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/nodes.py"
click node_publisher "https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/nodes.py"
click node_research_state "https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/state.py"
click node_review_schema "https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/schema.py"
click node_llm_adapter "https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/llm.py"
click node_report_view "https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/app.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_streamlit,node_cli,node_source_gate,node_report_view,node_user toneBlue
class node_workflow toneAmber
class node_planner,node_search,node_writer,node_reviewer,node_publisher toneMint
class node_research_state,node_review_schema,node_llm_adapter toneRose
class node_gemini,node_tavily toneIndigo
```

## Components

### User interfaces

- [Streamlit UI](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/app.py): `app.py`
- [CLI interface](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/main.py): `main.py`
- [Source review gate](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/app.py): `app.py`
- [Final report display](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/app.py): `app.py`

### Workflow orchestration

- [Research graph](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/graph.py): `graph.py`

### Research stages

- [Query planner](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/nodes.py): `nodes.py`
- [Web search](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/nodes.py): `nodes.py`
- [Report drafter](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/nodes.py): `nodes.py`
- [Fact reviewer](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/nodes.py): `nodes.py`
- [Report publisher](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/nodes.py): `nodes.py`

### State and AI services

- [Research state](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/state.py): `state.py`
- [Review result schema](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/schema.py): `schema.py`
- [Gemini adapter](https://github.com/hardikagarwal23/multi-agent-ai-research-system/blob/main/llm.py): `llm.py`

### Other components

- **Research user**
- **Google Gemini**
- **Tavily Search**

## Connections

- Research user → Streamlit UI: enters topic (evidence: `README.md`)
- Research user → CLI interface: enters topic (evidence: `main.py`)
- Streamlit UI → Research graph: builds and invokes (evidence: `app.py`)
- CLI interface → Research graph: builds and invokes (evidence: `main.py`)
- Research graph → Query planner: dispatches (evidence: `graph.py`)
- Research graph → Web search: dispatches (evidence: `graph.py`)
- Research graph → Report drafter: dispatches (evidence: `graph.py`)
- Research graph → Fact reviewer: dispatches (evidence: `graph.py`)
- Research graph → Report publisher: dispatches (evidence: `graph.py`)
- Research graph → Source review gate: pauses after search (evidence: `README.md`)
- Query planner → Web search: provides queries (evidence: `README.md`)
- Web search → Source review gate: presents sources (evidence: `README.md`)
- Source review gate → Report drafter: approves sources (evidence: `app.py`)
- Report drafter → Fact reviewer: submits draft (evidence: `README.md`)
- Fact reviewer → Report drafter: requests rewrite (evidence: `graph.py`)
- Fact reviewer → Report publisher: approves draft (evidence: `graph.py`)
- Report publisher → Final report display: produces report (evidence: `app.py`)
- Query planner → Gemini adapter: requests completions (evidence: `nodes.py`)
- Report drafter → Gemini adapter: requests completions (evidence: `nodes.py`)
- Fact reviewer → Gemini adapter: requests evaluation (evidence: `nodes.py`)
- Report publisher → Gemini adapter: requests formatting (evidence: `nodes.py`)
- Gemini adapter → Google Gemini: calls model (evidence: `llm.py`)
- Web search → Tavily Search: submits queries (evidence: `nodes.py`)
- Fact reviewer → Review result schema: validates output (evidence: `nodes.py`)
- Research graph → Research state: uses typed state (evidence: `graph.py`)
- Query planner → Research state: reads and updates (evidence: `nodes.py`)
