Stacks Technical Diagrams

Technical Diagrams for Stacks

Turn a small typed JSON specification into one self-contained, interactive HTML diagram. Static output is the default; motion is opt-in.

Every delivered artifact carries a theme toggle (persists in localStorage, respects prefers-color-scheme), pan/zoom, node search, focus with authored upstream/downstream reach, route probing, a semantic lens, an overview radar, presentation mode, guided stories, and an export menu (clipboard PNG; PNG/JPEG/WebP raster at up to 4x; dual-theme SVG; WebM for motion; 1200x630 share cards). Those are reader capabilities that already exist in the output, not authoring work.

Attribution

This skill ports the renderer, validator, and viewer from Archify 2.17.0-dev.1 by tt-a1i under the MIT license. Archify is itself a fork and rewrite of Cocoon AI's architecture-diagram-generator 1.0. Preserve LICENSE and THIRD_PARTY_NOTICES.md when redistributing this skill or substantial portions of its source.

Running the CLI

Every command below is one launcher invocation from the Stacks project root:

.claude/skills/stacks-technical-diagrams/bin/diagrams doctor

The launcher runs Bun against the skill's own empty bunfig.toml with --no-env-file, so a diagram render never inherits the application's preload chain or its .env. Never call the renderers with a bare bun; use the launcher (or bun --config=<skill>/bunfig.toml --no-env-file <skill>/bin/technical-diagrams.mjs if you need the explicit form).

Commands: render, validate, deliver, compare, preview, visual-check, check, inspect, migrate, guide, brands, examples, doctor, demo. Run diagrams with no arguments for the full usage block.

Fast authoring path

Use this bounded path for ordinary generation.

1. Choose architecture, workflow, sequence, dataflow, or lifecycle from the question. When ambiguous, run diagrams guide "<scenario>" --json.

2. Read one matching schema in schemas/, plus schemas/common.schema.json, plus one matching JSON example in examples/. Read only those files. Use the example for field shape, never for facts. New workflow sources use schema_version: 2; keep schema_version: 1 only when preserving an existing workflow's fixed geometry.

3. Artifact first: the next tool action writes the candidate JSON. Do not plan exact coordinates in prose and do not read renderer internals before the first candidate. Start with one clear main path, short side branches, sparse labels, and at most 12 primary nodes. Set meta.quality_profile: "showcase" unless the user explicitly wants a dense standard map. Start with automatic routes and labels; do not add via, channelX, channelY, or labelAt before a diagnostic asks for one, and apply at most one diagnosed geometry control per repair.

4. Validate after every candidate edit and immediately before handoff:

   .claude/skills/stacks-technical-diagrams/bin/diagrams validate <type> <candidate.json> --quality showcase --json
   

   A receipt with only 4 artifact checks is basic validation, never showcase acceptance. A showcase pass reports all 9 artifact checks with 0 composition errors and 0 warnings. For a workflow v2 geometry diagnosis, run validate workflow <candidate.json> --layout-json and read the stable compiler receipt; solver internals are not authoring controls. A passing final validation freezes the candidate: do not edit it afterward.

5. Deliver once, as the final acceptance step:

   .claude/skills/stacks-technical-diagrams/bin/diagrams deliver <type> <candidate.json> <output.html> --quality showcase --json
   

   A non-zero exit is never success. On failure, change only the diagnosed subject, verify evidence, choose from supportedFixes, and rerun. Keep correcting 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.

Inspect renderer or validator source only after an unsupported internal diagnostic or two failed focused repairs.

Stacks repository workflow

1. Inspect the implementation before drawing. Treat app/ as overrides and storage/framework/defaults/app/ as fallbacks. Follow registrations in app/Routes.ts, route files, actions, jobs, listeners, middleware, models, config, resources, and the framework entry points that matter to the requested view.
2. Read the relevant Stacks domain skill before mapping an unfamiliar subsystem. Common companions are stacks-router, stacks-actions, stacks-models, stacks-database, stacks-jobs, stacks-events, stacks-realtime, and stacks-cloud.
3. Draw one question per diagram. For a runtime overview, prefer browser or client -> stx/router -> action or service -> model/query -> database, then add only the external systems and trust boundaries that story needs.
4. Write output to the user's requested path. When no path is given, use docs/public/diagrams/<descriptive-name>/index.html and keep the source JSON beside it. That path matters: BunPress only renders docs/**/*.md and copies docs/public/**, so a diagram written anywhere else under docs/ never reaches the built site. The directory-plus-index.html shape is what the deployed docs host serves at the clean URL /docs/diagrams/<descriptive-name>; a bare <name>.html is redirected to an extensionless path that does not exist. Link to it from a docs page as /diagrams/<descriptive-name> (BunPress adds the /docs base).

To pin architecture nodes to real code, pass --repo-root . and author meta.repository; nodes then mark themselves SRC n and open Git-verified files and line ranges at one pinned commit. See references/authoring-contract.md.

Type router

Trigger phrases: "architecture/system/cloud diagram" -> architecture (unless clearly process-oriented). "workflow/flow/process/runbook/approval/CI-CD/incident" -> workflow. "sequence/interaction/call chain/who calls whom" -> sequence. "data flow/pipeline/ETL/lineage/PII/governance" -> dataflow. "state/status/lifecycle/state machine/retry/terminal" -> lifecycle.

Mermaid input

Read Mermaid for topology and meaning, then author fresh JSON. Do not parse or re-render Mermaid styling.

• flowchart / graph -> workflow, or architecture for a component map. subgraph becomes a lane or a boundary; a diamond node becomes a decision or security node.
• sequenceDiagram -> sequence. participant becomes a semantic participant, ->> a message, -->> a return variant, Note a message note, rect a segment.
• stateDiagram -> lifecycle. [*] becomes the start type or the terminal lane; transition labels stay event-like.

Drop Mermaid styling and keep only topology and meaning. Grouping, lane order, and emphasis are your judgment, and that judgment is the product.

Authoring invariants

• One obvious main path; side branches leave the nearest main-path node. Remove low-value edges before adding routing controls. If a diagram needs 20+ edges, remove edges until the main path is obvious.
• Detail belongs in summary cards, not in extra arrows.
• Omit meta.visual_preset by default so every diagram opens in classic. Color mode and visual preset are independent: switching light/dark preserves the preset. Set signal-flow, blueprint, or editorial only when the user asks for that style.
• Omit meta.subtitle by default. Never invent one that restates the title, nodes, or cards.
• Omit meta.legend for the truthful auto default. When needed, use only mode: auto|all|hidden and renderer-supported entries.<kind>.label|visible. Labels never change semantics.
• Component types are frontend, backend, database, cloud, security, messagebus, external. Variants are default, emphasis, security, dashed.
• Relationship labels are semantic data. When one collides, move the label, adjust the route or spacing, then shorten the wording while preserving meaning. Delete wording only when both endpoints fully imply it and it carries no protocol, action, direction, sync/async behavior, or cross-boundary mechanism. Deleting a meaningful label is not a geometry repair.
• Spacing means clear gap, not center distance. A label's clear gap must exceed its measured mask width.
• Automatic routes own their endpoint sides: the first and final segment leave and enter perpendicular to that side. Automatic Port Spread is default behavior for architecture, workflow, dataflow, and lifecycle; it stands down for explicit via, channelX, channelY, labelAt, or a non-auto route.
• Never accept an edge crossing an unrelated opaque node, an ambiguous shared corridor, or a label masking another route.
• For sequence diagrams, omit meta.column_fit for the stable fixed layout. Set "spread" when a wide viewBox leaves unused horizontal space or meaningful participant labels do not fit; do not shorten semantic labels first.
• Lifecycle phase columns 0..4 occupy the main rail; an event or terminal column N in 0..2 aligns beneath main column N + 2. A recoverable state uses type: "failure" plus a real transition back to the active state.
• Omit meta.engineering_profile by default. Enable deployment-ownership only when the user explicitly asks for production deployment topology, ownership handoff, or a fail-closed deployment review, and the facts are known. It fails closed on missing owners, region placement, private database scope, or named crossings; repair the facts rather than removing the profile.
• Set meta.animation: "trace" only for a demo or presentation view. It respects prefers-reduced-motion and leaves static output unchanged.
• meta.views is optional: at most five curated chapters built from stable node IDs.
• meta.locale (en or zh-CN) localizes renderer-owned viewer UI only, never authored content. For any other language, omit it and say plainly that the fixed viewer UI and <html lang> fall back to English.
• Treat the artifact as a first-screen desktop composition. One responsive artifact serves laptops and external displays; never emit device-specific HTML or alternate topology. Before handoff the page must not scroll horizontally or vertically at 1440x900, 1600x1000, and 1920x1080 (plus 2048x1320 for a large-display composition). Repair overflow by removing genuinely redundant content or compacting spacing before shrinking nodes or labels. Never counterfeit a pass with overflow: hidden, clipping, an internal scroller, a stretched SVG, or smaller typography.

Read references/authoring-contract.md only when you need field enums, spacing math, geometry repair rules, repository evidence, or mode-specific placement.

Delivery evidence

deliver freezes the specification bytes into a private same-directory snapshot, renders and checks that snapshot, atomically commits the HTML, and reports SHA-256 plus byte counts for both specification and artifact. It proves deterministic artifact checks; it does not exercise the viewer in a browser.

.claude/skills/stacks-technical-diagrams/bin/diagrams visual-check <output.html> --json

