langgraph-architecture-review

LangGraph Architecture Review

Outcome

Turn the project's real LangGraph code into a traceable architecture review:

• a Mermaid graph grounded in source locations;
• state, node, edge, persistence, HITL, model, tool, and side-effect boundaries;
• a feature-level explanation of how the graph delivers the user's task;
• prioritized improvements with evidence, expected effect, risk, and verification.

The source code and compiled graph are evidence. A plausible diagram is not evidence.

Ownership

Default to review-only: inspect and report without editing project code. Only modify a graph when the user explicitly requests implementation after reviewing the architecture.

The named output is LANGGRAPH_ARCHITECTURE_PACKET. Read references/review-contract.md before writing the final report. Read references/upstream-sources.md when the user asks for current APIs, latest architecture, framework comparison, persistence, HITL, or migration guidance.

Workflow

CREATE A TODO LIST FOR THE TASKS BELOW:

1. Resolve the project root. Read applicable AGENTS.md and architecture docs. If no readable project exists, report a blocker and stop.

2. Find LangGraph dependencies and imports. Record the installed Python package version; never infer the version from training data.

3. If the user asks for “latest” or current best practices, check the official release and live documentation listed in references/upstream-sources.md. If network access fails, mark the comparison local-only instead of guessing.

4. Run the static inventory from the project root:

   python /absolute/path/to/langgraph-architecture-review/scripts/inspect_langgraph.py . \
     --output /tmp/langgraph-architecture.md \
     --json /tmp/langgraph-architecture.json
   

5. Read every discovered graph entrypoint, state schema, node callable, router, persistence configuration, and graph-facing API. If the scanner misses dynamic construction, add that evidence manually with file and line references.

6. Use runtime introspection only when importing the graph is demonstrably side-effect free. Prefer the public API: