archify

Archify Skill

Create professional technical diagrams as self-contained HTML files with inline SVG, a theme toggle, and a built-in image/SVG export menu. No external runtime dependencies beyond Google Fonts.

Every diagram this skill produces ships with:

• A Dark / Light theme toggle (top-right, persists in localStorage, respects prefers-color-scheme on first visit).
• An Export menu with Copy PNG to clipboard plus downloads for PNG / JPEG / WebP (all rasterized natively at 4× source resolution for maximum sharpness) and SVG (vector, styles inlined). The SVG download is dual-theme self-contained: it ships with both dark and light variable sets plus a @media (prefers-color-scheme) rule, so embedding it in a GitHub README (or any <img> host that exposes a color scheme) makes it follow the reader's dark/light preference automatically. All rendering happens in-browser, no server.
• A CSS-variable-driven color system so both themes remain visually consistent with the same SVG markup.

Diagram Types

Archify supports five technical diagram modes:

| Type | Use for | Output path | |------|---------|-------------| | architecture | System components, cloud resources, services, storage, security boundaries, and infrastructure relationships | Hand-place SVG components inside assets/template.html | | workflow | Technical flows, request lifecycles, approval gates, tool calls, runbooks, CI/CD paths, incident response, and process ownership | Prefer renderers/workflow/render-workflow.mjs with a workflow JSON file | | sequence | API calls, request lifecycles, service interactions, cache fallback paths, async trace/logging, and return paths over time | Prefer renderers/sequence/render-sequence.mjs with a sequence JSON file | | dataflow | Data pipelines, ETL/ELT, analytics flows, PII isolation, governance boundaries, lineage, warehouse sync, and downstream consumers | Prefer renderers/dataflow/render-dataflow.mjs with a data-flow JSON file | | lifecycle | State machines, object lifecycles, run/order/deployment status transitions, wait states, retries, terminal states, and recovery paths | Prefer renderers/lifecycle/render-lifecycle.mjs with a lifecycle JSON file |

When the user says "architecture", "system diagram", "cloud diagram", or asks to understand a codebase structure, use the architecture mode unless the requested output is clearly process-oriented.

When the user says "workflow", "flow", "process", "runbook", "sequence of steps", "approval", "CI/CD", "incident", or asks how work moves through actors/systems over time, use the workflow mode.

When the user says "sequence", "interaction", "call sequence", "request lifecycle", "API call chain", "who calls whom", or asks how multiple participants interact over time, use the sequence mode.

When the user says "data flow", "pipeline", "ETL", "ELT", "lineage", "analytics", "warehouse", "PII", "consent", "governance", or asks where data comes from, how it is transformed, and who consumes it, use the dataflow mode.

When the user says "state", "status", "lifecycle", "state machine", "terminal", "retry", "cancel", "timeout", "order lifecycle", "deployment lifecycle", "agent run lifecycle", or asks how an object changes state over time, use the lifecycle mode.

Schema Validation (all renderer modes)

Every JSON file is validated against its schema (archify/schemas/.schema.json) before any layout work runs. Schema violations exit non-zero with a path-prefixed error message — for example /cards/0/dot must be equal to one of the allowed values ["cyan","emerald","violet","amber","rose","orange","slate"] or /nodes/0/id must match pattern "^[a-zA-Z][a-zA-Z0-9_-]$". Common things the schema catches before the renderer touches the file:

• Unknown node/participant/state type, unknown card dot
• IDs containing spaces or starting with a digit
• Extra/misspelled fields (additionalProperties: false is set on every object)
• Missing required fields (label, meta.title, etc.)
• schema_version not equal to 1

If a render fails with a schema error, fix the JSON and re-run; do not edit the renderer.

Workflow Mode

Workflow diagrams use a compact JSON IR:

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": {
    "title": "Release Workflow",
    "subtitle": "PR to production deployment",
    "output": "release-workflow.html",
    "viewBox": [720, 780]
  },
  "lanes": [
    { "id": "dev", "label": "Developer" },
    { "id": "ci", "label": "CI" }
  ],
  "nodes": [],
  "edges": [],
  "cards": []
}

If you have filesystem/tool access, create a workflow JSON file and render it with:

node archify/renderers/workflow/render-workflow.mjs workflow.json workflow.html

The renderer:

• Places nodes by lane + column instead of raw SVG coordinates
• Routes edges through explicit anchors and orthogonal route presets
• Uses c-lane swimlanes plus the normal semantic component classes
• Adds a c-mask label background for routed labels
• Fails fast on schema violations, overlapping nodes, out-of-lane placement, and labeled short links — keep adjacent-step labels minimal in the JSON to avoid the short-link error

Use workflow labels sparingly. Adjacent steps should often be unlabeled; reserve labels for cross-lane transitions, approval decisions, async trace writes, and return paths.

Sequence Mode

Sequence diagrams use a compact JSON IR:

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": {
    "title": "Cache Miss Request Sequence",
    "subtitle": "Frontend request path with auth and cache fallback",
    "output": "cache-miss-request.html",
    "viewBox": [820, 760]
  },
  "participants": [
    { "id": "web", "type": "frontend", "label": "Web App", "sublabel": "React UI" },
    { "id": "api", "type": "backend", "label": "API", "sublabel": "request handler" }
  ],
  "messages": [],
  "activations": [],
  "cards": []
}

If you have filesystem/tool access, create a sequence JSON file and render it with:

node archify/renderers/sequence/render-sequence.mjs sequence.json sequence.html

The renderer:

• Places participants across the top and time downward
• Uses semantic message variants: emphasis, security, return, and dashed
• Uses activation bars to show ownership duration
• Uses light segment bands as story landmarks
• Fails fast on schema violations, overflowing participants, unknown message endpoints, and rows that are too tight

Use sequence diagrams when the important thing is order over time. Keep labels short; prefer "GET /path", "verify JWT", "cache miss", "emit trace", and "200 JSON" over prose sentences.

Data-flow Mode

Data-flow diagrams use a compact JSON IR:

{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "meta": {
    "title": "Product Analytics Data Flow",
    "subtitle": "Events, consent, PII isolation, warehouse sync, and consumers",
    "output": "product-analytics.html",
    "viewBox": [900, 720]
  },
  "stages": [
    { "label": "Sources" },
    { "label": "Ingest" },
    { "label": "Process" },
    { "label": "Store" },
    { "label": "Consume" }
  ],
  "nodes": [],
  "flows": [],
  "cards": []
}

If you have filesystem/tool access, create a data-flow JSON file and render it with:

node archify/renderers/dataflow/render-dataflow.mjs dataflow.json dataflow.html

The renderer:

• Places nodes by lifecycle stage + row
• Uses vertical stage bands for source, ingest, process, store, and consume boundaries
• Uses flow labels to name data assets, plus optional classification for PII/governance context
• Uses semantic variants: emphasis for the primary data path, security for PII/policy/consent/restricted joins, and dashed for async or batch derivations
• Fails fast on schema violations, node overlap, stage overflow, unknown flow endpoints, missing labels, and unreadably short arrows

Use data-flow diagr