Explain Architecture

Build an accurate mental model of a codebase (or a chosen part of it) and deliver it as one self-contained HTML orientation page. The goal is orientation, not critique — a reader should finish knowing what the pieces are, how they fit, where data flows, and where to look next.

Borrowed from Practical Model-Driven Enterprise Architecture: an explanation is a view that answers a defined question for a defined audience, split into structure (what the parts are and how they connect) and behavior (what happens, in what order). Pick the scope and audience first, then explain only what serves them — "a single view tells a single idea."

Outcome spine

• Result: a single .html file with inline CSS, JavaScript, and SVG at docs/<scope>-architecture.html by default.
• Next consumer: the person orienting themselves — opened straight from disk, no server.
• Done: the file exists, scripts/validate_explain_architecture.py exits 0, and the page was rendered or sent to the user.
• Intent: a map, not the territory. 4–6 sections, one traced flow, every claim grounded in files actually read. Depth beyond that belongs to html-explainer.

Step 0 — Scope & audience (ask only if unclear)

Settle two things before exploring; infer from the request when you can, ask at most one short question when you can't: