# Modular Architecture of Archify: A Deep Dive Into Its Skill-Based Design

> Explore Archify's modular architecture. Discover its skill-based design, layered components, and typed JSON contracts for seamless AI agent integration.

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

---

**Archify is built as a modular, self-contained skill with clear functional boundaries organized into layers—skill metadata, CLI, schemas, renderers, validators, examples, and tests—where each layer communicates through typed JSON contracts to enable drop-in deployment across AI-agent environments.**

The modular architecture of Archify makes it instantly portable. You can embed the same codebase into Cursor, Claude Code, Codex CLI, OpenCode, or any other agent runtime without modification. Every component lives in its own directory with explicit boundaries, making the project easy to understand, extend, and maintain.

## High-Level Architectural Layers

Archify organizes its source tree around seven distinct layers. Each layer has a single responsibility and exposes data only through well-defined JSON interfaces.

| Layer | Purpose | Key Locations |
|-------|---------|---------------|
| **Skill metadata** | Describes capabilities to host agents and declares the public entry point | [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) |
| **CLI / binary** | Command-line driver for generation, validation, preview, and delivery | `archify/bin/archify.mjs` |
| **Core package** | Node package that aggregates runtime dependencies | [`archify/package.json`](https://github.com/tt-a1i/archify/blob/main/archify/package.json) |
| **Schemas** | Typed JSON contracts for all diagram types and shared definitions | [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json), [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) |
| **Renderers** | Pure-JS modules that transform validated JSON IR into HTML/SVG/PNG/WebM | `archify/renderers/architecture/render-architecture.mjs`, `archify/renderers/workflow/render-workflow.mjs`, `archify/renderers/lifecycle/render-lifecycle.mjs` |
| **Validators & Generators** | Auto-generation of validators and render-output verification | `archify/scripts/generate-validators.mjs`, `archify/scripts/check-render-output.mjs` |
| **Examples & Tests** | Runnable scenarios and comprehensive test coverage | [`archify/examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.architecture.json), `archify/test/architecture-delta.test.mjs` |

The **contract-first approach** means no layer imports implementation details from another. A diagram description can be validated, rendered, and exchanged without hidden runtime coupling.

## Skill Metadata and Host Integration

The [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) file serves as the skill descriptor. It tells host agents which commands are available, which visual presets are supported, and which **engineering profiles** (such as `deployment-ownership`) can be activated. This file is referenced by every installer script and parsed by agent runtimes to surface Archify capabilities in their UI.

Because the skill metadata is decoupled from the implementation, you can upgrade the renderer logic without changing how agents discover the skill.

## CLI Entry Point: `bin/archify.mjs`

The CLI in `archify/bin/archify.mjs` is intentionally thin. It parses sub-commands—`generate`, `validate`, `preview`, `deliver`, `guide`—then delegates to specialized modules. The CLI also provides workflow shortcuts:

```bash
node archify/bin/archify.mjs guide "Show API request"

```

This design keeps the command surface small while allowing deep functionality through composition.

## Schema Layer: Typed JSON Contracts

All diagram types share a **common schema** defined in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json). This foundation includes reusable concepts: component IDs, coordinate points, legend entries, and metadata fields.

Each diagram type extends this base with domain-specific structures:

- **[`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json)** — components, boundaries, connections, and cards
- **[`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json)** — steps, branches, and actions
- **[`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json)** — states, events, and retry logic
- **[`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json)** — sources, transforms, and sinks

Schemas feed directly into the validation pipeline. The script `archify/scripts/generate-validators.mjs` walks the schema directory, emits tiny validator modules, and registers them at runtime. This auto-generation guarantees that validators never drift from the source of truth.

## Renderer Architecture: Pure Functions for Each Diagram Type

Renderers live in `archify/renderers/` as self-contained modules. Each accepts a **validated JSON IR** and returns a **self-contained HTML artifact** with all assets embedded for offline use.

The **architecture renderer** (`archify/renderers/architecture/render-architecture.mjs`) implements grid layouts and visual presets. The **workflow renderer** (`archify/renderers/workflow/render-workflow.mjs`) specializes in sequencing flows. The **lifecycle renderer** (`archify/renderers/lifecycle/render-lifecycle.mjs`) handles state-machine visualization.

All renderers are **pure functions with no side effects**. This makes them safe to execute in sandboxed environments and trivial to unit test.

## Validators, Build Scripts, and Determinism

Two scripts guarantee output quality:

- **`generate-validators.mjs`** — creates runtime validators from JSON-Schema definitions
- **`check-render-output.mjs`** — runs deterministic checks on generated HTML (exact IDs, layout dimensions, export format correctness)

These scripts enforce that every render produces byte-identical output given identical input, which is essential for snapshot testing and reproducible documentation.

## Examples, Recipes, and Scenario Building

The `examples/` directory contains ready-made JSON descriptions: web applications, cache-miss sequences, deployment-ownership reviews. These serve as both documentation and integration tests.

For programmatic composition, `recipes/scenarios.mjs` assembles complex diagrams from reusable building blocks. This lets teams standardize visual conventions across multiple architecture documents.

## Test Suite as Living Documentation

The `test/` directory contains **over 30 test files** covering every public API, schema validation, renderer output, CLI behavior, and edge case. Notable tests include:

- `archify/test/architecture-delta.test.mjs` — verifies diffing between architecture versions
- Motion governor validation
- Legend contract enforcement
- Route-share-card generation

Tests use native Node `assert` and run via `npm test`. They document the modular design by demonstrating how layers interact through their contracts.

## Practical Usage: Generating and Rendering Diagrams

### Basic architecture diagram generation

```bash

# Create a minimal JSON description

cat > web-app.architecture.json <<'EOF'
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Web App", "visual_preset": "signal-flow" },
  "components": [
    { "id": "frontend", "type": "frontend", "label": "Browser" },
    { "id": "api",      "type": "backend",  "label": "API Server" },
    { "id": "db",       "type": "database", "label": "PostgreSQL" }
  ],
  "connections": [
    { "from": "frontend", "to": "api" },
    { "from": "api",      "to": "db" }
  ]
}
EOF

# Render to self-contained HTML

node archify/bin/archify.mjs render architecture web-app.architecture.json web-app.html

```

The command validates against [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) before rendering, guaranteeing that malformed input never produces broken output.

### Live preview with validation

```bash
node archify/bin/archify.mjs preview architecture web-app.architecture.json --open

```

Preview mode watches the source file, re-validates on every edit, and updates the display only when validation passes.

### Extending with custom presets

```javascript
// archify/renderers/architecture/custom-preset.mjs
import { renderArchitecture } from "./render-architecture.mjs";

export default function renderCustom(ir) {
  ir.meta.visual_preset = "editorial";
  return renderArchitecture(ir);
}

```

Register in [`archify/package.json`](https://github.com/tt-a1i/archify/blob/main/archify/package.json) under `"archify.renderers"` and invoke:

```bash
node archify/bin/archify.mjs render architecture --renderer custom-preset my-diagram.json out.html

```

## Key Source Files in the Modular Architecture

| File | Role |
|------|------|
| [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) | Skill descriptor for host agents |
| [`archify/package.json`](https://github.com/tt-a1i/archify/blob/main/archify/package.json) | Package metadata and renderer registration |
| `archify/bin/archify.mjs` | CLI orchestration (generate, validate, preview, deliver) |
| [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) | Shared schema definitions |
| [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) | Architecture diagram contract |
| `archify/renderers/architecture/render-architecture.mjs` | Core architecture renderer |
| `archify/renderers/workflow/render-workflow.mjs` | Workflow diagram renderer |
| `archify/renderers/lifecycle/render-lifecycle.mjs` | Lifecycle diagram renderer |
| `archify/scripts/generate-validators.mjs` | Auto-generator for validators |
| [`archify/examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.architecture.json) | Reference implementation example |

