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

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
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
Schemas	Typed JSON contracts for all diagram types and shared definitions	archify/schemas/architecture.schema.json, 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, 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 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:

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. 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 — components, boundaries, connections, and cards
• workflow.schema.json — steps, branches, and actions
• lifecycle.schema.json — states, events, and retry logic
• 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

# 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 before rendering, guaranteeing that malformed input never produces broken output.

Live preview with validation

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

// 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 under "archify.renderers" and invoke:

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	Skill descriptor for host agents
archify/package.json	Package metadata and renderer registration
archify/bin/archify.mjs	CLI orchestration (generate, validate, preview, deliver)
archify/schemas/common.schema.json	Shared schema definitions
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	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 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, 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. 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.

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