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
GenAI Architectures
There are eight architectures and seven boundaries between them. Every boundary is a yes-or-no question about the task — not a judgment call about the design.
Chat Templates
A chat template is the contract between your messages and the exact token stream the model was trained on. Get it wrong and nothing raises — the model just gets quietly worse.
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.
LangGraph Agent Evals
Every layer of an agent eval stack is a measuring instrument with its own error rate — the grader included — and none of them should gate a deploy until it has been scored against known faults.
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.
Federated AI Agents
Every call that crosses from one owner to another is a seam, and a seam has five properties — contract, authority, state, failure, and accountability — that are free inside one deployment and have to be built across it.
