Archify Documentation Structure: A Complete Guide to the Repository Layout

The Archify documentation follows a hierarchical organization spanning root-level project files, user guides in docs/, technical schemas in archify/schemas/, renderer documentation in archify/renderers/, and operational guides at the repository root.

The tt-a1i/archify repository maintains a comprehensive documentation structure that separates high-level project information from deep technical implementation details. Understanding this documentation structure for Archify helps developers quickly locate schema definitions, usage examples, and contribution guidelines. The layout follows a logical progression from introductory materials to specialized renderer documentation and research artifacts.

Root-Level Project Documentation

The repository root contains the primary entry points for understanding the project scope and getting started quickly.

README.md serves as the main project overview, providing installation commands, supported agent compatibility, and core concept explanations. This file includes quick-start instructions such as:

npx skills add tt-a1i/archify -g

ROADMAP.md and DESIGN.md contain future development plans and architectural rationale, while CONTRIBUTING.md establishes coding standards and issue templates for contributors. Version history and licensing information reside in CHANGELOG.md and LICENSE, respectively.

User Guides and Articles

The docs/ directory houses detailed user-facing documentation and research materials.

docs/article-archify.md provides a comprehensive article describing Archify's capabilities, use cases, and feature set. This file offers the most complete narrative documentation for understanding what the tool accomplishes.

Research and design experiments occupy separate markdown files following naming conventions like research-visual-evolution-round-9.md. These files document ongoing visual design decisions, experimental features, and iterative improvements to the diagram generation algorithms.

Technical Schema Reference

Deep technical documentation resides in archify/schemas/README.md, which defines the formal JSON Intermediate Representation (IR) for all supported diagram types. According to the archify source code, this directory contains schema definitions for architecture, workflow, sequence, data-flow, and lifecycle diagrams.

The schema reference documentation specifies validation rules, property types, and relationships between diagram elements. Developers integrating with Archify's JSON IR should consult this location first when building custom diagram generators or validators.

Renderer Documentation

Each diagram type maintains dedicated documentation within the renderer subdirectories at archify/renderers/*/README.md.

archify/renderers/workflow/README.md documents the workflow diagram renderer implementation, explaining how the system processes workflow JSON IR into visual outputs. Similar README files exist for:

• archify/renderers/architecture/README.md
• archify/renderers/sequence/README.md
• archify/renderers/dataflow/README.md
• archify/renderers/lifecycle/README.md

These files contain renderer-specific parameters, styling options, and implementation notes that differ between diagram types.

Skill Contract and Runtime Configuration

archify/SKILL.md defines the complete contract for the Archify skill, including metadata specifications, runtime expectations, and delivery parameters. This file is essential for understanding how Archify integrates with agent systems and what constraints govern its execution environment.

Implementation Examples and Tests

Practical usage examples live in the examples/ directory, containing ready-to-run HTML demos and their corresponding JSON source files. examples/web-app.html demonstrates the interactive viewer capabilities, while accompanying .json files provide sample diagram data for testing different rendering modes.

The archify/test/ directory contains the automated test suite, including archify/test/visual-check.test.mjs, which validates rendering output, schema compliance, and visual regression.

Command-Line Documentation

The CLI tools support self-documenting help flags, but key commands are demonstrated in the primary documentation:

# Generate a high-level architecture diagram for the current repo

archify bin/archify.mjs guide "Show the runtime architecture of this repo"

# Validate a workflow JSON file with showcase quality standards

node archify/bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json \
    --quality showcase --json

Summary

• Root documentation (README.md, CONTRIBUTING.md, ROADMAP.md) provides project overview and contribution guidelines
• docs/article-archify.md contains the comprehensive user guide and feature descriptions
• archify/schemas/README.md defines the formal JSON IR specifications for all diagram types
• Renderer-specific READMEs in archify/renderers/*/README.md document implementation details for each diagram type
• archify/SKILL.md specifies the runtime contract and skill metadata
• examples/ and archify/test/ provide working code samples and validation suites

Frequently Asked Questions

Where is the main project overview located in the Archify repository?

The primary project overview resides in README.md at the repository root. This file contains installation instructions, quick-start commands using npx skills add, and high-level explanations of supported diagram types and agents.

How are the JSON IR schemas documented?

Schema documentation is centralized in archify/schemas/README.md, which defines the intermediate representation structure for architecture, workflow, sequence, data-flow, and lifecycle diagrams. This file serves as the authoritative reference for schema validation and JSON structure requirements.

What is the purpose of the SKILL.md file?

archify/SKILL.md contains the complete skill contract specifying runtime expectations, metadata requirements, and delivery constraints for the Archify skill system. It defines how the tool integrates with agent frameworks and what operational parameters govern execution.

Where can I find working examples of Archify diagrams?

Working examples are located in the examples/ directory, which contains HTML viewer demonstrations like web-app.html alongside their corresponding JSON source files. The archify/test/ directory also provides test cases that demonstrate valid diagram configurations and rendering outputs.

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