# aditya-karande/chatbot_with_langgraph architecture

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

- Interactive diagram: https://gitdiagram.com/aditya-karande/chatbot_with_langgraph
- Repository: https://github.com/aditya-karande/chatbot_with_langgraph

## Overview

#### Purpose and Entry Point
This is a Streamlit-based agentic chatbot that combines LangGraph orchestration, LLM tool calling, document RAG, approval-gated code execution, and two memory scopes. Runtime starts at `app.py`, which hosts chat, thread interaction, file upload, and human approval/resume controls.

#### Application Boundary and State
The backend models a stateful LangGraph conversation rather than a request/response web service. `backend/state.py` defines chatbot state and prompting context; `backend/config.py` centralizes model, embedding, database, and memory/checkpoint setup. Conversation identity and user context must flow consistently through graph invocations and resumes.

#### Main Orchestration Graph
`backend/graph.py` composes the primary LangGraph workflow and routes among agent generation, tools, RAG, memory persistence, and summarization. `backend/agent.py` supplies the main agent decision logic and conditional paths. The graph is the control-plane boundary: individual capabilities are graph nodes or subgraphs, while Streamlit invokes/resumes the compiled workflow.

#### Agent and Tool Execution
The agent uses an external Groq-hosted `openai/gpt-oss-120b` model to decide whether to answer directly or request capabilities. `backend/tools.py` exposes weather, stock, currency, date, web search, and Python execution tools. Safe tool calls return into the agent loop; Python execution crosses a human-approval boundary through `hitl_gate` in `backend/agent.py`, using LangGraph interruption until the UI approves or rejects.

#### Retrieval-Augmented Generation
`backend/rag.py` owns document upload/ingestion and a dedicated LangGraph RAG subgraph. PDF, TXT, and Markdown content is chunked, embedded with Gemini embeddings, and persisted in PostgreSQL pgvector. At query time, retrieval is followed by relevance grading/filtering before selected chunks are supplied for answer generation. This separates document knowledge from general agent/tool reasoning.

#### Memory and Conversation Lifecycle
Short-term conversation continuity is checkpoint-backed and managed with history compression in `backend/summarization.py`; summaries replace older messages when context grows. Long-term, cross-conversation facts are retrieved before response generation and selectively deduplicated/stored afterward by `backend/memory.py`. `backend/threads.py` manages user-facing chat histories, titles, and renaming, distinct from graph checkpoint state.

#### Runtime Infrastructure
The application runs as Python/Streamlit (`app.py`) with LangGraph as the workflow runtime. It depends on Groq for LLM inference, Google/Gemini for embeddings, PostgreSQL plus pgvector for vector persistence, and external APIs for tools such as weather and search. Configuration and connection initialization are concentrated in `backend/config.py`; deployment requires database connectivity, pgvector enabled, and API credentials.