These files illustrate how Archify achieves portability: a thin CLI layer, strict JSON-Schema contracts, independent renderers, auto-generated validators, and comprehensive tests.

## Summary

- **Modular architecture** enables Archify to function as a drop-in skill across multiple AI-agent environments
- **Seven distinct layers** (metadata, CLI, schemas, renderers, validators, examples, tests) each own a single responsibility
- **Contract-first design** uses [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) and per-diagram schemas to eliminate runtime coupling
- **Pure-function renderers** in `archify/renderers/` produce self-contained HTML artifacts with no side effects
- **Auto-generated validators** guarantee that schemas and validation logic stay synchronized
- **Over 30 test files** act as executable documentation for every module boundary

## Frequently Asked Questions

### What makes Archify "modular" compared to other diagramming tools?

Archify's modular architecture separates every concern into an independent layer that communicates only through typed JSON contracts. The CLI, schemas, renderers, and validators can be updated, replaced, or tested in isolation. This contrasts with monolithic tools where parsing, validation, and rendering are tightly coupled.

### Can I use Archify renderers without the CLI?

Yes. The renderers in `archify/renderers/` are pure JavaScript functions that accept validated JSON and return HTML strings. You can import `renderArchitecture`, `renderWorkflow`, or `renderLifecycle` directly into any Node.js application or browser bundle without pulling in the CLI or file-system dependencies.

### How does the schema layer prevent breaking changes?

All diagram types extend [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json), which defines stable concepts like component IDs and coordinate points. The `generate-validators.mjs` script regenerates runtime validators from these schemas, ensuring that any schema change immediately propagates to validation logic. Tests verify that existing examples still pass validation after updates.

### Is it possible to add custom diagram types to Archify?

Yes. Create a new schema in `archify/schemas/`, a matching renderer in `archify/renderers/`, and register both in [`package.json`](https://github.com/tt-a1i/archify/blob/main/package.json). The CLI discovers renderers dynamically through the `"archify.renderers"` configuration key, so no changes to `bin/archify.mjs` are required. The existing test patterns in `archify/test/` provide templates for validating new diagram types.