Guides · Series · 2 parts
From Unknown Codebase to Architecture Document
A three-pass methodology for compressing any codebase into validated diagrams and decisions — and then a LangGraph pipeline that runs it for you.
Inheriting a codebase you did not write
Architecture documentation fails in two directions. Written by hand, it is accurate on the day it ships and quietly wrong six weeks later. Generated by pointing an LLM at a repository, it is fluent, confident, and unvalidated — which is worse, because nobody can tell which parts are real.
The way out is to treat it as a compression problem with validation gates rather than a summarisation problem. You cannot fit a large codebase in a context window, so the question is what you throw away at each pass and how you check that what survived is true.
Part 1 is the methodology: three passes, language-agnostic and architecture-style-agnostic, producing diagrams, debt scores, and decisions a team can actually act on. Part 2 automates it as ArchLens — a twelve-node LangGraph pipeline with module chunking, four validation gates, a human-in-the-loop review interrupt, and real error recovery.
Read Part 1 first even if you only want the pipeline. The gates in Part 2 only make sense once you know what they are gating.
Which part solves my problem
The series reads in order, but if something is already broken, start here.
The series
2 of 2 published
From Unknown Codebase to Architecture Document: A Complete Practitioner's Guide
A 3-pass methodology for compressing any codebase - in any language, any architecture style - into validated diagrams, debt scores, and decisions that engineering teams and stakeholders can actually act on
From Unknown Codebase to Architecture Doc, Automated - Building the LangGraph Pipeline
How ArchLens - a 12-node LangGraph pipeline - turns any Git repository into a validated architecture document: state design, chunking logic, all four validation gates, human-in-the-loop review, and production-ready error recovery
Other guide series
Agentic AI with LangGraph
An eight-part guide to the part of agent engineering nobody demos: making the thing survive a restart, a concurrent write, a bad tool call, and a Tuesday deploy.
Harness Engineering
AI systems do not fail at the model layer. They fail in the code around it — and that code is a designable layer with its own architecture.
RAG Engineering
Most RAG failures happen upstream of the LLM, accumulate invisibly, and only surface as an incident. This series names each one.
Claude Code Playbook
Claude Code has four layers — context, skills, subagents, hooks — and the variable that decides which one you need is enforceability, not capability.
AI Control Plane
A fleet of agents needs a layer that is not itself an agent — observability, policy, orchestration, versioning, cost, and audit, built as infrastructure.
Agentic AI in the Data Center
In physical infrastructure, an agent’s autonomy is capped by reversibility and jurisdiction — not by how good the model is.
