# mr-chetan-66/halfgpt architecture

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

- Interactive diagram: https://gitdiagram.com/mr-chetan-66/halfgpt
- Repository: https://github.com/mr-chetan-66/halfgpt

## Overview

HalfGPT is a browser-based agentic chatbot. A user chats or uploads a supported document; FastAPI streams agent responses or ingests files, while conversation history and agent checkpoints persist separately. The agent routes requests to direct chat or specialized tools for calculations, web search, document retrieval, and memory. The README also documents Google Search with Tavily fallback. The graph reflects shown calls and documented capabilities; deployment details are excluded, and unsampled frontend behavior is not inferred.

Main entry points: [`app.py`](https://github.com/mr-chetan-66/halfgpt/blob/main/app.py) (FastAPI endpoints), [`agent.py`](https://github.com/mr-chetan-66/halfgpt/blob/main/agent.py) (Tool dispatch), [`tools.py`](https://github.com/mr-chetan-66/halfgpt/blob/main/tools.py) (Web search), [`templates/index.html`](https://github.com/mr-chetan-66/halfgpt/blob/main/templates/index.html) (Web interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_ui["Web interface<br/>[index.html]"]
  node_api["FastAPI endpoints<br/>[app.py]"]
  node_upload["Document upload<br/>[app.py]"]
  node_stream["Chat streaming<br/>[app.py]"]
end

subgraph group_agent["Agent runtime"]
  node_agent_graph["LangGraph agent<br/>[agent.py]"]
  node_router["Intent router<br/>[agent.py]"]
  node_tool_dispatch["Tool dispatch<br/>[agent.py]"]
  node_calculator["Calculator<br/>[tools.py]"]
  node_web_search["Web search<br/>[tools.py]"]
end

subgraph group_knowledge["Documents and memory"]
  node_doc_search["Document search tool<br/>[tools.py]"]
  node_ingestion["Document ingestion<br/>[rag.py]"]
  node_vectors[("Chroma vector store<br/>[rag.py]")]
  node_memory_tools["Memory tools<br/>[tools.py]"]
end

subgraph group_persistence["Persistence"]
  node_chat_db[("Conversation storage<br/>[database.py]")]
  node_checkpoints[("Agent checkpoints<br/>[agent.py]")]
end

subgraph group_integrations["External services"]
  node_groq["Groq chat model"]
  node_google["Google Search"]
  node_tavily["Tavily search"]
end

node_user(("Chat user"))

node_user -->|"uses"| node_ui
node_ui -->|"sends requests"| node_api
node_api -->|"renders page"| node_ui
node_api -->|"routes uploads"| node_upload
node_api -->|"routes chat"| node_stream
node_upload -->|"ingests file"| node_ingestion
node_api -->|"reads and writes"| node_chat_db
node_stream -->|"streams agent"| node_agent_graph
node_stream -->|"saves messages"| node_chat_db
node_agent_graph -->|"classifies intent"| node_router
node_router -->|"routes requests"| node_tool_dispatch
node_tool_dispatch -->|"dispatches"| node_calculator
node_tool_dispatch -->|"dispatches"| node_web_search
node_tool_dispatch -->|"dispatches"| node_doc_search
node_tool_dispatch -->|"dispatches"| node_memory_tools
node_agent_graph -->|"generates responses"| node_groq
node_web_search -->|"queries when configured"| node_google
node_web_search -->|"falls back to"| node_tavily
node_doc_search -->|"retrieves chunks"| node_vectors
node_ingestion -->|"stores chunks"| node_vectors
node_memory_tools -->|"saves and searches"| node_chat_db
node_agent_graph -->|"persists state"| node_checkpoints
node_api -->|"deletes thread state"| node_checkpoints
node_api -->|"deletes thread documents"| node_vectors

click node_ui "https://github.com/mr-chetan-66/halfgpt/blob/main/templates/index.html"
click node_api "https://github.com/mr-chetan-66/halfgpt/blob/main/app.py"
click node_upload "https://github.com/mr-chetan-66/halfgpt/blob/main/app.py"
click node_stream "https://github.com/mr-chetan-66/halfgpt/blob/main/app.py"
click node_agent_graph "https://github.com/mr-chetan-66/halfgpt/blob/main/agent.py"
click node_router "https://github.com/mr-chetan-66/halfgpt/blob/main/agent.py"
click node_tool_dispatch "https://github.com/mr-chetan-66/halfgpt/blob/main/agent.py"
click node_calculator "https://github.com/mr-chetan-66/halfgpt/blob/main/tools.py"
click node_web_search "https://github.com/mr-chetan-66/halfgpt/blob/main/tools.py"
click node_doc_search "https://github.com/mr-chetan-66/halfgpt/blob/main/tools.py"
click node_ingestion "https://github.com/mr-chetan-66/halfgpt/blob/main/rag.py"
click node_vectors "https://github.com/mr-chetan-66/halfgpt/blob/main/rag.py"
click node_memory_tools "https://github.com/mr-chetan-66/halfgpt/blob/main/tools.py"
click node_chat_db "https://github.com/mr-chetan-66/halfgpt/blob/main/database.py"
click node_checkpoints "https://github.com/mr-chetan-66/halfgpt/blob/main/agent.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_upload,node_stream,node_user toneBlue
class node_agent_graph,node_router,node_tool_dispatch,node_calculator,node_web_search toneAmber
class node_doc_search,node_ingestion,node_vectors,node_memory_tools toneMint
class node_chat_db,node_checkpoints toneRose
class node_groq,node_google,node_tavily toneIndigo
```

## Components

### Web application

- [Web interface](https://github.com/mr-chetan-66/halfgpt/blob/main/templates/index.html): `templates/index.html`
- [FastAPI endpoints](https://github.com/mr-chetan-66/halfgpt/blob/main/app.py): `app.py`
- [Document upload](https://github.com/mr-chetan-66/halfgpt/blob/main/app.py): `app.py`
- [Chat streaming](https://github.com/mr-chetan-66/halfgpt/blob/main/app.py): `app.py`

### Agent runtime

- [LangGraph agent](https://github.com/mr-chetan-66/halfgpt/blob/main/agent.py): `agent.py`
- [Intent router](https://github.com/mr-chetan-66/halfgpt/blob/main/agent.py): `agent.py`
- [Tool dispatch](https://github.com/mr-chetan-66/halfgpt/blob/main/agent.py): `agent.py`
- [Calculator](https://github.com/mr-chetan-66/halfgpt/blob/main/tools.py): `tools.py`
- [Web search](https://github.com/mr-chetan-66/halfgpt/blob/main/tools.py): `tools.py`

### Documents and memory

- [Document search tool](https://github.com/mr-chetan-66/halfgpt/blob/main/tools.py): `tools.py`
- [Document ingestion](https://github.com/mr-chetan-66/halfgpt/blob/main/rag.py): `rag.py`
- [Chroma vector store](https://github.com/mr-chetan-66/halfgpt/blob/main/rag.py): `rag.py`
- [Memory tools](https://github.com/mr-chetan-66/halfgpt/blob/main/tools.py): `tools.py`

### Persistence

- [Conversation storage](https://github.com/mr-chetan-66/halfgpt/blob/main/database.py): `database.py`
- [Agent checkpoints](https://github.com/mr-chetan-66/halfgpt/blob/main/agent.py): `agent.py`

### External services

- **Groq chat model**
- **Google Search**
- **Tavily search**

### Other components

- **Chat user**

## Connections

- Chat user → Web interface: uses (evidence: `README.md`)
- Web interface → FastAPI endpoints: sends requests (evidence: `README.md`)
- FastAPI endpoints → Web interface: renders page (evidence: `app.py`)
- FastAPI endpoints → Document upload: routes uploads (evidence: `app.py`)
- FastAPI endpoints → Chat streaming: routes chat (evidence: `app.py`)
- Document upload → Document ingestion: ingests file (evidence: `app.py`)
- FastAPI endpoints → Conversation storage: reads and writes (evidence: `app.py`)
- Chat streaming → LangGraph agent: streams agent (evidence: `app.py`)
- Chat streaming → Conversation storage: saves messages (evidence: `app.py`)
- LangGraph agent → Intent router: classifies intent (evidence: `agent.py`)
- Intent router → Tool dispatch: routes requests (evidence: `agent.py`)
- Tool dispatch → Calculator: dispatches (evidence: `agent.py`)
- Tool dispatch → Web search: dispatches (evidence: `agent.py`)
- Tool dispatch → Document search tool: dispatches (evidence: `agent.py`)
- Tool dispatch → Memory tools: dispatches (evidence: `agent.py`)
- LangGraph agent → Groq chat model: generates responses (evidence: `README.md`)
- Web search → Google Search: queries when configured (evidence: `tools.py`)
- Web search → Tavily search: falls back to (evidence: `tools.py`)
- Document search tool → Chroma vector store: retrieves chunks (evidence: `tools.py`)
- Document ingestion → Chroma vector store: stores chunks (evidence: `rag.py`)
- Memory tools → Conversation storage: saves and searches (evidence: `tools.py`)
- LangGraph agent → Agent checkpoints: persists state (evidence: `agent.py`)
- FastAPI endpoints → Agent checkpoints: deletes thread state (evidence: `app.py`)
- FastAPI endpoints → Chroma vector store: deletes thread documents (evidence: `app.py`)
