Case study
A system that documents itself
An architecture map generated from the code on every push, with a compare view for reviewing a branch before it ships.
- My role
- Sole engineer
- When
- 2026
- Status
- In use
- Stack
- Node.js, TypeScript, React Flow, Supabase
0
hours of manual upkeep
Every push
when the map regenerates
The problem
As the only engineer on a system that changes daily, hand-written architecture docs go stale within a week. Anyone joining later, including a second engineer, would have to reverse-engineer how the pieces fit together.
What I built
A script that reads the codebase and produces one structured snapshot of how the app is put together. It is deterministic: no AI, no network and no database, so the same code always gives the same map, and secret values never appear in it. It captures:
- every screen, and the data and server functions it uses
- every server function, scheduled job and storage area
- every table in its final state, after replaying every database migration in order
- the AI assistant's tools, and the test suites
- the outside services the system depends on, and who calls what
How it's used
After a push that changes behaviour, the snapshot is published and a developer-only page draws it as an interactive map. A compare view puts two snapshots side by side, such as a branch against the live version, and flags what changed on each side. Reviewing a branch becomes a question of looking at the differences, not reading every file.
The hard part
Knowing a table's real shape means replaying hundreds of migrations in order, with every create, alter and drop, and doing it by parsing SQL rather than running a database. Getting that exactly right is what makes the map trustworthy enough to review against.
Limits
The full map includes security detail that shouldn't be public, so the version shown here is redacted to screens, functions, services and how they connect.