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

> Master Archify best practices for effective AI system mapping. Learn to use the global skill installer, craft bounded prompts, and validate with quality showcase for flawless AI chat diagrams. Get the complete guide.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: best-practices
- Published: 2026-08-11

---

**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:

```bash
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:

```bash

# 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](https://github.com/tt-a1i/archify/blob/main/README.md#1-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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.json) |
| **Workflow** | CI/CD pipelines or procedural steps | [`archify/schemas/workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.json) |
| **Sequence** | Call-order tracing through components | [`archify/schemas/sequence.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.json) |
| **Data Flow** | Data lineage and PII boundary mapping | [`archify/schemas/dataflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.json) |
| **Lifecycle** | State-machine views of resources | [`archify/schemas/lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/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

```bash
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:

```bash

# 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:

```bash
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:

```bash
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:

```bash

# 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:

```bash

# 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

```bash

# 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.