How Archify Diagrams Represent CI/CD Pipelines: A Complete Technical Guide

Archify diagrams represent CI/CD pipelines through a specialized Workflow type that uses a JSON schema to define lanes for participants, nodes for stages, and edges for transitions, rendering them into self-contained HTML with automatic layout and orthogonal routing.

Archify is an open-source documentation-generation tool that transforms plain-text descriptions or Mermaid snippets into production-ready, theme-aware HTML diagrams. When you need to visualize deployment automation, Archify diagrams represent CI/CD pipelines using a structured domain-specific language that enforces schema validation and produces portable visualizations without external dependencies.

The Workflow Schema Foundation

Archify models CI/CD pipelines using the Workflow diagram type defined in archify/schemas/workflow.schema.json. This schema enforces a strict structure that separates visual presentation from logical flow.

Lanes as Pipeline Participants

The lanes array assigns each logical actor a distinct horizontal track. In a typical CI/CD pipeline, you define lanes for Developer, CI, Staging, and Production environments. Each lane object requires an id and label property:

{
  "lanes": [
    { "id": "dev", "label": "Developer" },
    { "id": "ci",  "label": "CI" },
    { "id": "ops", "label": "Ops" }
  ]
}

The renderer in archify/renderers/workflow/render-workflow.mjs automatically calculates lane heights and spacing to prevent node overlap.

Nodes as Pipeline Stages

Each pipeline stage becomes a node with a label, optional icon, and type. Nodes are positioned on specific lanes using the laneId field that references a lane's id. The example in archify/examples/agent-tool-call.workflow.json demonstrates this pattern with nodes for "pull request", "tests", "approval", and "build image".

{
  "nodes": [
    { "id": "pr",    "label": "Pull Request", "laneId": "dev" },
    { "id": "test",  "label": "Run Tests",    "laneId": "ci" },
    { "id": "build", "label": "Build Image",  "laneId": "ci" }
  ]
}

Edges as Transitions

Edges connect nodes and represent pipeline transitions. They support label properties for conditional logic (e.g., "Pass" or "Fail"), condition fields for complex routing, and variant properties controlling visual style (straight, curved, or orthogonal). The routing engine automatically avoids collisions and respects lane boundaries.

{
  "edges": [
    { "from": "pr",   "to": "test" },
    { "from": "test", "to": "build" }
  ]
}

Modeling CI/CD Concepts

Archify provides specific constructs for common CI/CD patterns through special node variants and lane configurations.

Decision Gates

Decision points such as CI pass/fail checks or deployment approvals are modeled as diamond-shaped gate nodes. Set the variant property to "gate" to instruct the renderer to draw a decision diamond. The Hivenue CI/CD example in experiments/v3-mermaid-validation/sources/4-hivenue-cicd.mmd demonstrates this pattern with CI pass/fail diamonds translated to gate nodes.

{
  "id": "gate",
  "label": "CI Pass?",
  "laneId": "ci",
  "variant": "gate"
}

Connect multiple outgoing edges to create branching logic:

{
  "edges": [
    { "from": "gate", "to": "build", "label": "Pass" },
    { "from": "gate", "to": "pr",    "label": "Fail", "variant": "dashed" }
  ]
}

Exception Handling Paths

Special exception lanes isolate error-recovery paths without cluttering the main flow. According to archify/SKILL.md (section Short side branches), mark these lanes with "variant": "exception" to visually distinguish failure routes from standard deployment paths.

From JSON to HTML: The Rendering Pipeline

When you feed Archify a workflow JSON, the CLI tool archify/bin/archify.mjs executes a four-stage rendering process.

Validation and Layout

1. Schema Validation: The JSON is validated against archify/schemas/workflow.schema.json, ensuring all required fields (lanes, nodes, edges) are present and type-correct.
2. Automatic Layout: Nodes are spaced on their assigned lanes using an internal grid system that prevents overlap.
3. Edge Routing: A shared orthogonal routing engine calculates arrow paths that respect lane boundaries and gate positions.

