Archify Authoring Invariants and Best Practices: The Complete Guide

Archify enforces strict authoring invariants and a fast-authorship workflow to guarantee deterministic, validated diagrams that pass 9-point quality checks with zero composition errors.

The Archify diagramming system from tt-a1i/archify is built around immutable geometric and structural constraints. These authoring invariants prevent ambiguous topologies, while the fast-authoring workflow provides a bounded, iterative path from concept to delivery. This guide covers the core rules, the step-by-step practice, and the geometry that ties them together.

Core Authoring Invariants

Archify's invariants are non-negotiable constraints defined in archify/SKILL.md (lines 61-70) and enforced by the validator. Violations result in immediate rejection with diagnostic receipts.

Topology Invariants

• One obvious main path — Side branches must attach to the nearest main-path node, creating clear visual hierarchy.
• No meta.legend unless custom — The default auto legend is truthful and sufficient; manual legends require deliberate justification.
• Fixed component enums — Types and variants are restricted to schema-defined values. See archify/references/authoring-contract.md (lines 9-11) for the complete list:
  • Types: frontend, backend, database, cloud, security, messagebus, external
  • Variants: default, emphasis, security, dashed

Geometry Invariants

• Spacing is "clear gap" — Distance measurements are edge-to-edge, not center-to-center. Relationship labels require gaps larger than the label's mask width.
• Automatic routes own endpoint sides — First and last segments must leave and enter perpendicular to declared sides.
• Port-spread is automatic — Applied to architecture, workflow, dataflow, and lifecycle diagrams; disabled for explicit routes using via or channelX.
• No edge crossing opaque nodes — The renderer rejects any geometry where edges cross unrelated nodes or run collinearly along container borders.

These invariants are validated against the "showcase" quality profile, which runs 9 artifact checks with zero tolerance for warnings.

Fast-Authoring Workflow (Best Practices)

The recommended workflow in archify/SKILL.md (lines 15-30) minimizes rework through early, frequent validation.

Step 1: Select Diagram Type and Schema

Choose from: architecture, workflow, sequence, dataflow, lifecycle.

Reference the matching schema in archify/schemas/ and one example from archify/examples/. Use examples only for field shapes—author fresh IDs, wording, and facts.

Step 2: Create Candidate JSON

Start constrained:

• Single clear main path
• ≤ 12 primary nodes
• Automatic routing preferred
• meta.quality_profile set to "showcase" unless "standard" density is explicitly requested

Step 3: Validate Immediately After Each Edit

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

A passing "showcase" validation reports all 9 artifact checks with zero composition errors.

Step 4: Iterate on Diagnosed Subjects Only

When diagnostics appear, examine diagnostics[].subject and apply one supportedFix at a time (e.g., labelAt, via). Never guess multiple fixes simultaneously.

Step 5: Deliver Final Output

node bin/archify.mjs deliver <type> candidate.json output.html --quality showcase --json

Non-zero exit codes are never reported as success.

Step 6: Optional Live Preview Loop

node bin/archify.mjs preview <type> candidate.json output.html --quality showcase

The preview preserves the last verified artifact across failures.

Geometry and Layout Rules

The authoring contract in archify/references/authoring-contract.md specifies precise geometric calculations underlying the invariants.

Node Anchors and Routing

• Node anchors are side mid-points
• First and last segments must be perpendicular to entry/exit sides (lines 36-38)

Minimum Segment Lengths

• ≥ 8 px for any non-zero segment
• ≥ 16 px for interior segments (lines 39-40)

Label Clearance Rule

clear gap > label mask width + 8 px

This ensures labels remain legible without manual positioning (lines 48-54).

Diagnostic-Driven Repair Order

When validation fails, follow this sequence from the authoring contract (lines 58-65):

1. Meta-profile — Verify quality_profile and schema compliance
2. Node overlap — Resolve spatial collisions
3. Edge-through-node — Fix routes passing through unrelated nodes
4. Crossings — Minimize and clarify unavoidable intersections
5. Label clearance — Adjust gaps for readability

Each diagnostic includes code, subject, evidence, and supportedFixes for targeted repair.

Complete Authoring Example

# Install the skill (once)

npx skills add tt-a1i/archify -g

# Copy starter example

cp archify/examples/web-app.json my-diagram.json

# Edit my-diagram.json following invariants:

#   - One main path, ≤12 nodes

#   - Valid component types/variants only

#   - No custom legend without justification

# Validate after every significant change

node bin/archify.mjs validate architecture my-diagram.json \
     --quality showcase --json

# Apply first suggested fix when diagnostics appear

# (e.g., adjust labelAt, add missing side, correct componentType)

# Deliver final HTML on clean validation

node bin/archify.mjs deliver architecture my-diagram.json \
     output.html --quality showcase --json

# Or use live preview during active development

node bin/archify.mjs preview architecture my-diagram.json \
     output.html --quality showcase

Evidence-Based Diagrams from Code

When diagrams must reflect actual repository structure per archify/references/authoring-contract.md (lines 92-94):

1. Inspect entry-points, storage, transports, and deployment boundaries
2. Record only verified evidence
3. Use --repo-root flag with supported renderers for evidence receipts

Never infer runtime causality from file proximity or naming alone.

Summary

• Authoring invariants are immutable constraints enforced by the Archify validator—topology rules, fixed enums, and geometric minimums that guarantee unambiguous diagrams.
• Fast-authoring workflow provides bounded iteration: pick type, read schema, create constrained candidate, validate immediately, repair one diagnosed issue at a time, deliver on clean pass.
• Showcase quality profile runs 9 artifact checks with zero warnings required for success.
• Diagnostic-driven repair follows meta-profile → node overlap → edge-through-node → crossings → label clearance sequence.
• Geometry rules in the authoring contract specify side-perpendicular routing, minimum segment lengths, and label-gap calculations.

Frequently Asked Questions

What happens if I violate an authoring invariant?

The validator rejects the diagram and returns a JSON diagnostic with code, subject, evidence, and supportedFixes. You must resolve the specific violation before delivery succeeds. No partial or degraded output is generated.

Can I use custom component types or variants outside the schema-defined enums?

No. The renderer strictly validates against enums in authoring-contract.md (lines 9-11). Attempting undefined types or variants triggers a schema violation. This constraint ensures consistent visual language across all Archify diagrams.

What is the difference between "showcase" and "standard" quality profiles?

Showcase enforces all 9 artifact checks with zero warnings—required for publication-ready diagrams. Standard permits denser layouts with relaxed spacing, suitable for exploratory drafts. Both profiles enforce core invariants; showcase adds stricter geometry and clarity requirements.

How do I fix a diagram with edge-through-node violations?

Run validation to get the specific subject node and supportedFixes. Common remedies include adding a via point to reroute, adjusting channelX/channelY for orthogonal paths, or repositioning the connected nodes. Apply one fix, re-validate, and iterate.

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