What Types of Issues Can Archify's Composition Checking Detect?

Archify's composition checking can detect seven distinct categories of architectural diagram issues, including improper edge crossings, container border violations, excessive micro-segments, cramped turns, missing structural frames, composition profile mismatches, and overall validation status failures.

The tt-a1i/archify repository provides automated composition checking that validates how structural frames and edges are arranged within architectural diagrams. This system evaluates geometric routing, structural integrity, and profile compliance to ensure diagrams remain both syntactically correct and architecturally coherent. Understanding what types of issues Archify's composition checking can detect enables teams to enforce strict quality gates in their documentation pipelines.

Edge Geometry and Routing Violations

Archify analyzes edge geometry in scripts/build-gallery.mjs at line 225 to identify four specific routing issues that degrade diagram clarity and violate architectural boundaries.

Improper Edge Crossings

The system detects improper edge crossings when connections intersect each other in ways that make diagrams difficult to read or that violate layer boundaries. These crossings often indicate incorrect dependency flows or hierarchical violations that obscure the intended architecture.

Container Border Violations

When edges intersect the borders of containers—such as regions, security groups, or lanes—incorrectly, Archify flags these as container border violations. This indicates misplaced responsibilities where connections improperly traverse containment boundaries, suggesting components belong in different architectural partitions.

Excessive Micro-Segments

The validator counts tiny line segments resulting from over-fragmented routing algorithms. Excessive micro-segments suggest the need to simplify edge paths to improve rendering performance and visual clarity, as fragmented routing often indicates poor pathfinding or manual over-editing.

Cramped Turns and Short Interior Segments

Archify identifies cramped turns where routing angles are too tight, as well as short interior segments that create ambiguous routing paths. These geometric issues typically indicate layout algorithms or manual adjustments that compromise readability and create visual confusion.

Structural Frame Integrity

Missing or Mis-typed Structural Frames

In scripts/package-smoke.mjs at line 133, Archify verifies that every expected frame—including regions, lanes, groups, and security groups—is present and correctly typed. Missing or mis-typed structural frames break the diagram's hierarchical integrity and invalidate the architectural model by creating orphaned components or invalid containment hierarchies.

Composition Profile Validation

Composition Profile Mismatch

At line 1022 in archify/bin/archify.mjs, the system checks that the rendered diagram matches the declared composition profile (such as "showcase"). A composition profile mismatch occurs when the visual output deviates from the intended architectural pattern, catching inconsistencies between design intent and actual implementation.

Overall Pass/Fail Status

The system aggregates all metrics into a single compositionStatus field. As implemented in archify/bin/preview.mjs at line 472, this boolean-style status returns either pass or fail, determining whether the diagram meets architectural standards for automated pipelines and CI/CD integration.

Running Composition Checks

You can execute these validations via the CLI or programmatically to automate quality control.

CLI Execution

Run the preview command to generate validation receipts:

# Generate a preview and see composition results

archify preview path/to/your/architecture.json

# Output includes something like:

#   1/1 artifact checks; composition SHOWCASE: pass

Programmatic Integration

Import runPreview from archify/bin/preview.mjs to check composition status in Node.js applications:

import { runPreview } from 'archify/bin/preview.mjs';

const receipt = await runPreview('examples/archify-repo.architecture.json');
if (receipt.validation.compositionStatus !== 'pass') {
  console.warn('Composition issues detected:', receipt.validation.composition);
}

Summary

• Archify detects seven distinct composition issues ranging from geometric edge violations to structural frame integrity failures.
• Edge-related checks in scripts/build-gallery.mjs identify crossings, border violations, micro-segments, and cramped turns at line 225.
• Structural validation in scripts/package-smoke.mjs ensures all required frames are present and correctly typed at line 133.
• Profile matching in archify/bin/archify.mjs verifies diagrams adhere to declared composition profiles like "showcase" at line 1022.
• The compositionStatus field in archify/bin/preview.mjs at line 472 provides a binary pass/fail result for automated quality gates.

Frequently Asked Questions

What is the compositionStatus field in Archify?

The compositionStatus field is a validation result returned by Archify's preview system, specifically aggregated in archify/bin/preview.mjs at line 472. It compiles all composition metrics into either pass or fail, indicating whether the diagram meets architectural standards. This field enables CI/CD pipelines to gate deployments based on diagram quality automatically.

How does Archify detect edge routing problems?

Archify analyzes edge geometry in scripts/build-gallery.mjs at line 225 to detect improper crossings, container border violations, excessive micro-segments, and cramped turns. These checks evaluate the physical routing paths of connections to ensure they don't violate containment boundaries or create unreadable crossing patterns that obscure architectural intent.

Can Archify validate specific architectural patterns?

Yes, Archify validates composition profiles such as "showcase" as implemented in archify/bin/archify.mjs at line 1022. The system verifies that the rendered diagram matches the declared profile, ensuring consistency between the intended architectural pattern and the actual diagram structure, which catches mismatches between design specifications and implementation.

What happens when a composition check fails?

When checks fail, the compositionStatus returns fail and the validation receipt includes detailed information about the specific violations found. As shown in scripts/package-smoke.mjs at line 133, automated processes can abort operations when encountering non-pass statuses, preventing low-quality diagrams from entering production documentation or deployment pipelines.

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