# vikasjha2003/fathom-research architecture

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

- Interactive diagram: https://gitdiagram.com/vikasjha2003/fathom-research
- Repository: https://github.com/vikasjha2003/fathom-research

## Overview

Fathom Research turns a user’s topic into a sourced report through search, page reading, drafting, and critic-guided revision. The Streamlit interface streams workflow progress and presents the report, research, review, and download. In `main.py`, a LangGraph stateful workflow coordinates specialized agent nodes, tool dispatch, result extraction, and quality-gated routing. The README documents the model providers and product capabilities; sampled code shows the principal workflow and tool implementations. The available UI excerpt is partial, so some presentation details are based on the README.

Main entry points: [`main.py`](https://github.com/vikasjha2003/fathom-research/blob/main/main.py) (StateGraph orchestration), [`streamlit_app.py`](https://github.com/vikasjha2003/fathom-research/blob/main/streamlit_app.py) (Streamlit interface), [`prompts.py`](https://github.com/vikasjha2003/fathom-research/blob/main/prompts.py) (Agent prompts), [`tools.py`](https://github.com/vikasjha2003/fathom-research/blob/main/tools.py) (Web search tool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_ui["Streamlit interface<br/>[streamlit_app.py]"]
  node_report_view["Report and results<br/>[streamlit_app.py]"]
end

subgraph group_workflow["Research workflow"]
  node_workflow_graph["StateGraph orchestration<br/>[main.py]"]
  node_shared_state["Research state<br/>[main.py]"]
  node_prompts["Agent prompts<br/>[prompts.py]"]
  node_searcher["Searcher agent<br/>[main.py]"]
  node_search_extract["Search result extraction<br/>[main.py]"]
  node_reader["Reader agent<br/>[main.py]"]
  node_reading_extract["Reading result extraction<br/>[main.py]"]
  node_writer["Report writer<br/>[main.py]"]
  node_critic["Critic and quality gate<br/>[main.py]"]
end

subgraph group_tools["Research tools"]
  node_search_tool["Web search tool<br/>[tools.py]"]
  node_scrape_tool["Page scraper<br/>[tools.py]"]
end

subgraph group_services["External services"]
  node_llm_services{{"LLM providers"}}
  node_tavily{{"Tavily search"}}
  node_web_pages{{"Web pages"}}
end

node_researcher(("Researcher"))

node_researcher -->|"enters topic"| node_ui
node_ui -->|"streams workflow"| node_workflow_graph
node_workflow_graph -->|"tracks state"| node_shared_state
node_workflow_graph -->|"starts search"| node_searcher
node_searcher -->|"loads prompt"| node_prompts
node_searcher -->|"invokes model"| node_llm_services
node_searcher -->|"dispatches queries"| node_search_tool
node_search_tool -->|"searches web"| node_tavily
node_search_tool -.->|"returns source links"| node_web_pages
node_workflow_graph -->|"routes results"| node_search_extract
node_search_extract -->|"passes findings"| node_reader
node_reader -->|"loads prompt"| node_prompts
node_reader -->|"invokes model"| node_llm_services
node_reader -->|"dispatches URLs"| node_scrape_tool
node_scrape_tool -->|"fetches pages"| node_web_pages
node_workflow_graph -->|"routes readings"| node_reading_extract
node_reading_extract -->|"passes evidence"| node_writer
node_writer -->|"loads prompt"| node_prompts
node_writer -->|"invokes model"| node_llm_services
node_writer -->|"submits draft"| node_critic
node_critic -->|"loads prompt"| node_prompts
node_critic -->|"invokes model"| node_llm_services
node_critic -->|"routes revision"| node_writer
node_critic -->|"ends when approved"| node_workflow_graph
node_workflow_graph -->|"streams updates"| node_ui
node_ui -->|"presents results"| node_report_view
node_report_view -->|"offers download"| node_researcher

click node_ui "https://github.com/vikasjha2003/fathom-research/blob/main/streamlit_app.py"
click node_workflow_graph "https://github.com/vikasjha2003/fathom-research/blob/main/main.py"
click node_shared_state "https://github.com/vikasjha2003/fathom-research/blob/main/main.py"
click node_prompts "https://github.com/vikasjha2003/fathom-research/blob/main/prompts.py"
click node_searcher "https://github.com/vikasjha2003/fathom-research/blob/main/main.py"
click node_search_extract "https://github.com/vikasjha2003/fathom-research/blob/main/main.py"
click node_reader "https://github.com/vikasjha2003/fathom-research/blob/main/main.py"
click node_reading_extract "https://github.com/vikasjha2003/fathom-research/blob/main/main.py"
click node_writer "https://github.com/vikasjha2003/fathom-research/blob/main/main.py"
click node_critic "https://github.com/vikasjha2003/fathom-research/blob/main/main.py"
click node_search_tool "https://github.com/vikasjha2003/fathom-research/blob/main/tools.py"
click node_scrape_tool "https://github.com/vikasjha2003/fathom-research/blob/main/tools.py"
click node_report_view "https://github.com/vikasjha2003/fathom-research/blob/main/streamlit_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_ui,node_report_view toneBlue
class node_workflow_graph,node_shared_state,node_prompts,node_searcher,node_search_extract,node_reader,node_reading_extract,node_writer,node_critic toneAmber
class node_search_tool,node_scrape_tool toneMint
class node_llm_services,node_tavily,node_web_pages toneRose
class node_researcher toneIndigo
```

## Components

### User interface

- [Streamlit interface](https://github.com/vikasjha2003/fathom-research/blob/main/streamlit_app.py): `streamlit_app.py`
- [Report and results](https://github.com/vikasjha2003/fathom-research/blob/main/streamlit_app.py): `streamlit_app.py`

### Research workflow

- [StateGraph orchestration](https://github.com/vikasjha2003/fathom-research/blob/main/main.py): `main.py`
- [Research state](https://github.com/vikasjha2003/fathom-research/blob/main/main.py): `main.py`
- [Agent prompts](https://github.com/vikasjha2003/fathom-research/blob/main/prompts.py): `prompts.py`
- [Searcher agent](https://github.com/vikasjha2003/fathom-research/blob/main/main.py): `main.py`
- [Search result extraction](https://github.com/vikasjha2003/fathom-research/blob/main/main.py): `main.py`
- [Reader agent](https://github.com/vikasjha2003/fathom-research/blob/main/main.py): `main.py`
- [Reading result extraction](https://github.com/vikasjha2003/fathom-research/blob/main/main.py): `main.py`
- [Report writer](https://github.com/vikasjha2003/fathom-research/blob/main/main.py): `main.py`
- [Critic and quality gate](https://github.com/vikasjha2003/fathom-research/blob/main/main.py): `main.py`

### Research tools

- [Web search tool](https://github.com/vikasjha2003/fathom-research/blob/main/tools.py): `tools.py`
- [Page scraper](https://github.com/vikasjha2003/fathom-research/blob/main/tools.py): `tools.py`

### External services

- **LLM providers**
- **Tavily search**
- **Web pages**

### Other components

- **Researcher**

## Connections

- Researcher → Streamlit interface: enters topic (evidence: `streamlit_app.py`)
- Streamlit interface → StateGraph orchestration: streams workflow (evidence: `streamlit_app.py`)
- StateGraph orchestration → Research state: tracks state (evidence: `main.py`)
- StateGraph orchestration → Searcher agent: starts search (evidence: `main.py`)
- Searcher agent → Agent prompts: loads prompt (evidence: `main.py`)
- Searcher agent → LLM providers: invokes model (evidence: `README.md`)
- Searcher agent → Web search tool: dispatches queries (evidence: `main.py`)
- Web search tool → Tavily search: searches web (evidence: `tools.py`)
- Web search tool → Web pages: returns source links
- StateGraph orchestration → Search result extraction: routes results (evidence: `main.py`)
- Search result extraction → Reader agent: passes findings (evidence: `main.py`)
- Reader agent → Agent prompts: loads prompt (evidence: `main.py`)
- Reader agent → LLM providers: invokes model (evidence: `README.md`)
- Reader agent → Page scraper: dispatches URLs (evidence: `main.py`)
- Page scraper → Web pages: fetches pages (evidence: `tools.py`)
- StateGraph orchestration → Reading result extraction: routes readings (evidence: `main.py`)
- Reading result extraction → Report writer: passes evidence (evidence: `main.py`)
- Report writer → Agent prompts: loads prompt (evidence: `main.py`)
- Report writer → LLM providers: invokes model (evidence: `README.md`)
- Report writer → Critic and quality gate: submits draft (evidence: `main.py`)
- Critic and quality gate → Agent prompts: loads prompt (evidence: `main.py`)
- Critic and quality gate → LLM providers: invokes model (evidence: `README.md`)
- Critic and quality gate → Report writer: routes revision (evidence: `main.py`)
- Critic and quality gate → StateGraph orchestration: ends when approved (evidence: `main.py`)
- StateGraph orchestration → Streamlit interface: streams updates (evidence: `streamlit_app.py`)
- Streamlit interface → Report and results: presents results (evidence: `README.md`)
- Report and results → Researcher: offers download (evidence: `README.md`)
