# How the Archify Pipeline Handles Errors During Validation: Structured Diagnostics Deep Dive

> Discover how the Archify pipeline transforms validation failures into structured JSON diagnostics, offering clear remediation steps for deterministic error handling. Learn more about this powerful feature.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-30

---

**The Archify validation pipeline converts every failure—from JSON syntax errors to composition violations—into a structured, machine-readable JSON receipt with precise remediation steps, ensuring deterministic error handling instead of raw Node.js stack traces.**

The `tt-a1i/archify` repository validates diagram specifications through a deterministic pipeline that captures failures at three distinct stages: input parsing, renderer execution, and artifact verification. Understanding how the Archify pipeline handles errors during validation is essential for integrating the tool into CI/CD workflows and building automated remediation systems.

## The Six-Stage Validation Pipeline

The `commandValidate` function in `archify/bin/archify.mjs` orchestrates a strict sequence that transforms runtime exceptions into reproducible diagnostic reports.

### 1. Argument Parsing and Environment Setup

The pipeline begins by extracting the `--json` and `--layout-json` flags from the command line, then isolates the diagram **type** (e.g., `architecture`, `workflow`) and **input** file path. It sets the environment variable `ARCHIFY_DIAGNOSTIC_FORMAT=json` to force all subprocesses to emit structured diagnostics rather than human-readable text.

### 2. Renderer Invocation

Archify invokes the type-specific renderer (such as `render-architecture.mjs`) as a subprocess. The renderer validates the input JSON against schemas defined in `renderers/shared/generated-validators.mjs` before attempting to generate the diagram.

### 3. Renderer Failure Processing

When a renderer exits with a non-zero status, the `rendererFailure()` function (lines 41-70 in `archify/bin/archify.mjs`) captures the JSON payload from **stderr**. If stderr contains no parseable JSON, the function falls back to a generic internal error. It constructs a list of **diagnostic** objects containing:

- **`code`**: A machine-stable identifier (e.g., `input/json-parse`, `render/layout-failed`)
- **`message`**: A human-readable description of the failure
- **`subject`**: The object reference (e.g., `{ input: 'diagram.json' }`)
- **`evidence`**: Additional context such as system error codes or parsing locations
- **`supportedFixes`**: An array of precise remediation instructions

```javascript
// archify/bin/archify.mjs – renderer failure processing
function rendererFailure(result) { … }

```

### 4. Artifact Verification

On successful render, Archify executes `scripts/check-render-output.mjs` to validate the generated HTML/SVG against layout and composition rules (e.g., label clearance, minimum distances, edge crossings). When this checker fails, the `checkerDiagnostics()` function transforms its JSON receipt into standardized diagnostic entries.

```javascript
const check = runNode([path.join(skillRoot, 'scripts/check-render-output.mjs'), out], { stdio: 'pipe' });
// … if check.status !== 0 → reportValidateFailure({ …, stage: 'check', diagnostics: checkerDiagnostics(checker) })

```

### 5. Unified Error Reporting

The `reportValidateFailure()` function (lines 30-35 in `archify/bin/archify.mjs`) wraps all failure contexts into a unified JSON receipt by calling `reportArtifactFailure()` with the `command: 'validate'` option. This receipt includes:

- `command`: Always set to `'validate'`
- `stage`: One of `input`, `render`, or `check`
- `error`: The original error message string
- `diagnostics[]`: The complete array of diagnostic objects
- `status`: The original exit code from the renderer or checker

```javascript
// archify/bin/archify.mjs – validation error wrapper
function reportValidateFailure(options) {
  reportArtifactFailure({ ...options, command: 'validate' });
}

```

### 6. Exit Code Propagation

After the validation block completes, Archify assigns the renderer or checker's exit status to `process.exitCode`. This guarantees that any validation failure results in a non-zero exit code, making the tool compatible with standard Unix pipeline conventions and CI/CD failure detection.

## The Diagnostic Schema

Every validation error follows a consistent schema designed for automated parsing. The **diagnostic** objects included in the `diagnostics` array contain:

- **`code`**: Machine-stable identifier (examples: `input/json-parse`, `artifact/check-failed`, `composition/proper-crossing`)
- **`severity`**: Typically `error` for validation failures
- **`message`**: Human-readable description suitable for console output
- **`subject`**: The specific entity the diagnostic refers to, such as `{ input: 'diagram.json' }` or `{ relationship: 'edge-123' }`
- **`evidence`**: Contextual data including system error codes, file paths, or parsing tokens
- **`supportedFixes`**: Actionable remediation steps (e.g., "repair the JSON syntax and run validation again")

