# tar7nic/researchmind architecture

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

- Interactive diagram: https://gitdiagram.com/tar7nic/researchmind
- Repository: https://github.com/tar7nic/researchmind

## Overview

ResearchMind accepts a research query with optional document input, gathers evidence through an agent’s tools, synthesizes a cited report, evaluates it, and saves the result. The UI also exposes the agent trace, report export, and evaluation scorecard/history. The README documents the LangGraph stages and tool capabilities; sampled source confirms the research-page, context-building, judge, and storage calls, while detailed graph wiring and tool implementations were not sampled.

Main entry points: [`ui/app.py`](https://github.com/tar7nic/researchmind/blob/main/ui/app.py) (Streamlit Navigation), [`agent/graph.py`](https://github.com/tar7nic/researchmind/blob/main/agent/graph.py) (LangGraph Orchestrator), [`agent/nodes.py`](https://github.com/tar7nic/researchmind/blob/main/agent/nodes.py) (Supervisor Routing), [`ui/sections/research.py`](https://github.com/tar7nic/researchmind/blob/main/ui/sections/research.py) (Research Query)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Research UI"]
  node_ui_app["Streamlit Navigation<br/>[app.py]"]
  node_research_page["Research Query<br/>[research.py]"]
  node_trace_page["Agent Trace<br/>[trace.py]"]
  node_report_page["Report Output<br/>[report.py]"]
  node_scorecard_page["Scorecard and History<br/>[scorecard.py]"]
  node_pdf_export["PDF Export<br/>[pdf_export.py]"]
end

subgraph group_input["Input Processing"]
  node_context["Unified Context<br/>[unified_context.py]"]
  node_pdf_parser["PDF Extraction<br/>[pdf_parser.py]"]
  node_image_handler["Image Encoding<br/>[image_handler.py]"]
end

subgraph group_agent["Research Agent"]
  node_graph["LangGraph Orchestrator<br/>[graph.py]"]
  node_supervisor["Supervisor Routing<br/>[nodes.py]"]
  node_executor["Tool Executor<br/>[nodes.py]"]
  node_tools["Research Tools<br/>[tools.py]"]
  node_synthesis["Report Synthesis<br/>[nodes.py]"]
end

subgraph group_persistence["Evaluation and Storage"]
  node_judge["LLM Judge<br/>[judge.py]"]
  node_storage_node["Record Persistence<br/>[nodes.py]"]
  node_database[("Research Records<br/>[db.py]")]
end

node_user(("Researcher"))
node_groq{{"Groq LLM"}}
node_tavily{{"Tavily Search"}}
node_python_repl{{"Python REPL"}}

node_user -->|"chooses page"| node_ui_app
node_ui_app -->|"routes to"| node_research_page
node_research_page -->|"builds input"| node_context
node_context -->|"extracts PDF"| node_pdf_parser
node_context -->|"encodes images"| node_image_handler
node_research_page -->|"invokes research"| node_graph
node_graph -->|"dispatches"| node_supervisor
node_supervisor -->|"requests reasoning"| node_groq
node_supervisor -->|"routes tool calls"| node_executor
node_executor -->|"invokes tools"| node_tools
node_tools -->|"searches web"| node_tavily
node_tools -->|"executes code"| node_python_repl
node_executor -->|"returns tool results"| node_supervisor
node_graph -->|"dispatches synthesis"| node_synthesis
node_synthesis -->|"generates report"| node_groq
node_graph -->|"dispatches evaluation"| node_judge
node_judge -->|"scores report"| node_groq
node_graph -->|"dispatches save"| node_storage_node
node_storage_node -->|"writes record"| node_database
node_ui_app -->|"initializes"| node_database
node_ui_app -->|"routes to"| node_trace_page
node_ui_app -->|"routes to"| node_report_page
node_ui_app -->|"routes to"| node_scorecard_page
node_report_page -->|"exports report"| node_pdf_export

click node_ui_app "https://github.com/tar7nic/researchmind/blob/main/ui/app.py"
click node_research_page "https://github.com/tar7nic/researchmind/blob/main/ui/sections/research.py"
click node_trace_page "https://github.com/tar7nic/researchmind/blob/main/ui/sections/trace.py"
click node_report_page "https://github.com/tar7nic/researchmind/blob/main/ui/sections/report.py"
click node_scorecard_page "https://github.com/tar7nic/researchmind/blob/main/ui/sections/scorecard.py"
click node_pdf_export "https://github.com/tar7nic/researchmind/blob/main/ui/components/pdf_export.py"
click node_context "https://github.com/tar7nic/researchmind/blob/main/ingestion/unified_context.py"
click node_pdf_parser "https://github.com/tar7nic/researchmind/blob/main/ingestion/pdf_parser.py"
click node_image_handler "https://github.com/tar7nic/researchmind/blob/main/ingestion/image_handler.py"
click node_graph "https://github.com/tar7nic/researchmind/blob/main/agent/graph.py"
click node_supervisor "https://github.com/tar7nic/researchmind/blob/main/agent/nodes.py"
click node_executor "https://github.com/tar7nic/researchmind/blob/main/agent/nodes.py"
click node_tools "https://github.com/tar7nic/researchmind/blob/main/agent/tools.py"
click node_synthesis "https://github.com/tar7nic/researchmind/blob/main/agent/nodes.py"
click node_judge "https://github.com/tar7nic/researchmind/blob/main/agent/judge.py"
click node_storage_node "https://github.com/tar7nic/researchmind/blob/main/agent/nodes.py"
click node_database "https://github.com/tar7nic/researchmind/blob/main/storage/db.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_app,node_research_page,node_trace_page,node_report_page,node_scorecard_page,node_pdf_export toneBlue
class node_context,node_pdf_parser,node_image_handler toneAmber
class node_graph,node_supervisor,node_executor,node_tools,node_synthesis toneMint
class node_judge,node_storage_node,node_database toneRose
class node_user,node_groq,node_tavily,node_python_repl toneIndigo
```

## Components

### Research UI

- [Streamlit Navigation](https://github.com/tar7nic/researchmind/blob/main/ui/app.py): `ui/app.py`
- [Research Query](https://github.com/tar7nic/researchmind/blob/main/ui/sections/research.py): `ui/sections/research.py`
- [Agent Trace](https://github.com/tar7nic/researchmind/blob/main/ui/sections/trace.py): `ui/sections/trace.py`
- [Report Output](https://github.com/tar7nic/researchmind/blob/main/ui/sections/report.py): `ui/sections/report.py`
- [Scorecard and History](https://github.com/tar7nic/researchmind/blob/main/ui/sections/scorecard.py): `ui/sections/scorecard.py`
- [PDF Export](https://github.com/tar7nic/researchmind/blob/main/ui/components/pdf_export.py): `ui/components/pdf_export.py`

### Input Processing

- [Unified Context](https://github.com/tar7nic/researchmind/blob/main/ingestion/unified_context.py): `ingestion/unified_context.py`
- [PDF Extraction](https://github.com/tar7nic/researchmind/blob/main/ingestion/pdf_parser.py): `ingestion/pdf_parser.py`
- [Image Encoding](https://github.com/tar7nic/researchmind/blob/main/ingestion/image_handler.py): `ingestion/image_handler.py`

### Research Agent

- [LangGraph Orchestrator](https://github.com/tar7nic/researchmind/blob/main/agent/graph.py): `agent/graph.py`
- [Supervisor Routing](https://github.com/tar7nic/researchmind/blob/main/agent/nodes.py): `agent/nodes.py`
- [Tool Executor](https://github.com/tar7nic/researchmind/blob/main/agent/nodes.py): `agent/nodes.py`
- [Research Tools](https://github.com/tar7nic/researchmind/blob/main/agent/tools.py): `agent/tools.py`
- [Report Synthesis](https://github.com/tar7nic/researchmind/blob/main/agent/nodes.py): `agent/nodes.py`

### Evaluation and Storage

- [LLM Judge](https://github.com/tar7nic/researchmind/blob/main/agent/judge.py): `agent/judge.py`
- [Record Persistence](https://github.com/tar7nic/researchmind/blob/main/agent/nodes.py): `agent/nodes.py`
- [Research Records](https://github.com/tar7nic/researchmind/blob/main/storage/db.py): `storage/db.py`

### Other components

- **Researcher**
- **Groq LLM**
- **Tavily Search**
- **Python REPL**

## Connections

- Researcher → Streamlit Navigation: chooses page
- Streamlit Navigation → Research Query: routes to
- Research Query → Unified Context: builds input
- Unified Context → PDF Extraction: extracts PDF
- Unified Context → Image Encoding: encodes images
- Research Query → LangGraph Orchestrator: invokes research
- LangGraph Orchestrator → Supervisor Routing: dispatches
- Supervisor Routing → Groq LLM: requests reasoning
- Supervisor Routing → Tool Executor: routes tool calls
- Tool Executor → Research Tools: invokes tools
- Research Tools → Tavily Search: searches web
- Research Tools → Python REPL: executes code
- Tool Executor → Supervisor Routing: returns tool results
- LangGraph Orchestrator → Report Synthesis: dispatches synthesis
- Report Synthesis → Groq LLM: generates report
- LangGraph Orchestrator → LLM Judge: dispatches evaluation
- LLM Judge → Groq LLM: scores report
- LangGraph Orchestrator → Record Persistence: dispatches save
- Record Persistence → Research Records: writes record
- Streamlit Navigation → Research Records: initializes
- Streamlit Navigation → Agent Trace: routes to
- Streamlit Navigation → Report Output: routes to
- Streamlit Navigation → Scorecard and History: routes to
- Report Output → PDF Export: exports report