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

> Learn how Archify diagrams visually represent CI/CD pipelines. Explore JSON schema, lanes, nodes, and edges for dynamic workflow visualization direct from your code.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-07-15

---

**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`](https://github.com/tt-a1i/archify/blob/main/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:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json) demonstrates this pattern with nodes for "pull request", "tests", "approval", and "build image".

```json
{
  "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.

```json
{
  "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.

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

```

Connect multiple outgoing edges to create branching logic:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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:

```json
{
  "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:

```json
{
  "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:

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

```

Open [`ci-pipeline.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.