/explainme

name: explainme
description: Explain a codebase, subsystem, or PR to a human — visually and verifiably. Turns real code structure into a polished, validated, explorable standalone HTML map (architecture, workflow, sequence, data-flow, or lifecycle/state) with inline SVG, dark/light themes, guided walkthrough chapters, source-pinned nodes, and PNG/SVG/WebM export. Use for onboarding, "how does this system work / how does this flow work", visual PR/architecture review, or converting/beautifying Mermaid. In Hydraia it is grounded in codegraph's verified structure, not a guessed topology.
license: MIT
metadata:
  version: "0.1 (hydraia)"
  author: hydraia (José Daniel Garcés Ospina)
  vendored_from: tt-a1i/archify (MIT, v2.17)
  based_on: Cocoon-AI/architecture-diagram-generator (MIT, v1.0)

Explainme — visual, verifiable code explanation

Explain a codebase to a human as a **self-contained, interactive HTML map** compiled from a small typed JSON specification. The deterministic CLI validates every artifact before delivery and refuses to ship one that is not geometrically clean and semantically faithful — so the diagram never invents topology. Static output is the default; enable motion only for a demo or presentation.

**This is a vendored + rebranded build of [Archify](https://github.com/tt-a1i/archify) (MIT).** The MIT `LICENSE`, `THIRD_PARTY_NOTICES.md`, and the upstream attribution above are kept as required. The engine (schemas, renderers, viewer, validator) is upstream's; Hydraia adds the codegraph grounding and the onboarding framing below.

Hydraia grounding — codegraph is the topology source (read first)

Do NOT hand-guess the system's structure. In Hydraia the topology comes from **codegraph** (the verified code knowledge graph), and Explainme renders it:

1. Query codegraph for the subsystem in scope — components/modules, call edges, entry points, storage/transports, blast radius (`codegraph_explore`, callers/callees/impact). That is the ground truth. 2. Author the typed IR (below) from those **verified** nodes and edges — not from a guess. When a node maps to real code, set its source-evidence (`SRC` markers) from codegraph's file:line so the diagram is click-through to the actual source. 3. **Frame it as onboarding, not decoration.** Attach up to ~5 guided-walkthrough `views` chapters that walk a newcomer through the real paths — e.g. "request path", "auth flow", "data lineage", "startup/lifecycle". The goal is "a new engineer understands this system in 10 minutes", not "a pretty picture". 4. Then follow the fast authoring path. The model that drives this is Sonnet-class — the hard correctness lives in the deterministic CLI + codegraph, not in the model's geometry planning.

Fast authoring path

Create a self-contained, interactive HTML diagram from a small typed JSON specification. Static output is the default; enable motion only when the user asks for a demo or presentation.

Fast authoring path

Use this bounded path for ordinary generation. Do not read the optional Viewer Runtime reference unless the user asks about those features.

1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle` from the question. 2. Read one matching schema in `schemas/`, `schemas/common.schema.json`, and one matching JSON example in `examples/`. Read only those files. Fresh authorship means new stable IDs, domain wording, and layout; use the example for field shape, not facts. New workflow sources use `schema_version: 2` and its readable layout contract; keep `schema_version: 1` only when preserving an existing workflow's fixed geometry. When real product identity matters, query `node bin/archify.mjs brands "<name>" --json`; read `references/brand-marks.md` only for an unknown brand with a user-provided URL. 3. Artifact first: the next tool action must write the candidate. Write the candidate before inspecting renderer internals. Do not plan exact coordinates in prose. Start with one clear main path, short side branches, sparse labels, and at most 12 primary nodes. Set `meta.quality_profile` to `"showcase"` unless the user explicitly requests a dense `standard` map. Start with automatic routes and labels. Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic calls for one; apply at most one diagnosed geometry control per repair. 4. Validate after every candidate edit and immediately before handoff:

   node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json

A receipt with only 4 artifact checks is basic validation, never showcase acceptance. A showcase pass must report all 9 artifact checks with 0 composition errors and 0 warnings. If the candidate omits or misspells the exact `meta.quality_profile` field, fix it before geometry. For a workflow v2 geometry diagnosis, run `node bin/archify.mjs validate workflow <candidate.json> --layout-json` and use the stable compiler receipt; solver internals are not authoring controls. A passing final validation freezes the candidate: never edit it afterward. 5. For a delivered HTML, `deliver` is the final acceptance command:

   node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json

A non-zero exit can never be described as success. A failed delivery preserves any previous output, so do not run `visual-check` on that path: it would inspect the stale last-good artifact, not the failed candidate. If validation fails, change only the diagnosed `subject`, verify `evidence`, choose from `supportedFixes`, and rerun. Continue focused correction while the objective error count reaches a new minimum. If two consecutive rounds do not improve that best count, stop and report the unresolved diagnostics truthfully.

Update awareness

After the first candidate exists, run the packaged checker `scripts/check-update.mjs` once with Node and continue the requested workflow. If the command cannot run, continue