# zhangzgen/langraph-agent-study architecture

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

- Interactive diagram: https://gitdiagram.com/zhangzgen/langraph-agent-study
- Repository: https://github.com/zhangzgen/langraph-agent-study

## Overview

This repository is primarily a LangGraph agent application. Users interact through the CLI or Feishu bot; requests enter a shared graph that can clarify and review a plan, then run a ReAct loop that calls tools, pauses for approval when needed, and returns an answer. Checkpoints support resumed sessions, while context handling compresses older history and expires stale tool results. The README documents capabilities beyond the sampled source; graph links for those subsystems follow its architecture description, not inspected implementations.

Main entry points: [`langraph_agent/graph.py`](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/graph.py) (Agent graph), [`langraph_agent/tool_guard.py`](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/tool_guard.py) (Tool approval), [`langraph_agent/feishu_bot.py`](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/feishu_bot.py) (Feishu bot), [`langraph_agent/checkpoints.py`](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/checkpoints.py) (Checkpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channels["Interaction channels"]
  node_cli["CLI<br/>[cli.py]"]
  node_feishu["Feishu bot<br/>[feishu_bot.py]"]
end

subgraph group_orchestration["Agent orchestration"]
  node_graph["Agent graph<br/>[graph.py]"]
  node_plan["Plan review<br/>[graph.py]"]
  node_model["Chat model<br/>[llm.py]"]
  node_guard["Tool approval<br/>[tool_guard.py]"]
  node_context["Context manager<br/>[context.py]"]
end

subgraph group_capabilities["Tools and extensions"]
  node_tools["Basic tools<br/>[basic.py]"]
  node_filesystem["File tools<br/>[filesystem.py]"]
  node_shell["Shell tool<br/>[shell.py]"]
  node_web["Web search<br/>[web_search.py]"]
  node_mcp["MCP tools<br/>[mcp.py]"]
  node_skills["Skill tools<br/>[skill_tools.py]"]
  node_skill_registry["Skill registry<br/>[registry.py]"]
end

subgraph group_state["State and prompts"]
  node_checkpoint[("Checkpoints<br/>[checkpoints.py]")]
  node_approval_store[("Feishu approvals")]
  node_prompts["Prompt loader<br/>[prompt.py]"]
  node_config["Configuration<br/>[config.py]"]
end

node_user(("User"))
node_tavily["Tavily"]
node_mcp_services["MCP services"]
node_langsmith["LangSmith"]
node_postgres[("PostgreSQL")]
node_sqlite[("SQLite")]

node_user -->|"sends request"| node_cli
node_user -->|"sends request"| node_feishu
node_cli -->|"runs session"| node_graph
node_feishu -->|"runs session"| node_graph
node_graph -.->|"optional plan"| node_plan
node_plan -.->|"approved plan"| node_graph
node_graph -->|"manages history"| node_context
node_graph -->|"invokes"| node_model
node_model -->|"loads prompts"| node_prompts
node_graph -->|"classifies tools"| node_guard
node_guard -->|"executes approved"| node_filesystem
node_guard -->|"executes approved"| node_shell
node_guard -->|"executes"| node_tools
node_guard -->|"executes"| node_web
node_guard -->|"executes"| node_mcp
node_guard -->|"executes"| node_skills
node_skills -->|"discovers skills"| node_skill_registry
node_web -->|"searches and extracts"| node_tavily
node_mcp -->|"loads tools"| node_mcp_services
node_graph -->|"saves and resumes"| node_checkpoint
node_feishu -->|"persists approvals"| node_approval_store
node_checkpoint -.->|"uses when configured"| node_postgres
node_checkpoint -.->|"fallback backend"| node_sqlite
node_approval_store -.->|"uses when configured"| node_postgres
node_approval_store -.->|"fallback backend"| node_sqlite
node_prompts -.->|"remote-first templates"| node_langsmith
node_prompts -->|"reads settings"| node_config
node_graph -->|"reads settings"| node_config

click node_cli "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/cli.py"
click node_feishu "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/feishu_bot.py"
click node_graph "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/graph.py"
click node_plan "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/graph.py"
click node_model "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/llm.py"
click node_guard "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/tool_guard.py"
click node_context "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/context.py"
click node_tools "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/tools/basic.py"
click node_filesystem "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/tools/filesystem.py"
click node_shell "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/tools/shell.py"
click node_web "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/tools/web_search.py"
click node_mcp "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/tools/mcp.py"
click node_skills "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/tools/skill_tools.py"
click node_skill_registry "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/skills/registry.py"
click node_checkpoint "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/checkpoints.py"
click node_approval_store "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/feishu_approvals.py"
click node_prompts "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/prompt.py"
click node_config "https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/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_cli,node_feishu,node_user toneBlue
class node_graph,node_plan,node_model,node_guard,node_context,node_postgres,node_sqlite toneAmber
class node_tools,node_filesystem,node_shell,node_web,node_mcp,node_skills,node_skill_registry toneMint
class node_checkpoint,node_approval_store,node_prompts,node_config toneRose
class node_tavily,node_mcp_services,node_langsmith toneIndigo
```

## Components

### Interaction channels

- [CLI](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/cli.py): `langraph_agent/cli.py`
- [Feishu bot](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/feishu_bot.py): `langraph_agent/feishu_bot.py`

### Agent orchestration

- [Agent graph](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/graph.py): `langraph_agent/graph.py`
- [Plan review](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/graph.py): `langraph_agent/graph.py`
- [Chat model](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/llm.py): `langraph_agent/llm.py`
- [Tool approval](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/tool_guard.py): `langraph_agent/tool_guard.py`
- [Context manager](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/context.py): `langraph_agent/context.py`

### Tools and extensions

- [Basic tools](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/tools/basic.py): `langraph_agent/tools/basic.py`
- [File tools](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/tools/filesystem.py): `langraph_agent/tools/filesystem.py`
- [Shell tool](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/tools/shell.py): `langraph_agent/tools/shell.py`
- [Web search](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/tools/web_search.py): `langraph_agent/tools/web_search.py`
- [MCP tools](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/tools/mcp.py): `langraph_agent/tools/mcp.py`
- [Skill tools](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/tools/skill_tools.py): `langraph_agent/tools/skill_tools.py`
- [Skill registry](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/skills/registry.py): `langraph_agent/skills/registry.py`

### State and prompts

- [Checkpoints](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/checkpoints.py): `langraph_agent/checkpoints.py`
- [Feishu approvals](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/feishu_approvals.py): `langraph_agent/feishu_approvals.py`
- [Prompt loader](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/prompt.py): `langraph_agent/prompt.py`
- [Configuration](https://github.com/zhangzgen/langraph-agent-study/blob/main/langraph_agent/config.py): `langraph_agent/config.py`

### Other components

- **User**
- **Tavily**
- **MCP services**
- **LangSmith**
- **PostgreSQL**
- **SQLite**

## Connections

- User → CLI: sends request
- User → Feishu bot: sends request
- CLI → Agent graph: runs session
- Feishu bot → Agent graph: runs session
- Agent graph → Plan review: optional plan
- Plan review → Agent graph: approved plan
- Agent graph → Context manager: manages history
- Agent graph → Chat model: invokes
- Chat model → Prompt loader: loads prompts
- Agent graph → Tool approval: classifies tools
- Tool approval → File tools: executes approved
- Tool approval → Shell tool: executes approved
- Tool approval → Basic tools: executes
- Tool approval → Web search: executes
- Tool approval → MCP tools: executes
- Tool approval → Skill tools: executes
- Skill tools → Skill registry: discovers skills
- Web search → Tavily: searches and extracts
- MCP tools → MCP services: loads tools
- Agent graph → Checkpoints: saves and resumes
- Feishu bot → Feishu approvals: persists approvals
- Checkpoints → PostgreSQL: uses when configured
- Checkpoints → SQLite: fallback backend
- Feishu approvals → PostgreSQL: uses when configured
- Feishu approvals → SQLite: fallback backend
- Prompt loader → LangSmith: remote-first templates
- Prompt loader → Configuration: reads settings
- Agent graph → Configuration: reads settings