Application Structure
How to decide when to structure a LangGraph project, how to separate graph topology from node logic from tools, how to navigate the monorepo vs polyrepo decision, what breaks when you get structure wrong, and how the layout evolves as your agent count grows.
Quick Reference
- →Don't structure until you feel the pain — a single-file agent is fine for 1-3 nodes with one developer
- →Import direction rule: graphs import nodes, nodes import tools, tools import state — never import upward
- →Keep the graph file thin — it should read like a flowchart, not contain business logic
- →Organize tools by domain (search_tools.py, db_tools.py) so they're reusable across multiple agents
- →Use langgraph.json to declare graph entry points, environment files, and dependencies for LangGraph Platform
- →MemorySaver is development-only — use PostgresSaver or SqliteSaver for production persistence
- →Test each layer independently: tools with unit tests, nodes with FakeListChatModel, graphs with integration tests
- →Structure evolves with scale: single file at 1 agent, shared packages at 3, versioned libraries at 10+
When a Single File Is Fine
Before you create a /graphs, /nodes, /tools directory tree, ask whether your agent needs it. Most agents start as a single file, and many should stay that way. Structure has a cost: more files, more import indirection, more places for circular imports to hide. The benefit only materializes when you have something to separate.
| Scenario | Structure needed? | Why |
|---|---|---|
| 1 agent, <5 nodes, 1 developer | No — single file | Nothing to separate. Structure adds overhead with no benefit. |
| 1 agent, 5–15 nodes, or >1 developer | Minimal — state + graph + nodes | Split only when files become too long to navigate or when two developers keep editing the same file. |
| 2+ agents sharing tools or state | Yes — full structure | Shared code without a shared module means copy-paste bugs. This article applies. |
| 3+ agents, multiple teams | Yes — monorepo or polyrepo | See section 4. Team structure drives project layout at this scale. |
Creating /graphs, /nodes, /tools, /state, /prompts for a 3-node agent adds 5 files and import indirection for no benefit. Start with one file. Split when you feel the pain of not splitting — when two people edit the same file, when tests can't import a node without pulling in the whole graph, or when you've copy-pasted a tool for the third time.
A team scaffolded a full monorepo for a single support agent. The graph had 3 nodes. They spent more time debugging circular imports across 7 modules than building the agent. When they collapsed it back to one file, the agent shipped in 2 days.
Learn this in → 20 seconds