Archify Best Practices: A Complete Guide to System Mapping in AI Chat

Use the global skill installer, write bounded prompts for single diagram types, and always validate with --quality showcase before delivering artifacts.

Archify transforms codebase or system descriptions into polished, interactive system maps directly in chat. This guide covers the best practices for using Archify—from installation through delivery—based on the official tt-a1i/archify source code and documented workflows.

---

Installation Best Practices

Start with the right setup to avoid version drift and guarantee reproducibility.

Global Skill Installation

For most users, install once globally:

npx skills add tt-a1i/archify -g

This ensures you receive the latest stable version (v2.13.0) and avoids per-project dependency management overhead.

CI/Reproducible Environments

For automated pipelines or teams needing version stability:

# Pin to specific version in CI

npx skills use tt-a1i/archify@archify

Version pinning prevents accidental upgrades that could change diagram semantics between builds.

---

Prompt Design: The Bounded View Principle

The most effective Archify best practice is constraint. The agent performs best when given focused, single-purpose requests.

What to Request

Element	Best Practice
Diagram scope	One bounded view: core components, primary path, or external dependencies
Diagram type	Single type matching your review goal (see below)
Supporting details	Request these in "cards" (metadata panels) rather than additional edges

What to Avoid

• Multi-diagram requests in a single prompt
• Vague scopes like "show me everything"
• Implicit dependencies without explicit naming

Example bounded prompt:

"Show a runtime architecture with web app, API, Redis, and Postgres. Include owner and region details in cards."

This approach reduces hallucination and produces concise, reviewable artifacts according to the README's Ask for one bounded view guidance.

---

Choosing the Right Diagram Type

Archify provides five typed schemas, each with tailored validation and visual presets. Selecting correctly ensures semantic correctness:

Type	Use When	Schema Location
Architecture	Component-level system overview	archify/schemas/architecture.json
Workflow	CI/CD pipelines or procedural steps	archify/schemas/workflow.json
Sequence	Call-order tracing through components	archify/schemas/sequence.json
Data Flow	Data lineage and PII boundary mapping	archify/schemas/dataflow.json
Lifecycle	State-machine views of resources	archify/schemas/lifecycle.json

Each schema drives validation rules. Architecture diagrams enforce hierarchical containment; Sequence diagrams validate message ordering. Match your review goal to the type for automatic semantic enforcement.

---

The Validate-First Workflow

Never deliver without validation. Archify's validation engine catches schema violations and layout errors before rendering.

Validation Command Structure

node archify/bin/archify.mjs validate <type> <json> --quality showcase --json

Quality Levels

Level	Use Case
draft	Rapid iteration, internal brainstorming
review	Team review cycles
showcase	Published documentation, READMEs, release notes

Handling Validation Failures

Failures emit a single JSON receipt with supportedFixes. Programmatically address these before proceeding:

# Example: validate and capture fixes

node archify/bin/archify.mjs validate architecture arch.json --quality showcase --json > validation.json

# Review diagnostics, then apply suggested fixes

cat validation.json | jq '.supportedFixes'

Validation guarantees atomic artifacts that pass all schema and layout checks.

---

Iterative Refinement in Chat

After initial generation, refine diagrams with targeted, surgical requests.

How it works: The typed JSON IR (Intermediate Representation) remains unchanged except for explicitly requested modifications. This stability prevents cascading rewrites.

Effective refinement examples:

• "Add a Redis cache layer between Web App and API"
• "Move the Auth service left of the Gateway"
• "Surface the database connection pool size in the Postgres card"

The agent regenerates only the affected subgraph, preserves layout stability, and re-validates automatically.

---

Preview and Delivery

Local Preview (Optional)

Run a desktop loop that refreshes only on successful validation:

node archify/bin/archify.mjs preview architecture arch.json /tmp/arch.html --quality showcase

Use this for rapid visual iteration before final delivery.

Final Delivery

Produce deterministic, atomic artifacts:

node archify/bin/archify.mjs deliver architecture arch.json /tmp/arch.html --quality showcase --open --json

The --open flag launches the viewer; omit for CI pipelines. Delivery performs atomic file replacement—no partial writes.

---

Export and Sharing Best Practices

Archify provides purpose-built export options rather than screenshots:

Export Method	Dimensions	Best For
Copy Share Card	1200 × 630	READMEs, release notes, social posts
Route Share Card	Variable	Path-specific deep links
Reach Share Card	Variable	Component reachability analysis

Access via the viewer: press E → select export type. These renders retain full diagram context and interactivity metadata.

Avoid ambiguous screenshots—use the canonical export formats for professional documentation.

---

Optional: Deployment Ownership Profile

Enable strict production safety checks:

# Enable when reviewing production deployments

archify guide "..." --profile deployment-ownership

This profile enforces:

• Owner attribution on all components
• Region specification
• Boundary validation

It fails closed on missing data—never silently enabled. Use for release-engineered reviews where accountability is critical.

---

Local Debugging Commands

Verify environment health before committing artifacts:

# Check dependencies and environment

node archify/bin/archify.mjs doctor

# Generate sandbox demo for experimentation

node archify/bin/archify.mjs demo /tmp/demo-output

Run these in archify/bin/archify.mjs when troubleshooting integration issues.

---

Complete Workflow Example

# 1. Install (once)

npx skills add tt-a1i/archify -g

# 2. Generate from natural language

archify mjs guide "Show a runtime architecture with web app, API, Redis, and Postgres" --json > arch.json

# 3. Validate to showcase quality

node archify/bin/archify.mjs validate architecture arch.json --quality showcase --json

# 4. Preview locally

node archify/bin/archify.mjs preview architecture arch.json /tmp/arch.html --quality showcase

# 5. Deliver final artifact

node archify/bin/archify.mjs deliver architecture arch.json /tmp/arch.html --quality showcase --open --json

---

Summary

• Install globally with npx skills add tt-a1i/archify -g; pin versions in CI for reproducibility
• Write bounded prompts requesting single diagram types with clear scope and card-based details
• Choose diagram types that match your review goal—each enforces different semantic rules through dedicated schemas in archify/schemas/
• Validate before delivery using --quality showcase to guarantee atomic, polished artifacts
• Refine iteratively in chat—the typed IR enables surgical updates without cascading changes
• Export correctly using Share Cards (1200×630) for documentation, not screenshots
• Enable deployment-ownership for production reviews requiring strict accountability

---

Frequently Asked Questions

How do I install Archify for team use?

Use the global installer (npx skills add tt-a1i/archify -g) for development machines. For CI/CD pipelines, pin the version with npx skills use tt-a1i/archify@archify to prevent unexpected behavior changes between builds.

What makes a good Archify prompt?

A good prompt requests one bounded view with explicit scope (e.g., "runtime architecture of core services"), specifies the diagram type, and asks for supporting details in cards rather than additional diagram elements. This reduces agent hallucination and produces reviewable artifacts.

Why does validation fail even when my diagram looks correct?

Archify validates against typed schemas in archify/schemas/—not just visual appearance. Common failures include missing required node attributes, invalid edge references, or layout constraints violated at the specified quality level. The validation output includes supportedFixes for programmatic remediation.

When should I use the deployment-ownership profile?

Enable this profile when reviewing production systems where accountability is mandatory. It enforces owner, region, and boundary fields on all components and fails validation if any are missing—providing a safety gate for release-engineered reviews.

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