Archify's System Design Philosophy: Evidence-Driven Architecture Visualization

Archify treats architecture diagrams as precise technical instruments using a dark-first canvas, semantic color encoding, deterministic exports, and evidence-backed source linking rather than decorative drawings.

Archify's system design philosophy centers on transforming architecture diagrams from passive sketches into verifiable technical artifacts. According to the tt-a1i/archify repository, every visual element serves a functional purpose—whether encoding infrastructure semantics through color or linking nodes directly to source code. This approach prioritizes trust, clarity, and reproducibility through strict design rules and deterministic pipelines.

Core Tenets of the Design Philosophy

One Dominant Technical Canvas

The interface centers on a dark-first surface that presents the primary path before secondary details. As defined in DESIGN.md, the canvas carries one spatial narrative where restrained controls and progressive disclosure allow readers to move from the main flow to exact authored relationships. This ensures the diagram communicates hierarchy immediately without visual noise.

Semantic-Color Vocabulary

Every saturated color in Archify encodes specific infrastructure meaning—frontend, backend, database, security—rather than serving as mere decoration. The Semantic Color Rule in DESIGN.md explicitly states that "every saturated color maps to a node or relationship meaning; never add an accent merely to make a surface lively." This creates a precise visual system where color carries technical information.

Mono-Forward Typography

Archify utilizes a single monospace family (JetBrains Mono) with hierarchy expressed through weight, size, and spacing rather than mixing decorative fonts. According to the typography specifications in DESIGN.md, "a single mono family makes the artifact feel authored by an engineering instrument," reinforcing the tool's technical precision.

Deterministic, Portable Exports

The Canonical Clean Rule mandates that viewer state lives outside canonical exports, ensuring generated HTML, SVG, or WebM artifacts remain self-contained and free of transient UI artifacts. As documented in DESIGN.md under the Elevation section, "viewer state stays outside canonical exports; proof remains portable and deterministic." This guarantees that shared diagrams render identically regardless of the viewing environment.

Finite, Reader-Controlled Motion

Motion in Archify follows strict temporal and accessibility constraints. State transitions are limited to 140–200 milliseconds, always respect prefers-reduced-motion settings, and never introduce unauthored animation. While authored story motion may extend longer, it remains finite and reader-controlled, preventing motion-induced distraction or accessibility barriers.

Evidence-First Approach

Nodes can be marked with source beacons (SRC n) that link to verified code locations, grounding every interaction in actual implementation. As described in README.md under Truthful Interaction, "every interaction stays grounded… Source evidence, only when requested." This allows diagrams to function as navigable maps to the underlying codebase.

Layout Judgment Over Auto-Layout

Rather than relying on heuristic algorithms that clutter diagrams, Archify employs layout judgment where the agent decides hierarchy, spacing, routes, and emphasis. The README.md emphasizes that "layout judgment over generic auto-layout" ensures deterministic, intentional positioning rather than algorithmic noise.

Strict Design Rules

The philosophy enforces discipline through named rules including:

• Theme Parity Rule – Consistent behavior across light/dark modes
• Flat-at-Rest Rule – No elevation without interaction
• One Voice Rule – Unified communication tone

These constraints prevent visual noise and maintain the diagram's technical integrity.

Implementation in the Codebase

The Deterministic Pipeline

The CLI entry point at archify/bin/archify.mjs implements a strict generate → validate → preview → deliver pipeline. This ensures that every diagram passes through schema validation and semantic rule checking before export.

Typed JSON IR and Validation

The intermediate representation uses strictly typed JSON schemas defined in archify/schemas/README.md, ensuring reproducible, machine-checkable artifacts. The validation step fails fast if schema or semantic rules are broken, maintaining the philosophy of technical rigor.

Practical Workflow Example

# 1️⃣ Generate a minimal typed JSON IR for a three‑node flow

cat > example.json <<'EOF'
{
  "meta": { "locale": "en", "visual_preset": "signal-flow" },
  "nodes": [
    { "id": "browser", "label": "Browser", "type": "frontend" },
    { "id": "api",     "label": "API",     "type": "backend" },
    { "id": "db",      "label": "Postgres", "type": "database" }
  ],
  "edges": [
    { "source": "browser", "target": "api", "label": "HTTP" },
    { "source": "api",     "target": "db",  "label": "SQL" }
  ]
}
EOF

# 2️⃣ Validate the source (fails fast if schema or semantic rules are broken)

node archify/bin/archify.mjs validate architecture example.json --json

# 3️⃣ Render a deterministic HTML artifact

node archify/bin/archify.mjs deliver architecture example.json out.html --open

These commands demonstrate typed JSON IR, schema validation, and deterministic delivery—all core to Archify's evidence-driven approach.

Agent Skill Contracts

The archify/SKILL.md file formalizes the interaction contract for agents, defining precise commands, metadata requirements, and validation contracts. This ensures that automated agents respect the same strict design rules as human authors.

Summary

• Dark-first canvas prioritizes the primary spatial narrative with progressive disclosure of secondary details.
• Semantic colors encode infrastructure meaning (frontend, backend, database) and never serve decorative purposes.
• Deterministic exports remain self-contained and portable, with viewer state excluded from canonical artifacts.
• Evidence linking through SRC n beacons connects diagrams directly to verified source code.
• Finite motion respects accessibility via prefers-reduced-motion and strict 140–200ms transition limits.
• Layout judgment replaces heuristic auto-layout with intentional, agent-controlled hierarchy and spacing.
• Strict validation via JSON schemas and CLI pipelines ensures technical rigor before export.

Frequently Asked Questions

What distinguishes Archify from conventional diagramming tools?

Archify differs by treating diagrams as verifiable technical artifacts rather than drawings. While traditional tools focus on aesthetic flexibility, Archify enforces the Semantic Color Rule, Canonical Clean Rule, and evidence linking through source beacons. According to README.md, this ensures "every interaction stays grounded" in actual code rather than approximate illustrations.

How does Archify handle accessibility and motion preferences?

Archify implements finite, reader-controlled motion with transitions capped at 140–200 milliseconds and full support for prefers-reduced-motion. As specified in DESIGN.md, the system "never adds motion that isn't authored," ensuring diagrams remain accessible to users with vestibular disorders while preserving necessary state-transition feedback.

What is the Semantic Color Rule in Archify's design system?

The Semantic Color Rule mandates that every saturated color must map to a specific node type or relationship meaning—such as frontend (cyan), backend (purple), or database (green)—and prohibits decorative accents. This rule in DESIGN.md ensures the visual vocabulary remains a precise technical instrument where color carries infrastructure semantics rather than visual appeal.

How can architecture diagrams link directly to source code?

Archify supports source beacons marked as SRC n that nodes can carry to link directly to verified code locations. As implemented in the evidence-first approach described in README.md, these beacons allow readers to navigate from the visual diagram to the exact implementation, ensuring the architecture visualization remains synchronized with the actual system state.

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