# milwinantany/agentic-researcher architecture

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

- Interactive diagram: https://gitdiagram.com/milwinantany/agentic-researcher
- Repository: https://github.com/milwinantany/agentic-researcher

## Overview

This repository implements a command-line research assistant: a user supplies a topic, and the orchestrator plans sub-questions, finds and crawls web pages, indexes their text, synthesizes findings with an LLM, and writes a Markdown brief. The graph distinguishes orchestration from the domain stages and shows the search, web, vector-store, and model integrations. The README describes interchangeable LLM providers, but the inspected LLM utility specifically calls Ollama; other provider wiring is not shown.

Main entry points: [`main.py`](https://github.com/milwinantany/agentic-researcher/blob/main/main.py) (CLI orchestrator), [`core/reason.py`](https://github.com/milwinantany/agentic-researcher/blob/main/core/reason.py) (Research synthesizer), [`utils/llm.py`](https://github.com/milwinantany/agentic-researcher/blob/main/utils/llm.py) (LLM utility), [`core/planner.py`](https://github.com/milwinantany/agentic-researcher/blob/main/core/planner.py) (Question planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Research workflow"]
  node_orchestrator["CLI orchestrator<br/>[main.py]"]
  node_planner["Question planner<br/>[planner.py]"]
  node_reasoner["Research synthesizer<br/>[reason.py]"]
end

subgraph group_llm["Language model"]
  node_llm_utility["LLM utility<br/>[llm.py]"]
end

subgraph group_storage["Index and reports"]
  node_indexer["Document indexer<br/>[indexer.py]"]
  node_vector_store[("ChromaDB collection")]
  node_writer["Markdown writer<br/>[output.py]"]
  node_reports["Research reports"]
end

subgraph group_sources["External sources"]
  node_search["Web search<br/>[search.py]"]
  node_crawler["Page crawler<br/>[crawler.py]"]
end

node_researcher(("Researcher"))
node_search_service{{"DDGS search"}}
node_web[("Web pages")]
node_ollama{{"Ollama model"}}

node_researcher -->|"submits topic"| node_orchestrator
node_orchestrator -->|"plans questions"| node_planner
node_planner -->|"requests questions"| node_llm_utility
node_llm_utility -->|"sends prompt"| node_ollama
node_orchestrator -->|"searches topic"| node_search
node_search -->|"queries results"| node_search_service
node_orchestrator -->|"crawls URLs"| node_crawler
node_crawler -->|"fetches pages"| node_web
node_orchestrator -->|"indexes documents"| node_indexer
node_indexer -->|"stores documents"| node_vector_store
node_orchestrator -->|"synthesizes research"| node_reasoner
node_reasoner -->|"queries context"| node_vector_store
node_reasoner -->|"requests synthesis"| node_llm_utility
node_orchestrator -->|"writes brief"| node_writer
node_writer -->|"writes Markdown"| node_reports

click node_orchestrator "https://github.com/milwinantany/agentic-researcher/blob/main/main.py"
click node_planner "https://github.com/milwinantany/agentic-researcher/blob/main/core/planner.py"
click node_search "https://github.com/milwinantany/agentic-researcher/blob/main/core/search.py"
click node_crawler "https://github.com/milwinantany/agentic-researcher/blob/main/core/crawler.py"
click node_indexer "https://github.com/milwinantany/agentic-researcher/blob/main/core/indexer.py"
click node_reasoner "https://github.com/milwinantany/agentic-researcher/blob/main/core/reason.py"
click node_llm_utility "https://github.com/milwinantany/agentic-researcher/blob/main/utils/llm.py"
click node_writer "https://github.com/milwinantany/agentic-researcher/blob/main/core/output.py"
click node_reports "https://github.com/milwinantany/agentic-researcher/tree/main/outputs"

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_orchestrator,node_planner,node_reasoner toneBlue
class node_llm_utility,node_web toneAmber
class node_indexer,node_vector_store,node_writer,node_reports toneMint
class node_search,node_crawler toneRose
class node_researcher,node_search_service,node_ollama toneIndigo
```

## Components

### Research workflow

- [CLI orchestrator](https://github.com/milwinantany/agentic-researcher/blob/main/main.py): `main.py`
- [Question planner](https://github.com/milwinantany/agentic-researcher/blob/main/core/planner.py): `core/planner.py`
- [Research synthesizer](https://github.com/milwinantany/agentic-researcher/blob/main/core/reason.py): `core/reason.py`

### Language model

- [LLM utility](https://github.com/milwinantany/agentic-researcher/blob/main/utils/llm.py): `utils/llm.py`

### Index and reports

- [Document indexer](https://github.com/milwinantany/agentic-researcher/blob/main/core/indexer.py): `core/indexer.py`
- **ChromaDB collection**
- [Markdown writer](https://github.com/milwinantany/agentic-researcher/blob/main/core/output.py): `core/output.py`
- [Research reports](https://github.com/milwinantany/agentic-researcher/tree/main/outputs): `outputs`

### External sources

- [Web search](https://github.com/milwinantany/agentic-researcher/blob/main/core/search.py): `core/search.py`
- [Page crawler](https://github.com/milwinantany/agentic-researcher/blob/main/core/crawler.py): `core/crawler.py`

### Other components

- **Researcher**
- **DDGS search**
- **Web pages**
- **Ollama model**

## Connections

- Researcher → CLI orchestrator: submits topic (evidence: `README.md`)
- CLI orchestrator → Question planner: plans questions (evidence: `main.py`)
- Question planner → LLM utility: requests questions (evidence: `core/planner.py`)
- LLM utility → Ollama model: sends prompt (evidence: `utils/llm.py`)
- CLI orchestrator → Web search: searches topic (evidence: `main.py`)
- Web search → DDGS search: queries results (evidence: `core/search.py`)
- CLI orchestrator → Page crawler: crawls URLs (evidence: `main.py`)
- Page crawler → Web pages: fetches pages (evidence: `core/crawler.py`)
- CLI orchestrator → Document indexer: indexes documents (evidence: `main.py`)
- Document indexer → ChromaDB collection: stores documents (evidence: `core/indexer.py`)
- CLI orchestrator → Research synthesizer: synthesizes research (evidence: `main.py`)
- Research synthesizer → ChromaDB collection: queries context (evidence: `core/reason.py`)
- Research synthesizer → LLM utility: requests synthesis (evidence: `core/reason.py`)
- CLI orchestrator → Markdown writer: writes brief (evidence: `main.py`)
- Markdown writer → Research reports: writes Markdown (evidence: `core/output.py`)
