| name | archify |
| description | Create professional architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as standalone HTML files with SVG graphics, a built-in dark/light theme toggle, and one-click export to PNG / JPEG / WebP / SVG. Use when the user asks for system architecture diagrams, infrastructure diagrams, cloud architecture visualizations, security diagrams, network topology diagrams, technical workflows, approval flows, runbooks, CI/CD flows, process diagrams, API call sequences, request lifecycles, interaction diagrams, data pipelines, analytics flows, ETL/ELT maps, PII boundaries, governance/data lineage diagrams, state machines, lifecycle diagrams, status transitions, or terminal/retry paths. |
| license | MIT |
| metadata | {"version":"2.4","author":"tt-a1i","based_on":"Cocoon-AI/architecture-diagram-generator (MIT, v1.0)"} |
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":
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"
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":
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 diagrams when the important thing is data lineage and governance. Keep labels asset-like: "clickstream", "identity map", "normalized facts", "feature vectors", "restricted join". Put sensitivity in classification: "PII touch", "encrypted PII", "approved only", "non-PII", "read-only".
Lifecycle Mode
Lifecycle diagrams use a compact JSON IR:
{
"schema_version": 1,
"diagram_type": "lifecycle",
"meta": {
"title": "Agent Run Lifecycle",
"subtitle": "State machine for planning, execution, waits, retries, and terminal outcomes",
"output": "agent-run.html",
"viewBox": [980, 720]
},
"lanes": [
{ "id": "main", "label": "Main lifecycle" },
{ "id": "waiting", "label": "Wait states" },
{
If you have filesystem/tool access, create a lifecycle JSON file and render it with:
node archify/renderers/lifecycle/render-lifecycle.mjs lifecycle.json lifecycle.html
The renderer:
- Places states by lane + column
- Uses lanes to separate the happy path, wait states, and exception/recovery paths
- Uses semantic state types:
start, active, waiting, decision, success, failure, and neutral
- Uses transition variants:
emphasis for the primary lifecycle, security for failure/cancel/timeout/policy paths, and dashed for retry/resume paths
- Fails fast on schema violations, state overlap, out-of-lane placement, unknown lanes, unknown transition endpoints, and legends pushed outside the viewBox
Use lifecycle diagrams when the important thing is state, not step-by-step work. Keep transition labels event-like: "start", "plan ready", "needs approval", "retry", "timeout", "cancel". Put terminal states on the right or in the bottom lane so endings are visually unambiguous.
The Cardinal Rule: Use CSS Classes, Not Inline Colors
The theme toggle works by switching CSS custom properties. If you hardcode fill="rgba(...)" or stroke="#22d3ee" on SVG elements, those values will NOT update when the theme changes. Always prefer the class-based system.
Do this
<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>
Don't do this
<rect fill="rgba(6, 78, 59, 0.4)" stroke="#34d399" .../>
<text fill="white" .../>
Design System
Component color classes
| Component Type | Fill class | Text color class | When to use |
|---|
| Frontend | c-frontend | t-frontend | Client apps, browsers, mobile, UI |
| Backend | c-backend | t-backend | Services, APIs, workers, daemons |
| Database | c-database | t-database | DBs, caches, log files, data stores |
| Cloud / AWS | c-cloud | t-cloud | Managed cloud services, infra |
| Security | c-security | t-security | Auth providers, secrets, guards |
| Message Bus | c-messagebus | t-messagebus | Kafka/RabbitMQ/SNS/Event buses |
| External/Generic | c-external | t-muted | Users, 3rd parties, anything uncategorized |
Text on a dark or light background uses three neutral helpers:
| Text class | Role |
|---|
t-primary | Component names / titles |
t-muted | Sublabels, annotations |
t-dim | Tertiary / footer metadata |
Per-semantic text accents also exist: t-frontend, t-backend, t-database, t-cloud, t-security, t-messagebus, t-external — use when you want a label colored to match its component type (e.g., a small "OAI Protected" caption inside a cloud-type box).
Arrow classes
| Class | Marker id | Semantic |
|---|
a-default | #arrowhead | Standard data/flow arrow |
a-emphasis | #arrowhead-emphasis | Live event stream / hot path |
a-security | #arrowhead-security | Auth / security flow (dashed) |
a-dashed | #arrowhead-dashed | Async / secondary (dashed) |
Always set stroke-width on the line (e.g., 1.5) — the class only sets color and dasharray.
Boundary classes
| Class | Purpose |
|---|
c-security-group | Dashed rose boundary for SGs |
c-region | Large dashed amber region/cluster |
c-lane | Subtle swimlane for workflow/process diagrams |
Typography
Inherit from the SVG root (already wired to JetBrains Mono). Font sizes: 12px for component names, 9px for sublabels, 8px for annotations, 7px for tiny labels.
Visual Elements
Background grid: Automatically themed via .c-grid inside the <pattern id="grid">. Don't modify.
Component boxes: Rounded rectangles (rx="6"), stroke-width="1.5", using the .c-<type> classes.
Arrow z-order: Draw connection arrows BEFORE component boxes (earlier in the SVG). SVG paints in document order, so arrows drawn first appear behind shapes drawn later.
Masking arrows behind transparent fills: Component fills are semi-transparent, which means arrows behind them bleed through. The template solves this with a two-rect pattern — an opaque mask rect, then the styled component on top:
<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-database" stroke-width="1.5"/>
Always use c-mask instead of hardcoded fill="#0f172a" — the mask color itself is themed.
Message buses / Event buses: Small connector elements between services:
<rect x="X" y="Y" width="120" height="20" rx="4" class="c-messagebus" stroke-width="1"/>
<text x="CENTER_X" y="Y+14" class="t-messagebus" font-size="7" text-anchor="middle">Kafka / RabbitMQ</text>
Spacing Rules
CRITICAL: When stacking components vertically, ensure proper spacing to avoid overlaps:
- Standard component height: 60px for services, 80-120px for larger components
- Minimum vertical gap between components: 40px
- Inline connectors (message buses): Place IN the gap between components, not overlapping
Example vertical layout:
Component A: y=70, height=60 -> ends at y=130
Gap: y=130 to y=170 -> 40px gap, place bus at y=140 (20px tall)
Component B: y=170, height=60 -> ends at y=230
Wrong: Placing a message bus at y=160 when Component B starts at y=170 (causes overlap)
Right: Placing a message bus at y=140, centered in the 40px gap (y=130 to y=170)
Security Group & Region Boundary Padding
When a component sits inside a c-security-group or c-region boundary, the small label on the boundary (e.g., sg-name :port, AWS Region: us-west-2) needs room above the inner component — otherwise the label visually crashes into the box below it.
Rule: boundary y = inner-component y − 30, boundary height = inner-component height + 50. Place the label 18px below the boundary top (baseline). This yields ~12px clear gap between the label baseline and the inner component's top edge.
Example — a Load Balancer (y=280, h=50) inside a security group:
<rect x="350" y="250" width="120" height="100" rx="8" class="c-security-group" stroke-width="1"/>
<text x="358" y="268" class="t-security" font-size="8">sg-name :port</text>
<rect x="360" y="280" width="100" height="50" rx="6" class="c-mask"/>
<rect x="360" y="280" width="100" height="50" rx="6" class="c-cloud" stroke-width="1.5"/>
If the inner component is taller (e.g., a 100px multi-line box), keep the 30/50 offsets — the extra vertical room on top stays the same, the bottom padding grows naturally.
Legend Placement
CRITICAL: Place legends OUTSIDE all boundary boxes (region boundaries, cluster boundaries, security groups).
- Calculate where all boundaries end (y position + height)
- Place legend at least 20px below the lowest boundary
- Expand SVG viewBox height if needed to accommodate
Layout Structure
- Header — Title with pulsing dot indicator, subtitle
- Toolbar (auto-included from template) — theme toggle + export menu, top-right fixed position
- Main SVG diagram — contained in rounded border card
- Summary cards — grid of 3 cards below diagram with key details
- Footer — minimal metadata line
Component Box Pattern
<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-<type>" stroke-width="1.5"/>
<text x="CENTER_X" y="Y+20" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">LABEL</text>
<text x="CENTER_X" y="Y+36" class="t-muted" font-size="9" text-anchor="middle">sublabel</text>
Arrow Patterns
<line x1="..." y1="..." x2="..." y2="..." class="a-default" stroke-width="1.5" marker-end="url(#arrowhead)"/>
<line x1="..." y1="..." x2="..." y2="..." class="a-emphasis" stroke-width="1.5" marker-end="url(#arrowhead-emphasis)"/>
<path d="..." class="a-security" stroke-width="1.5" marker-end="url(#arrowhead-security)"/>
<path d="..." class="a-dashed" stroke-width="1" marker-end="url(#arrowhead-dashed)"/>
Pair each arrow class with the matching marker id (same suffix).
Info Card Pattern
<div class="card">
<div class="card-header">
<div class="card-dot COLOR"></div>
<h3>Title</h3>
</div>
<ul>
<li>• Item one</li>
<li>• Item two</li>
</ul>
</div>
Valid card-dot colors: cyan, emerald, violet, amber, rose, orange, slate — all automatically re-theme. Pair the dot to its component semantic (e.g., orange for a "Messaging" card, slate for an "External Services" card).
Template
Copy and customize the template at assets/template.html. Customization points:
- Update the
<title> and header <h1> text + subtitle
- Modify SVG
viewBox dimensions if needed (default: 1000 x 680)
- Add/remove/reposition component boxes using the
.c-<type> classes
- Draw connection arrows using
.a-<variant> classes
- Update the three summary cards
- Update footer metadata
Do NOT remove the .toolbar element, the <script> blocks, or the :root / [data-theme="..."] CSS. Those are what give every generated diagram the theme toggle and export buttons.
Output
Produce a single self-contained .html file with:
- Embedded CSS (no external stylesheets except Google Fonts)
- Inline SVG (no external images)
- Small amount of embedded JS (theme toggle + export) — keep as-is from template
The file should render correctly when opened directly in any modern browser. The Export menu should cleanly copy PNG to the clipboard, download PNG / JPEG / WebP (all at 4× source resolution, rendered natively by the browser — no bitmap upsampling), and download a dual-theme self-contained SVG whose colors follow the embedding host's prefers-color-scheme (dark by default; swaps to light under a light host; svg[data-theme="..."] still works as a manual override).