Main entry points: [`backend/graph.py`](https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/graph.py) (Compiled Workflow), [`backend/config.py`](https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/config.py) (Runtime Configuration), [`backend/agent.py`](https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/agent.py) (Agent Decision & HITL), [`app.py`](https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/app.py) (Streamlit Chat App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User Interface"]
  node_streamlit["Streamlit Chat App<br/>Python UI<br/>[app.py]"]
  node_threads["Thread Manager<br/>chat history<br/>[threads.py]"]
  node_user(("User<br/>human"))
end

subgraph group_workflow["LangGraph Control Plane"]
  node_state["Conversation State<br/>LangGraph state<br/>[state.py]"]
  node_config["Runtime Configuration<br/>setup<br/>[config.py]"]
  node_graph{{"Compiled Workflow<br/>LangGraph workflow<br/>[graph.py]"}}
  node_agent["Agent Decision &amp; HITL<br/>agent node<br/>[agent.py]"]
  node_tools["Tool Executor<br/>tool suite<br/>[tools.py]"]
end

subgraph group_knowledge["Knowledge &amp; Memory"]
  node_rag{{"RAG Subgraph<br/>retrieval workflow<br/>[rag.py]"}}
  node_summarization["History Compression<br/>summarizer<br/>[summarization.py]"]
  node_memory["Long-Term Memory<br/>memory workflow<br/>[memory.py]"]
  node_checkpoints[("Checkpoint Store<br/>conversation persistence")]
end

subgraph group_infrastructure["External Services"]
  node_pgvector[("PostgreSQL + pgvector<br/>vector database")]
  node_groq["Groq LLM<br/>model inference"]
  node_gemini["Gemini Embeddings<br/>embedding model"]
  node_tool_apis["External Tool APIs<br/>external APIs"]
end

node_user -->|"chat, uploads, approval"| node_streamlit
node_streamlit -->|"manages chats"| node_threads
node_streamlit -->|"invoke / resume"| node_graph
node_graph -->|"reads and updates"| node_state
node_graph -->|"agent step"| node_agent
node_graph -->|"document retrieval path"| node_rag
node_graph -->|"compresses history"| node_summarization
node_graph -->|"retrieve and persist facts"| node_memory
node_agent -->|"tool calls"| node_tools
node_tools -->|"safe results loop"| node_agent
node_agent -.->|"Python interrupt for approval"| node_streamlit
node_tools -->|"weather and search requests"| node_tool_apis
node_rag -->|"embed chunks and queries"| node_gemini
node_rag -->|"ingest and retrieve chunks"| node_pgvector
node_agent -->|"decisions and answers"| node_groq
node_config -->|"configures runtime"| node_graph
node_config -->|"initializes"| node_checkpoints
node_config -->|"connects"| node_pgvector
node_config -->|"configures"| node_groq
node_config -->|"configures"| node_gemini
node_graph -->|"checkpoint state"| node_checkpoints

click node_streamlit "https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/app.py"
click node_threads "https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/threads.py"
click node_state "https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/state.py"
click node_config "https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/config.py"
click node_graph "https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/graph.py"
click node_agent "https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/agent.py"
click node_tools "https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/tools.py"
click node_rag "https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/rag.py"
click node_summarization "https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/summarization.py"
click node_memory "https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/memory.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,node_threads,node_user toneBlue
class node_state,node_config,node_graph,node_agent,node_tools toneAmber
class node_rag,node_summarization,node_memory,node_checkpoints toneMint
class node_pgvector,node_groq,node_gemini,node_tool_apis toneRose
```

## Components

### User Interface

- [Streamlit Chat App](https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/app.py): Python UI · Chat, uploads, thread controls, and approval/resume actions. · `app.py`
- [Thread Manager](https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/threads.py): chat history · Manages user-facing histories, titles, and renames. · `backend/threads.py`
- **User**: human

### LangGraph Control Plane

- [Conversation State](https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/state.py): LangGraph state · Defines conversation state and prompting context. · `backend/state.py`
- [Runtime Configuration](https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/config.py): setup · Initializes models, embeddings, databases, memory, and checkpoints. · `backend/config.py`
- [Compiled Workflow](https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/graph.py): LangGraph workflow · Routes agent, tools, RAG, memory, and summarization stages. · `backend/graph.py`
- [Agent Decision & HITL](https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/agent.py): agent node · Chooses response paths and gates Python execution with interrupts. · `backend/agent.py`
- [Tool Executor](https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/tools.py): tool suite · Weather, stock, currency, date, search, and Python tools. · `backend/tools.py`

### Knowledge & Memory

- [RAG Subgraph](https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/rag.py): retrieval workflow · Ingests documents and retrieves graded chunks for answers. · `backend/rag.py`
- [History Compression](https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/summarization.py): summarizer · Replaces older messages with summaries as context grows. · `backend/summarization.py`
- [Long-Term Memory](https://github.com/aditya-karande/chatbot_with_langgraph/blob/main/backend/memory.py): memory workflow · Retrieves facts before responses and deduplicates facts afterward. · `backend/memory.py`
- **Checkpoint Store**: conversation persistence · Stores short-term graph conversation continuity.

### External Services

- **PostgreSQL + pgvector**: vector database · Persists embedded document chunks.
- **Groq LLM**: model inference · Hosts openai/gpt-oss-120b for agent decisions and generation.
- **Gemini Embeddings**: embedding model
- **External Tool APIs**: external APIs · Supports weather and web-search style tools.

## Connections

- User → Streamlit Chat App: chat, uploads, approval
- Streamlit Chat App → Thread Manager: manages chats
- Streamlit Chat App → Compiled Workflow: invoke / resume
- Compiled Workflow → Conversation State: reads and updates
- Compiled Workflow → Agent Decision & HITL: agent step
- Compiled Workflow → RAG Subgraph: document retrieval path
- Compiled Workflow → History Compression: compresses history
- Compiled Workflow → Long-Term Memory: retrieve and persist facts
- Agent Decision & HITL → Tool Executor: tool calls
- Tool Executor → Agent Decision & HITL: safe results loop
- Agent Decision & HITL → Streamlit Chat App: Python interrupt for approval
- Tool Executor → External Tool APIs: weather and search requests
- RAG Subgraph → Gemini Embeddings: embed chunks and queries
- RAG Subgraph → PostgreSQL + pgvector: ingest and retrieve chunks
- Agent Decision & HITL → Groq LLM: decisions and answers
- Runtime Configuration → Compiled Workflow: configures runtime
- Runtime Configuration → Checkpoint Store: initializes
- Runtime Configuration → PostgreSQL + pgvector: connects
- Runtime Configuration → Groq LLM: configures
- Runtime Configuration → Gemini Embeddings: configures
- Compiled Workflow → Checkpoint Store: checkpoint state