Export and Theming

The generated HTML includes a light/dark theme toggle and a one-click export button supporting PNG, JPEG, WebP, and SVG formats. No external assets are required; everything lives in a single HTML file suitable for embedding in READMEs or wikis.

Practical Implementation

Basic CI/CD Pipeline JSON

Create a minimal pipeline definition that moves from pull request through testing to deployment:

{
  "lanes": [
    { "id": "dev", "label": "Developer" },
    { "id": "ci",  "label": "CI" },
    { "id": "ops", "label": "Ops" }
  ],
  "nodes": [
    { "id": "pr",    "label": "Pull Request",      "laneId": "dev" },
    { "id": "test",  "label": "Run Tests",         "laneId": "ci" },
    { "id": "gate",  "label": "CI Pass?",          "laneId": "ci", "variant": "gate" },
    { "id": "build", "label": "Build Image",       "laneId": "ci" },
    { "id": "deploy","label": "Deploy to Staging", "laneId": "ops" }
  ],
  "edges": [
    { "from": "pr",    "to": "test" },
    { "from": "test",  "to": "gate" },
    { "from": "gate",  "to": "build", "label": "Pass" },
    { "from": "gate",  "to": "pr",    "label": "Fail", "variant": "dashed" },
    { "from": "build", "to": "deploy" }
  ]
}

Adding Approval Gates

Insert manual approval steps by adding a gate node on the appropriate lane:

{
  "id": "approval",
  "label": "Manual Approval",
  "laneId": "ops",
  "variant": "gate"
}

Add edges connecting the build step to the approval gate, then from the gate to deployment. The renderer automatically draws the diamond shape with the label centered inside.

CLI Rendering

Generate the final diagram using the Archify CLI:

node archify/bin/archify.mjs render workflow path/to/ci-workflow.json --output ci-pipeline.html

Open ci-pipeline.html in any browser to view the interactive diagram with theme controls and export options.

Summary

• Archify uses a JSON schema (archify/schemas/workflow.schema.json) to define CI/CD pipelines with strict validation, preventing malformed diagrams at build time.
• Lanes represent participants (Developer, CI, Production) while nodes represent stages (build, test, deploy) positioned via laneId assignments.
• Gate variants create diamond-shaped decision points for conditional logic like pass/fail checks or manual approvals.
• Exception lanes isolate error-handling paths to maintain clean visual flow in complex pipelines.
• The rendering pipeline (archify/renderers/workflow/render-workflow.mjs) produces self-contained HTML with automatic layout, orthogonal edge routing, and one-click export to multiple image formats.

Frequently Asked Questions

What file format does Archify use to define CI/CD pipelines?

Archify uses a JSON format defined by archify/schemas/workflow.schema.json. This schema requires three top-level arrays: lanes for participant tracks, nodes for pipeline stages, and edges for transitions between stages. The CLI validates your JSON against this schema before rendering.

How do I represent a manual approval step in an Archify CI/CD diagram?

Add a node with "variant": "gate" on the appropriate lane (typically Ops or Production). Connect incoming edges from the previous stage and outgoing edges to subsequent stages. The renderer draws this as a diamond shape with the label centered inside, following the pattern shown in archify/examples/agent-tool-call.workflow.json.

Can Archify export CI/CD diagrams to image formats?

Yes. The generated HTML file includes a built-in export button that produces PNG, JPEG, WebP, and SVG formats without external dependencies. The export functionality is implemented in archify/renderers/workflow/render-workflow.mjs and requires no additional tooling or internet connection.

Where is the schema validation defined for Archify workflow diagrams?

The JSON Schema defining lanes, nodes, edges, and special variants (gate, exception) lives in archify/schemas/workflow.schema.json. The CLI entry point at archify/bin/archify.mjs performs validation against this schema before invoking the renderer, ensuring type safety and required field compliance.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}