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

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	Architecture	Validates components, services, databases, and their connections
workflow.schema.json	Workflow	Validates step-based process flows and decision branches
sequence.schema.json	Sequence	Validates lifelines, messages, and activation bars
dataflow.schema.json	Dataflow	Validates data sources, transformations, and sinks
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, 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

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	Architecture	Three-tier web application with load balancer, API servers, and database
agent-tool-call.workflow.json	Workflow	AI agent decision tree with tool invocations and error handling
cache-miss-request.sequence.json	Sequence	Distributed system interaction showing cache lookup failure and database fallback
product-analytics.dataflow.json	Dataflow	Event streaming pipeline from ingestion through transformation to warehouse
agent-run.lifecycle.json	Lifecycle	State machine for an autonomous agent from initialization to termination

Minimal Valid Architecture Configuration

{
  "$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 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:

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

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
2. Validates against 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 suffix suggested for architecture mode files
• .workflow.json suffix suggested for workflow mode files
• Similar patterns for .sequence.json, .dataflow.json, .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, workflow.schema.json, sequence.schema.json, dataflow.schema.json, and 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.

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