visual-check drives a system Chrome over the DevTools Protocol against the exact delivered HTML, without rerendering it, and writes screenshots plus a machine-readable receipt. It exits 2 (skipped) when no Chrome is installed. Keep three claims separate: deliver proves artifact checks, visual-check proves bounded browser behavior, and perceptual review requires a human or an image-capable reviewer. Never run visual-check after a failed delivery: it would inspect the stale last-good artifact.

For an active authoring loop, preview watches one JSON file on a random loopback port and reloads only after a candidate passes every gate, keeping the last verified diagram visible through failures:

.claude/skills/stacks-technical-diagrams/bin/diagrams preview <type> <input>.json <output>.html --quality showcase

Never start preview by default. deliver --open is an opt-in one-shot handoff after commit. Full receipt fields, coverage, sidecars, and exit behavior: references/delivery-contract.md.

Architecture Delta

For design or PR review, compare two validated architecture snapshots as Before / Delta / After with a machine receipt of exactly what was added, removed, changed, moved, and rerouted:

.claude/skills/stacks-technical-diagrams/bin/diagrams compare architecture base.json head.json delta.html --receipt delta.receipt.json --json

Component identity is components[].id, relationship identity is connections[].id (required for compare), and boundary identity is derived from kind + label. The delta reports authored facts only; it infers no impact, risk, or merge safety.

Brand marks

Brand identity is optional and explicit. When a node names a real product, look up a canonical built-in ID from the bundled catalogue of 107 marks:

.claude/skills/stacks-technical-diagrams/bin/diagrams brands "postgres" --json

Never infer a brand from a vague role such as "database", and never let a badge replace the semantic type, label, or relationship facts. brands capture <url> is the one command in this skill that makes a network request: it is user-initiated, it pins the result by SHA-256, and render, validate, deliver, and compare never perform an unpinned capture. See references/brand-marks.md.

Dependency-free and offline contract

Do not install packages or fetch runtime assets. Standalone validators for all five schemas are checked in, the renderers use Bun's Node compatibility modules, and delivered HTML embeds its own subsetted JetBrains Mono, so a page renders with no network access. Upstream's update-notifier scripts are deliberately not vendored: this port is pinned by metadata.source_commit and is updated by re-porting, never by a runtime download.

Verify the install with diagrams doctor, and generate a ready-to-open example with diagrams demo <output-directory> before the first custom diagram.

Deeper references

Read one of these only when the fast path calls for it.

Hand-placed fallback (no Bun available)

When the CLI cannot run, copy assets/template.html, place SVG by hand using the design system below, and run the self-review checklist before delivering.

The cardinal rule: CSS classes, not inline colors. The theme toggle switches CSS custom properties, so fill="rgba(...)" or stroke="#22d3ee" will not follow the theme.

<rect x="X" y="Y" width="W" height="H" rx="6" class="c-mask"/>
<rect x="X" y="Y" width="W" height="H" rx="6" class="c-backend" stroke-width="1.5"/>
<text x="CX" y="CY" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">API Server</text>
<text x="CX" y="CY+16" class="t-muted" font-size="9" text-anchor="middle">FastAPI :8000</text>

Component fills c-frontend, c-backend, c-database, c-cloud, c-security, c-messagebus, c-external; text accents t-<same> plus t-primary / t-muted / t-dim. Arrows a-default, a-emphasis (hot path), a-security (dashed), a-dashed (async), each with an explicit stroke-width and a matching marker-end="url(#arrowhead[-variant])". Boundaries: c-security-group (dashed rose), c-region (dashed amber), c-lane. Typography inherits JetBrains Mono from the SVG root: 11-12px component names, 9px sublabels, 8px annotations, 7px tiny labels.

Hard layout rules: an opaque c-mask rect immediately before every styled c-<type> rect; all arrows before all component rects in document order; at least 40px vertical gap between components; boundary y = inner y - 30 and boundary height = inner height + 50 with the label baseline 18px below the boundary top; the legend outside every boundary and at least 20px below the lowest one.

Self-review before delivering:

1. grep -E 'fill="(#|rgb)|stroke="(#|rgb)' out.html inside the SVG returns nothing but the template's own defs.
2. Every c-<type> rect has an identical-geometry c-mask rect immediately before it.
3. All arrows appear before all component rects in document order.
4. max(y + height) over all SVG elements is at least 20px inside the viewBox height; same for x.
5. Legend y is below every boundary's y + height.
6. The .toolbar, <script> blocks, and :root / [data-theme] CSS are untouched. They are the theme toggle, viewer, and export menu.

Output

Report the checked HTML path, the diagram type, the validation summary, the specification and artifact receipt, the browser-evidence status, and a truthful visual-review status. Never claim success for a non-zero command, and never claim a visual inspection you did not perform.