# butlee27/agentic-ai-research- architecture

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

- Interactive diagram: https://gitdiagram.com/butlee27/agentic-ai-research-
- Repository: https://github.com/butlee27/agentic-ai-research-

## Overview

AI Research Agent accepts a question in Streamlit, sends it to FastAPI, and runs a LangGraph workflow: research gathers live and internal evidence, writing produces a report, review checks it, and human approval either finishes or sends it for revision. The graph builder owns stage registration and routing; the supervisor selects revision stages. MCP exposes the search tools, while retrieval modules implement the internal knowledge-base capability. README documents the UI/API and knowledge-base workflow; retrieval internals and some agent implementations were not excerpted, so uncertain implementation links are omitted.

Main entry points: [`app/graph/builder.py`](https://github.com/butlee27/agentic-ai-research-/blob/main/app/graph/builder.py) (Graph builder), [`app/config.py`](https://github.com/butlee27/agentic-ai-research-/blob/main/app/config.py) (LLM configuration), [`app/agents/research_agent.py`](https://github.com/butlee27/agentic-ai-research-/blob/main/app/agents/research_agent.py) (Research agent), [`app/mcp/server.py`](https://github.com/butlee27/agentic-ai-research-/blob/main/app/mcp/server.py) (MCP tool server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_ui["Streamlit interface<br/>[streamlit_app.py]"]
  node_api["Research API<br/>[main.py]"]
end

subgraph group_workflow["Research workflow"]
  node_builder["Graph builder<br/>[builder.py]"]
  node_supervisor["Stage supervisor<br/>[supervisor.py]"]
  node_research["Research agent<br/>[research_agent.py]"]
  node_writer["Report writer<br/>[writer_agent.py]"]
  node_reviewer["Report reviewer<br/>[reviewer_agent.py]"]
  node_approval["Human approval<br/>[human_approval.py]"]
  node_routing["Workflow routing<br/>[routing.py]"]
end

subgraph group_sources["Research sources"]
  node_mcp_client["MCP client<br/>[client.py]"]
  node_mcp_server["MCP tool server<br/>[server.py]"]
  node_retrieval_tool["Knowledge retrieval tool<br/>[retrieval_tool.py]"]
  node_retrieval["Document retrieval"]
  node_web_tool["Web search tool<br/>[web_search.py]"]
end

subgraph group_runtime["Model and state"]
  node_state["Workflow state<br/>[state.py]"]
  node_config["LLM configuration<br/>[config.py]"]
end

node_user(("Research user"))
node_tavily["Tavily search"]
node_llm["Groq language model"]
node_knowledge_store[("Chroma knowledge base")]

node_user -->|"submits question"| node_ui
node_ui -->|"sends request"| node_api
node_api -->|"invokes workflow"| node_builder
node_builder -->|"registers stage"| node_research
node_builder -->|"registers stage"| node_supervisor
node_builder -->|"registers stage"| node_writer
node_builder -->|"registers stage"| node_reviewer
node_builder -->|"registers stage"| node_approval
node_builder -->|"uses state"| node_state
node_builder -->|"routes stages"| node_supervisor
node_builder -.->|"routes workflow"| node_routing
node_research -->|"requests searches"| node_mcp_client
node_mcp_client -->|"calls tools"| node_mcp_server
node_mcp_server -->|"invokes retrieval"| node_retrieval_tool
node_mcp_server -->|"invokes search"| node_web_tool
node_retrieval_tool -->|"retrieves documents"| node_retrieval
node_retrieval -.->|"searches knowledge"| node_knowledge_store
node_web_tool -->|"searches web"| node_tavily
node_config -->|"configures model"| node_llm
node_research -->|"gets model"| node_config
node_supervisor -->|"gets model"| node_config
node_reviewer -->|"gets model"| node_config
node_writer -->|"gets model"| node_config

click node_ui "https://github.com/butlee27/agentic-ai-research-/blob/main/app/ui/streamlit_app.py"
click node_api "https://github.com/butlee27/agentic-ai-research-/blob/main/app/api/main.py"
click node_builder "https://github.com/butlee27/agentic-ai-research-/blob/main/app/graph/builder.py"
click node_supervisor "https://github.com/butlee27/agentic-ai-research-/blob/main/app/agents/supervisor.py"
click node_research "https://github.com/butlee27/agentic-ai-research-/blob/main/app/agents/research_agent.py"
click node_writer "https://github.com/butlee27/agentic-ai-research-/blob/main/app/agents/writer_agent.py"
click node_reviewer "https://github.com/butlee27/agentic-ai-research-/blob/main/app/agents/reviewer_agent.py"
click node_approval "https://github.com/butlee27/agentic-ai-research-/blob/main/app/agents/human_approval.py"
click node_routing "https://github.com/butlee27/agentic-ai-research-/blob/main/app/graph/routing.py"
click node_state "https://github.com/butlee27/agentic-ai-research-/blob/main/app/graph/state.py"
click node_mcp_client "https://github.com/butlee27/agentic-ai-research-/blob/main/app/mcp/client.py"
click node_mcp_server "https://github.com/butlee27/agentic-ai-research-/blob/main/app/mcp/server.py"
click node_retrieval_tool "https://github.com/butlee27/agentic-ai-research-/blob/main/app/tools/retrieval_tool.py"
click node_retrieval "https://github.com/butlee27/agentic-ai-research-/tree/main/app/Retrieval"
click node_web_tool "https://github.com/butlee27/agentic-ai-research-/blob/main/app/tools/web_search.py"
click node_config "https://github.com/butlee27/agentic-ai-research-/blob/main/app/config.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_api,node_user toneBlue
class node_builder,node_supervisor,node_research,node_writer,node_reviewer,node_approval,node_routing,node_knowledge_store toneAmber
class node_mcp_client,node_mcp_server,node_retrieval_tool,node_retrieval,node_web_tool toneMint
class node_state,node_config toneRose
class node_tavily,node_llm toneIndigo
```

## Components

### User interface

- [Streamlit interface](https://github.com/butlee27/agentic-ai-research-/blob/main/app/ui/streamlit_app.py): `app/ui/streamlit_app.py`
- [Research API](https://github.com/butlee27/agentic-ai-research-/blob/main/app/api/main.py): `app/api/main.py`

### Research workflow

- [Graph builder](https://github.com/butlee27/agentic-ai-research-/blob/main/app/graph/builder.py): `app/graph/builder.py`
- [Stage supervisor](https://github.com/butlee27/agentic-ai-research-/blob/main/app/agents/supervisor.py): `app/agents/supervisor.py`
- [Research agent](https://github.com/butlee27/agentic-ai-research-/blob/main/app/agents/research_agent.py): `app/agents/research_agent.py`
- [Report writer](https://github.com/butlee27/agentic-ai-research-/blob/main/app/agents/writer_agent.py): `app/agents/writer_agent.py`
- [Report reviewer](https://github.com/butlee27/agentic-ai-research-/blob/main/app/agents/reviewer_agent.py): `app/agents/reviewer_agent.py`
- [Human approval](https://github.com/butlee27/agentic-ai-research-/blob/main/app/agents/human_approval.py): `app/agents/human_approval.py`
- [Workflow routing](https://github.com/butlee27/agentic-ai-research-/blob/main/app/graph/routing.py): `app/graph/routing.py`

### Research sources

- [MCP client](https://github.com/butlee27/agentic-ai-research-/blob/main/app/mcp/client.py): `app/mcp/client.py`
- [MCP tool server](https://github.com/butlee27/agentic-ai-research-/blob/main/app/mcp/server.py): `app/mcp/server.py`
- [Knowledge retrieval tool](https://github.com/butlee27/agentic-ai-research-/blob/main/app/tools/retrieval_tool.py): `app/tools/retrieval_tool.py`
- [Document retrieval](https://github.com/butlee27/agentic-ai-research-/tree/main/app/Retrieval): `app/Retrieval`
- [Web search tool](https://github.com/butlee27/agentic-ai-research-/blob/main/app/tools/web_search.py): `app/tools/web_search.py`

### Model and state

- [Workflow state](https://github.com/butlee27/agentic-ai-research-/blob/main/app/graph/state.py): `app/graph/state.py`
- [LLM configuration](https://github.com/butlee27/agentic-ai-research-/blob/main/app/config.py): `app/config.py`

### Other components

- **Research user**
- **Tavily search**
- **Groq language model**
- **Chroma knowledge base**

## Connections

- Research user → Streamlit interface: submits question (evidence: `README.md`)
- Streamlit interface → Research API: sends request (evidence: `README.md`)
- Research API → Graph builder: invokes workflow (evidence: `app/api/main.py`)
- Graph builder → Research agent: registers stage (evidence: `app/graph/builder.py`)
- Graph builder → Stage supervisor: registers stage (evidence: `app/graph/builder.py`)
- Graph builder → Report writer: registers stage (evidence: `app/graph/builder.py`)
- Graph builder → Report reviewer: registers stage (evidence: `app/graph/builder.py`)
- Graph builder → Human approval: registers stage (evidence: `app/graph/builder.py`)
- Graph builder → Workflow state: uses state (evidence: `app/graph/builder.py`)
- Graph builder → Stage supervisor: routes stages (evidence: `app/graph/builder.py`)
- Graph builder → Workflow routing: routes workflow
- Research agent → MCP client: requests searches (evidence: `app/agents/research_agent.py`)
- MCP client → MCP tool server: calls tools (evidence: `app/mcp/client.py`)
- MCP tool server → Knowledge retrieval tool: invokes retrieval (evidence: `app/mcp/server.py`)
- MCP tool server → Web search tool: invokes search (evidence: `app/mcp/server.py`)
- Knowledge retrieval tool → Document retrieval: retrieves documents (evidence: `app/tools/retrieval_tool.py`)
- Document retrieval → Chroma knowledge base: searches knowledge
- Web search tool → Tavily search: searches web (evidence: `app/tools/web_search.py`)
- LLM configuration → Groq language model: configures model (evidence: `app/config.py`)
- Research agent → LLM configuration: gets model (evidence: `app/agents/research_agent.py`)
- Stage supervisor → LLM configuration: gets model (evidence: `app/agents/supervisor.py`)
- Report reviewer → LLM configuration: gets model (evidence: `app/agents/reviewer_agent.py`)
- Report writer → LLM configuration: gets model (evidence: `app/agents/writer_agent.py`)
