Designer & builder

Clear Diagrams

Evidence-backed architecture diagrams on demand

6-stage pipeline4 artifacts per run

Harrison Halperin

Project brief

Shipped

Problem

Architecture diagrams go stale faster than teams can redraw them.

Outcome

A manifest-driven plugin that regenerates layered Mermaid architecture docs from live repository evidence, plus preview-safe HTML and split sources so large diagram sets stay readable.

Evidence

Validation rejects incomplete coverage and leaked local filesystem paths before a run is considered done.
Validation fails the run if local machine paths leak or preview/HTML/split-source artifacts are missing.

Key decisions

Allowlist boundary: The scanner only touches repositories declared in the manifest, paths outside that list are out of scope.
Default posture: Local-only scanning and a single-agent worker profile are the defaults; parallel profiles are opt-in.
Output contract: Every figure is followed by a plain-language paragraph so dense Mermaid is never left unexplained.
Safety gate: Validation fails the run if local machine paths leak or preview/HTML/split-source artifacts are missing.

System

The first figure is the generation pipeline from manifest to validated artifacts. The second shows how a single run keeps durable state so work can pause and resume.

Manifest to validated diagrams

1Manifestrepos · evidence classesscopes the allowlist

2Plan + queuegranular tasksone class per task

3Scanlocal or assistant providerAPIs, infra, workflows

4Merge graphnodes · edges · evidenceshared intermediate model

5RenderMermaid · preview · HTMLfull doc + split sources

6Validategatecoverage · path leakreject incomplete output

Each phase is a bounded unit of work (one repo and one evidence class at a time) so runs stay resumable and preview-friendly as the diagram set grows.

Run artifacts

One run directory, several artifacts

Run statequeue · evidence · graphresumable on disk

Full diagram docMermaid + narrativeself-explanatory pages

Preview indexMermaid-free Markdownstays light in preview

HTML viewerdependency-freelocal browse without a CDN

Split sourcesone .mmd per diagrameditable pieces

Durable run state holds the queue, evidence packs, merged graph, and every render artifact, so a failed or paused run can resume without starting over.

Why generation is a pipeline

Architecture diagrams go stale faster than anyone can hand-update them, and monolithic Mermaid files choke preview panes. I treat generation as a small pipeline instead of one prompt: a manifest scopes which repos and evidence classes to scan, granular tasks run locally (or via an optional assistant-backed provider), evidence merges into a graph, and the render stage writes a full document alongside a preview index, a dependency-free HTML viewer, and one `.mmd` file per diagram. Validation rejects incomplete coverage and leaked local filesystem paths before a run is considered done. Parallel worker profiles exist, but the default stays single-agent and local-only: no commits, PRs, or publishes without an explicit ask. Diagram-first is the pipeline that makes the default fire. Dual channels keeps diagram scaffolding out of the authoring thread.

Annotation notes

Allowlist boundary

The scanner only touches repositories declared in the manifest. Paths outside that list are out of scope.

Default posture

Local-only scanning and a single-agent worker profile are the defaults; parallel profiles are opt-in.

Output contract

Every figure is followed by a plain-language paragraph so dense Mermaid is never left unexplained.

Safety gate

Validation fails the run if local machine paths leak or preview/HTML/split-source artifacts are missing.

Skills

Portfolio graph

Hover nodes · click empty canvas to zoom/pan

Maps how the work here connects. Open the Portfolio graph →

Professional
Personal
Skill
Writing