# hit93/ai-research-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/hit93/ai-research-assistant
- Repository: https://github.com/hit93/ai-research-assistant

## Overview

The product is a Streamlit AI research assistant that turns a topic into a sourced, verified report. Its documented lifecycle plans sub-queries, retrieves academic and web evidence, synthesizes findings, audits claims, and revises weak results before export. The LangGraph nodes are the internal workflow layer; retrieval also uses hybrid passage search. README documents semantic caching, layered memory, and gateway failover, but several implementations were not sampled, so those links reflect documented capabilities rather than inspected calls. No visual-analysis or security implementation is evident in the supplied tree.

Main entry points: [`src/graphs/nodes.py`](https://github.com/hit93/ai-research-assistant/blob/main/src/graphs/nodes.py) (Graph Nodes), [`app.py`](https://github.com/hit93/ai-research-assistant/blob/main/app.py) (Streamlit UI), [`src/graphs/graph.py`](https://github.com/hit93/ai-research-assistant/blob/main/src/graphs/graph.py) (Research Graph), [`src/chains/llm.py`](https://github.com/hit93/ai-research-assistant/blob/main/src/chains/llm.py) (LLM Chain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_streamlit["Streamlit UI<br/>[app.py]"]
end

subgraph group_workflow["Research Workflow"]
  node_graph["Research Graph<br/>[graph.py]"]
  node_state["Workflow State<br/>[state.py]"]
  node_nodes["Graph Nodes<br/>[nodes.py]"]
  node_planner["Query Planner<br/>[planner.py]"]
  node_synth["Synthesis Chain<br/>[synthesizer.py]"]
  node_verifier["Claim Verifier<br/>[verifier.py]"]
  node_refiner["Report Refiner<br/>[refiner.py]"]
  node_prompts["Prompt Templates<br/>[synthesizer.py]"]
end

subgraph group_retrieval["Evidence Retrieval"]
  node_arxiv["ArXiv Search<br/>[arxiv_tool.py]"]
  node_web["Web Search<br/>[web_search_tool.py]"]
  node_fetch["Full-Text Fetch"]
  node_rag["Hybrid Retrieval<br/>[hybrid_rag.py]"]
  node_cleaner["Text Normalizer<br/>[text_cleaner.py]"]
end

subgraph group_services["Models and Memory"]
  node_llm["LLM Chain<br/>[llm.py]"]
  node_gateway["LLM Gateway<br/>[gateway.py]"]
  node_cache[("Semantic Cache<br/>[semantic_cache.py]")]
  node_stm[("Short-Term Memory<br/>[stm.py]")]
  node_ltm[("Long-Term Memory<br/>[ltm.py]")]
end

subgraph group_delivery["Report Delivery"]
  node_exporter["Report Exporter<br/>[exporter.py]"]
  node_result["Research Report<br/>[schemas.py]"]
end

node_researcher(("Researcher"))
node_groq{{"Groq LLM"}}
node_gemini{{"Gemini LLM"}}
node_tavily{{"Tavily Search"}}
node_ddg{{"DuckDuckGo"}}
node_arxiv_service{{"ArXiv API"}}

node_researcher -->|"enters topic"| node_streamlit
node_streamlit -->|"checks query"| node_cache
node_cache -.->|"returns hit"| node_streamlit
node_streamlit -->|"starts research"| node_graph
node_graph -->|"dispatches stages"| node_nodes
node_graph -->|"tracks state"| node_state
node_nodes -->|"plans queries"| node_planner
node_planner -->|"generates plan"| node_llm
node_nodes -->|"searches papers"| node_arxiv
node_nodes -->|"searches web"| node_web
node_web -->|"queries first"| node_tavily
node_web -.->|"falls back"| node_ddg
node_arxiv -->|"queries API"| node_arxiv_service
node_nodes -->|"fetches text"| node_fetch
node_nodes -->|"indexes and retrieves"| node_rag
node_fetch -->|"normalizes text"| node_cleaner
node_nodes -->|"synthesizes evidence"| node_synth
node_synth -->|"uses template"| node_prompts
node_synth -->|"requests generation"| node_gateway
node_nodes -->|"audits claims"| node_verifier
node_verifier -->|"requests judgment"| node_gateway
node_nodes -->|"revises weak result"| node_refiner
node_refiner -->|"requests revision"| node_gateway
node_gateway -->|"routes requests"| node_llm
node_llm -->|"calls model"| node_groq
node_llm -.->|"calls model"| node_gemini
node_nodes -.->|"tracks session"| node_stm
node_nodes -.->|"archives run"| node_ltm
node_graph -->|"produces result"| node_result
node_streamlit -->|"exports report"| node_exporter
node_exporter -->|"formats report"| node_result
node_streamlit -->|"shows downloads"| node_researcher

click node_streamlit "https://github.com/hit93/ai-research-assistant/blob/main/app.py"
click node_graph "https://github.com/hit93/ai-research-assistant/blob/main/src/graphs/graph.py"
click node_state "https://github.com/hit93/ai-research-assistant/blob/main/src/graphs/state.py"
click node_nodes "https://github.com/hit93/ai-research-assistant/blob/main/src/graphs/nodes.py"
click node_planner "https://github.com/hit93/ai-research-assistant/blob/main/src/chains/planner.py"
click node_synth "https://github.com/hit93/ai-research-assistant/blob/main/src/chains/synthesizer.py"
click node_verifier "https://github.com/hit93/ai-research-assistant/blob/main/src/chains/verifier.py"
click node_refiner "https://github.com/hit93/ai-research-assistant/blob/main/src/chains/refiner.py"
click node_prompts "https://github.com/hit93/ai-research-assistant/blob/main/src/prompts/synthesizer.py"
click node_arxiv "https://github.com/hit93/ai-research-assistant/blob/main/src/tools/arxiv_tool.py"
click node_web "https://github.com/hit93/ai-research-assistant/blob/main/src/tools/web_search_tool.py"
click node_fetch "https://github.com/hit93/ai-research-assistant/blob/main/src/tools/full_text_fetcher.py"
click node_rag "https://github.com/hit93/ai-research-assistant/blob/main/src/tools/hybrid_rag.py"
click node_cleaner "https://github.com/hit93/ai-research-assistant/blob/main/src/tools/text_cleaner.py"
click node_llm "https://github.com/hit93/ai-research-assistant/blob/main/src/chains/llm.py"
click node_gateway "https://github.com/hit93/ai-research-assistant/blob/main/src/chains/gateway.py"
click node_cache "https://github.com/hit93/ai-research-assistant/blob/main/src/memory/semantic_cache.py"
click node_stm "https://github.com/hit93/ai-research-assistant/blob/main/src/memory/stm.py"
click node_ltm "https://github.com/hit93/ai-research-assistant/blob/main/src/memory/ltm.py"
click node_exporter "https://github.com/hit93/ai-research-assistant/blob/main/src/utils/exporter.py"
click node_result "https://github.com/hit93/ai-research-assistant/blob/main/src/models/schemas.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 toneBlue
class node_graph,node_state,node_nodes,node_planner,node_synth,node_verifier,node_refiner,node_prompts toneAmber
class node_arxiv,node_web,node_fetch,node_rag,node_cleaner,node_arxiv_service toneMint
class node_llm,node_gateway,node_cache,node_stm,node_ltm toneRose
class node_exporter,node_result,node_researcher,node_groq,node_gemini,node_tavily,node_ddg toneIndigo
```

## Components

### User Interface

- [Streamlit UI](https://github.com/hit93/ai-research-assistant/blob/main/app.py): `app.py`

### Research Workflow

- [Research Graph](https://github.com/hit93/ai-research-assistant/blob/main/src/graphs/graph.py): `src/graphs/graph.py`
- [Workflow State](https://github.com/hit93/ai-research-assistant/blob/main/src/graphs/state.py): `src/graphs/state.py`
- [Graph Nodes](https://github.com/hit93/ai-research-assistant/blob/main/src/graphs/nodes.py): `src/graphs/nodes.py`
- [Query Planner](https://github.com/hit93/ai-research-assistant/blob/main/src/chains/planner.py): `src/chains/planner.py`
- [Synthesis Chain](https://github.com/hit93/ai-research-assistant/blob/main/src/chains/synthesizer.py): `src/chains/synthesizer.py`
- [Claim Verifier](https://github.com/hit93/ai-research-assistant/blob/main/src/chains/verifier.py): `src/chains/verifier.py`
- [Report Refiner](https://github.com/hit93/ai-research-assistant/blob/main/src/chains/refiner.py): `src/chains/refiner.py`
- [Prompt Templates](https://github.com/hit93/ai-research-assistant/blob/main/src/prompts/synthesizer.py): `src/prompts/synthesizer.py`

### Evidence Retrieval

- [ArXiv Search](https://github.com/hit93/ai-research-assistant/blob/main/src/tools/arxiv_tool.py): `src/tools/arxiv_tool.py`
- [Web Search](https://github.com/hit93/ai-research-assistant/blob/main/src/tools/web_search_tool.py): `src/tools/web_search_tool.py`
- [Full-Text Fetch](https://github.com/hit93/ai-research-assistant/blob/main/src/tools/full_text_fetcher.py): `src/tools/full_text_fetcher.py`
- [Hybrid Retrieval](https://github.com/hit93/ai-research-assistant/blob/main/src/tools/hybrid_rag.py): `src/tools/hybrid_rag.py`
- [Text Normalizer](https://github.com/hit93/ai-research-assistant/blob/main/src/tools/text_cleaner.py): `src/tools/text_cleaner.py`

### Models and Memory

- [LLM Chain](https://github.com/hit93/ai-research-assistant/blob/main/src/chains/llm.py): `src/chains/llm.py`
- [LLM Gateway](https://github.com/hit93/ai-research-assistant/blob/main/src/chains/gateway.py): `src/chains/gateway.py`
- [Semantic Cache](https://github.com/hit93/ai-research-assistant/blob/main/src/memory/semantic_cache.py): `src/memory/semantic_cache.py`
- [Short-Term Memory](https://github.com/hit93/ai-research-assistant/blob/main/src/memory/stm.py): `src/memory/stm.py`
- [Long-Term Memory](https://github.com/hit93/ai-research-assistant/blob/main/src/memory/ltm.py): `src/memory/ltm.py`

### Report Delivery

- [Report Exporter](https://github.com/hit93/ai-research-assistant/blob/main/src/utils/exporter.py): `src/utils/exporter.py`
- [Research Report](https://github.com/hit93/ai-research-assistant/blob/main/src/models/schemas.py): `src/models/schemas.py`

### Other components

- **Researcher**
- **Groq LLM**
- **Gemini LLM**
- **Tavily Search**
- **DuckDuckGo**
- **ArXiv API**

## Connections

- Researcher → Streamlit UI: enters topic
- Streamlit UI → Semantic Cache: checks query
- Semantic Cache → Streamlit UI: returns hit
- Streamlit UI → Research Graph: starts research
- Research Graph → Graph Nodes: dispatches stages
- Research Graph → Workflow State: tracks state
- Graph Nodes → Query Planner: plans queries
- Query Planner → LLM Chain: generates plan
- Graph Nodes → ArXiv Search: searches papers
- Graph Nodes → Web Search: searches web
- Web Search → Tavily Search: queries first
- Web Search → DuckDuckGo: falls back
- ArXiv Search → ArXiv API: queries API
- Graph Nodes → Full-Text Fetch: fetches text
- Graph Nodes → Hybrid Retrieval: indexes and retrieves
- Full-Text Fetch → Text Normalizer: normalizes text
- Graph Nodes → Synthesis Chain: synthesizes evidence
- Synthesis Chain → Prompt Templates: uses template
- Synthesis Chain → LLM Gateway: requests generation
- Graph Nodes → Claim Verifier: audits claims
- Claim Verifier → LLM Gateway: requests judgment
- Graph Nodes → Report Refiner: revises weak result
- Report Refiner → LLM Gateway: requests revision
- LLM Gateway → LLM Chain: routes requests
- LLM Chain → Groq LLM: calls model
- LLM Chain → Gemini LLM: calls model
- Graph Nodes → Short-Term Memory: tracks session
- Graph Nodes → Long-Term Memory: archives run
- Research Graph → Research Report: produces result
- Streamlit UI → Report Exporter: exports report
- Report Exporter → Research Report: formats report
- Streamlit UI → Researcher: shows downloads