# Archify Configuration Files Explained: JSON Schemas, Examples, and Runtime Assets

> Discover Archify's declarative JSON configuration files for system diagrams. Learn about JSON Schemas, examples, and runtime assets without writing code.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: api-reference
- Published: 2026-08-13

---

**Archify uses declarative JSON configuration files validated against JSON-Schema definitions to describe system diagrams without requiring any code.**

Archify is a diagram-as-code tool where all configuration lives in structured JSON files rather than imperative scripts. This article maps the complete configuration ecosystem in the `tt-a1i/archify` repository, from schema contracts that enforce data integrity to ready-to-use example payloads and temporary runtime state.

## JSON-Schema Configuration Files in Archify

Archify's core validation layer consists of five schema definitions located in `archify/schemas/`. These files serve as the **canonical configuration contract**—every user-supplied JSON must conform to one of these schemas before the CLI will render anything.

| Schema file | Diagram mode | Purpose |
|-------------|--------------|---------|
| [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) | Architecture | Validates components, services, databases, and their connections |
| [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) | Workflow | Validates step-based process flows and decision branches |
| [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json) | Sequence | Validates lifelines, messages, and activation bars |
| [`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json) | Dataflow | Validates data sources, transformations, and sinks |
| [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json) | Lifecycle | Validates state transitions and temporal evolution |

The CLI loads these schemas at runtime to enforce correct field types, required properties, and enumerated values. For example, in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json), the `entities` array requires each object to have an `id`, `type`, and `label` property with specific string constraints.

### Validating a Configuration Against Archify's Schema

```javascript
import fs from 'fs';
import path from 'path';
import Ajv from 'ajv';

const schemaPath = path.join('archify', 'schemas', 'architecture.schema.json');
const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));

const ajv = new Ajv();
const validate = ajv.compile(schema);

const myConfig = JSON.parse(fs.readFileSync('my-architecture.json', 'utf8'));
if (!validate(myConfig)) {
  console.error('Configuration invalid:', validate.errors);
}

```

This approach mirrors how Archify's own CLI performs validation before generating any visual output.

## Example Configuration Files for Archify

The `archify/examples/` directory contains **starter kit configurations** that demonstrate valid JSON shapes for each diagram mode. These files are tested, documented, and safe to copy as templates.

| Example file | Mode | Demonstrates |
|--------------|------|--------------|
| [`web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/web-app.architecture.json) | Architecture | Three-tier web application with load balancer, API servers, and database |
| [`agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/agent-tool-call.workflow.json) | Workflow | AI agent decision tree with tool invocations and error handling |
| [`cache-miss-request.sequence.json`](https://github.com/tt-a1i/archify/blob/main/cache-miss-request.sequence.json) | Sequence | Distributed system interaction showing cache lookup failure and database fallback |
| [`product-analytics.dataflow.json`](https://github.com/tt-a1i/archify/blob/main/product-analytics.dataflow.json) | Dataflow | Event streaming pipeline from ingestion through transformation to warehouse |
| [`agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/agent-run.lifecycle.json) | Lifecycle | State machine for an autonomous agent from initialization to termination |

### Minimal Valid Architecture Configuration

```json
{
  "$schema": "https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json",
  "title": "Simple Service",
  "description": "A tiny web service with a database.",
  "entities": [
    { "id": "frontend", "type": "webapp", "label": "Frontend" },
    { "id": "backend",  "type": "service", "label": "API" },
    { "id": "db",       "type": "database", "label": "Postgres" }
  ],
  "relations": [
    { "source": "frontend", "target": "backend", "type": "http" },
    { "source": "backend",  "target": "db",      "type": "sql" }
  ]
}

```

Save this as [`my-architecture.json`](https://github.com/tt-a1i/archify/blob/main/my-architecture.json) and it will pass validation against the official schema.

## Runtime-Generated Archify Configuration Files

When executing CLI commands, Archify creates **temporary hidden directories** that store per-run state. These are not source-controlled but are essential to Archify's configuration lifecycle.

- **`.archify-preview-*`** directories: Created by `archify preview` to cache rendered images and diagnostic logs
- **`.archify-delivery-*`** directories: Created by `archify open-artifact` and related commands to stage build outputs

The test suite in `archify/test/preview.test.mjs` explicitly checks for these patterns:

```javascript
fs.readdirSync(tmp).filter(name => name.startsWith('.archify-preview-'))

```

These runtime files let users inspect intermediate state and debug rendering failures without affecting their source configurations.

## Working with Archify Configuration Files

### Using the CLI with Custom Configurations

```bash
npx -y skills add tt-a1i/archify --skill archify --copy --yes
archify preview my-architecture.json --mode blueprint

```

The CLI performs three operations:
1. Parses [`my-architecture.json`](https://github.com/tt-a1i/archify/blob/main/my-architecture.json)
2. Validates against [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json)
3. Renders output in the requested *blueprint* visual style

### Configuration File Patterns

Archify recognizes files by naming convention rather than extension enforcement:
- **[`.architecture.json`](https://github.com/tt-a1i/archify/blob/main/.architecture.json)** suffix suggested for architecture mode files
- **[`.workflow.json`](https://github.com/tt-a1i/archify/blob/main/.workflow.json)** suffix suggested for workflow mode files
- Similar patterns for [`.sequence.json`](https://github.com/tt-a1i/archify/blob/main/.sequence.json), [`.dataflow.json`](https://github.com/tt-a1i/archify/blob/main/.dataflow.json), [`.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/.lifecycle.json)

The `$schema` property in your JSON enables IDE autocomplete and validation even before running the CLI.

## Summary

- **Schema files** in `archify/schemas/` enforce data integrity across five diagram modes
- **Example files** in `archify/examples/` provide tested, documented starting points
- **Runtime directories** (`.archify-preview-*`, `.archify-delivery-*`) store execution state without polluting source control
- All configuration is **declarative JSON**—no code required to generate diagrams
- Validation happens via **JSON-Schema** using the same rules in CLI and programmatic usage

## Frequently Asked Questions

### Where are Archify's configuration schemas stored?

The schemas live in `archify/schemas/` at the repository root. Each diagram mode has its own file: [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json), [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json), [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json), [`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json), and [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json).

### Can I write Archify configurations without using the CLI?

Yes. Archify configurations are plain JSON files. You can author them in any editor, validate them with standard JSON-Schema tools like Ajv, and only invoke the CLI when ready to render. The schemas include `$id` references for IDE support.

### What happens if my configuration fails validation?

The CLI reports schema violations with specific path and constraint information, then exits without generating output. Fix the reported fields—typically missing required properties, incorrect enum values, or type mismatches—and retry.

### Are the `.archify-*` hidden directories safe to delete?

Yes. These are ephemeral cache directories created during command execution. The test suite confirms they are regenerated as needed. Your source `.json` configuration files remain untouched.