When to Use Archify’s Architecture Diagram Type: A Complete Guide

Use Archify’s Architecture diagram type when you need to visualize the components, services, storage units, and security boundaries of a system at a high level, rather than mapping detailed execution flows.

The tt-a1i/archify repository provides five distinct diagram types, each optimized for different visualization needs. Understanding when to select the Architecture diagram ensures your system documentation accurately communicates structural relationships and ownership boundaries to stakeholders.

What the Architecture Diagram Type Covers

The Architecture diagram focuses on static structural elements rather than dynamic behavior. According to the source code in README.md (lines 33-41), this type is explicitly designed for "Components, services, storage, boundaries."

The archify/SKILL.md file (lines 59-63) confirms this mapping through the type router, specifying that Architecture diagrams handle "Components, services, cloud/security boundaries, infrastructure." This makes it distinct from sequence or flow-based diagrams that track execution steps.

Key characteristics include:

• Scope: High-level component maps showing what exists and how pieces are bounded
• Content: Front-end layers, back-end services, databases, cloud resources, security perimeters, message buses, and external services
• Metadata support: Ownership regions, deployment zones, and compliance-relevant boundaries

Four Specific Use Cases for Architecture Diagrams

System-Level Overviews

Use the Architecture type when describing the overall shape of an application, microservice landscape, or deployment topology. This provides stakeholders with a bird's-eye view of how major system pieces fit together without overwhelming detail about individual API calls or data transformations.

Boundary-Focused Audits

Select this diagram type for identifying trust zones, security perimeters, or compliance-relevant zones where "who owns what" matters. The Architecture diagram excels at visualizing security boundaries and regulatory isolation requirements, making it ideal for architecture review boards and security audits.

Static Component Documentation

Generate Architecture diagrams when you need repository-stored documentation that remains valid without live runtime data. Unlike dynamic monitoring dashboards, these diagrams serve as reference blueprints that developers can consult during onboarding or design discussions. The output is typically delivered as interactive HTML files that can be version-controlled alongside your code.

Change-Impact Reviews

Leverage the Architecture type's delta comparison capabilities when reviewing system evolution. The compare command allows you to visualize differences between two Architecture snapshots (Before / Delta / After), highlighting added, removed, or moved components and relationships. This is critical for pull request reviews and migration planning.

How to Generate and Validate Architecture Diagrams

The CLI entry point at archify/bin/archify.mjs provides a complete workflow for creating Architecture diagrams. The core pipeline follows guide → validate → deliver.

Basic Workflow

First, generate a JSON specification from a text description using the guide command:

# Create architecture.json from a plain-text description

node archify/bin/archify.mjs guide "Show a web front-end, API gateway, backend service, PostgreSQL DB, Redis cache, and external payment provider" --json > architecture.json

Validate the specification against the schema defined in archify/schemas/architecture.schema.json:

# Validate with showcase quality profile

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

Deliver the final interactive HTML output:

# Generate the interactive diagram

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

Adding Deployment Ownership Profiling

For fail-closed deployment reviews, apply the deployment-ownership engineering profile to annotate components with ownership metadata:

# Inject deployment ownership profile into the spec

jq '.meta.engineering_profile="deployment-ownership"' architecture.json > tmp.json && mv tmp.json architecture.json

# Re-validate and deliver with ownership annotations

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

Comparing Snapshots with Delta

Track architectural evolution using the compare command to generate delta visualizations:

# Compare base.json and head.json versions

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

Key Implementation Files

Understanding the source structure helps determine when to use the Architecture type:

• README.md (lines 33-41): Contains the diagram-type comparison table explicitly recommending Architecture for component and boundary visualization
• archify/SKILL.md (lines 59-63): Implements the type router logic that maps Architecture to component and infrastructure use cases
• archify/bin/archify.mjs: CLI entry point handling guide, validate, deliver, and compare commands
• archify/schemas/architecture.schema.json: Defines the JSON IR structure that Architecture specifications must conform to
• archify/examples/archify-repo.html: Live example demonstrating viewer features and interactive capabilities

Summary

• Choose Architecture when documenting what comprises a system and where components sit, not how they interact step-by-step
• Ideal for system overviews, security boundary audits, static documentation, and change-impact analysis
• Workflow: Use guide to generate specs, validate to check against schema, and deliver to produce HTML
• Advanced features: Support for deployment-ownership profiling and delta comparisons between architectural versions
• Source authority: Configuration lives in README.md and SKILL.md, with schema validation in architecture.schema.json

Frequently Asked Questions

What is the difference between Architecture and other Archify diagram types?

While the Architecture diagram type focuses on static components, services, and security boundaries, other types in the tt-a1i/archify ecosystem handle dynamic behaviors. Architecture answers "what exists and how is it bounded," whereas sequence or flow diagrams would answer "how do components interact over time." The type router in archify/SKILL.md explicitly separates these concerns to help you pick the right visualization for your documentation goal.

Can I use Architecture diagrams for real-time system monitoring?

No. Architecture diagrams are designed for static documentation that captures a point-in-time snapshot of your system structure. They are stored as JSON specifications and rendered to HTML for repository-based documentation. For live monitoring, you would need observability tools that ingest runtime metrics, whereas Archify's Architecture type serves design-time documentation and review processes.

How do I validate that my Architecture JSON follows the correct schema?

Use the validate command with the architecture type argument. The CLI checks your JSON against archify/schemas/architecture.schema.json to ensure required fields, component relationships, and boundary definitions meet the specification. You can specify quality profiles like --quality showcase to enforce stricter validation rules for production documentation.

What does the deployment-ownership profile add to Architecture diagrams?

The deployment-ownership engineering profile annotates components with ownership metadata required for fail-closed deployment reviews. When you inject this profile using jq to modify the meta.engineering_profile field, the validator checks for ownership assignments across all components. This ensures compliance requirements are met before the diagram is delivered as final documentation.

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