Application Structure

Monorepo patterns, project organization for LangGraph apps, and separation of graph definition vs node logic vs tools.

Quick Reference

→Separate graph definition (edges, nodes, state) from node logic (LLM calls, business rules) and tool implementations into distinct modules
→Use a monorepo structure with shared packages for tools, state schemas, and utilities across multiple agents
→Keep the graph file thin — it should read like a flowchart with named nodes, not contain business logic inline
→Organize tools by domain (search_tools.py, db_tools.py) rather than by agent, enabling reuse across graphs
→Use a langgraph.json manifest to declare entry points, dependencies, and environment configuration for deployment

Recommended Folder Structure

Clean project layout for a LangGraph agent

▸graphs/ contains only topology — nodes, edges, and compilation. No business logic
▸nodes/ contains the actual logic for each node. Each node is a pure function: state in, state update out
▸tools/ contains tool definitions organized by domain, reusable across multiple agents
▸state/ contains TypedDict definitions shared between graphs and tests
▸prompts/ contains versioned prompt files that can be hot-swapped without code changes

Graph file reads like a flowchart — pure topology

Layer	What to test	How	Speed
Tools	Input/output correctness	Unit tests with mocked APIs	Fast (ms)
Nodes	State transformations	Unit tests with mock state	Fast (ms)
Graph	End-to-end flow	Integration tests with FakeListChatModel	Medium (seconds)
Prompts	Agent behavior quality	Eval dataset + LLM-as-judge	Slow (minutes)

This is a premium article. Sign in with your Google account to continue.