## Practical Validation Examples

### Successful Validation

```bash
archify validate architecture examples/web-app.architecture.json --json

```

Returns a receipt with `ok: true` and an empty or passed-checks diagnostics array.

### Input Syntax Error

```bash
archify validate workflow bad.json --json

```

Produces a structured receipt identifying the parse failure:

```json
{
  "schemaVersion": 1,
  "ok": false,
  "command": "validate",
  "stage": "input",
  "type": "workflow",
  "input": "/path/bad.json",
  "error": "Input JSON could not be parsed: Unexpected token ...",
  "diagnostics": [
    {
      "code": "input/json-parse",
      "severity": "error",
      "message": "Input JSON could not be parsed: Unexpected token ...",
      "subject": {"input": "/path/bad.json"},
      "evidence": {"reason": "Unexpected token ..."},
      "supportedFixes": ["repair the JSON syntax and run validation again"]
    }
  ]
}

```

### Renderer Failure (Missing Field)

```bash
archify validate architecture missing-field.json

```

Console output shows the error message, while the internal pipeline captures structured diagnostics via `rendererFailure()`.

### Composition Check Failure

```bash
archify validate architecture overlapping.json --json

```

Returns diagnostics for layout violations:

```json
{
  "code": "composition/proper-crossing",
  "severity": "error",
  "message": "Final artifact failed composition/proper-crossing.",
  "subject": {"relationship": "edge-123"},
  "evidence": {"details": ["Edge crosses another relationship"]},
  "supportedFixes": ["adjust route/via or channel coordinates so unrelated relationships use separate corridors"]
}

```

## Summary

- **Renderer crash handling** via `rendererFailure()` in `archify/bin/archify.mjs` parses JSON from stderr or falls back to generic errors, ensuring no raw stack traces escape.
- **Artifact verification** through `scripts/check-render-output.mjs` catches layout and composition violations, converting them via `checkerDiagnostics()` into the standard schema.
- **Unified reporting** by `reportValidateFailure()` produces consistent JSON receipts with `ok: false`, explicit `stage` indicators (`input`, `render`, `check`), and full diagnostic arrays.
- **CI/CD compatibility** is guaranteed by setting `process.exitCode` to the subprocess exit status, ensuring reliable failure detection in automated pipelines.
- **Machine-consumable output** through the `ARCHIFY_DIAGNOSTIC_FORMAT=json` environment variable enables automated agents to implement self-healing workflows based on `code` and `supportedFixes` values.

## Frequently Asked Questions

### What is the structure of an Archify validation error receipt?

Archify validation error receipts follow a standardized JSON object containing `schemaVersion`, `ok: false`, the `command` name (`validate`), the failure `stage` (`input`, `render`, or `check`), the diagram `type`, the `input` file path, an `error` message string, and a `diagnostics` array. Each diagnostic includes `code`, `severity`, `message`, `subject`, `evidence`, and `supportedFixes` fields to enable programmatic error handling and automated remediation.

### How does Archify differentiate between renderer crashes and validation logic errors?

Renderer crashes are captured by the `rendererFailure()` function in `archify/bin/archify.mjs`, which attempts to parse structured JSON from the renderer's stderr stream. If parsing fails, it generates a generic internal error diagnostic. Validation logic errors—such as schema violations from `renderers/shared/generated-validators.mjs` or composition failures from `scripts/check-render-output.mjs`—are generated as native JSON and forwarded through the same `reportValidateFailure()` pipeline, ensuring consistent formatting regardless of whether the error originated from a subprocess crash or a validation rule violation.

### What exit codes does Archify return when validation fails?

Archify propagates the exact exit code from the failing renderer or checker subprocess to `process.exitCode`. For example, if the architecture renderer exits with code 1 due to a JSON parse error, Archify exits with code 1. This direct propagation ensures that shell scripts and CI systems can detect failures through standard Unix exit code conventions without needing to parse the JSON output.

### How can automated tools programmatically respond to Archify validation errors?

Automated tools should invoke Archify with the `--json` flag and ensure `ARCHIFY_DIAGNOSTIC_FORMAT=json` is set. By parsing the resulting receipt's `diagnostics` array, tools can map the `code` field (e.g., `input/json-parse`, `composition/proper-crossing`) to specific remediation actions. The `supportedFixes` array provides human-readable guidance, while the `subject` and `evidence` fields provide the context needed to implement automatic fixes, enabling self-healing diagram generation workflows.