# What Kind of Technical Debt Can Archify Identify? 4 Visual Debt Categories Explained

> Archify identifies four visual technical debt categories in architecture diagrams: crossings, corridors, border runs, and label clearance. Discover how Archify helps you manage these issues.

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

---

**Archify identifies four categories of visual-technical debt in architecture diagrams: proper crossings, ambiguous corridors, container border runs, and label-route clearance issues.**

The `tt-a1i/archify` tool analyzes generated architecture diagrams to detect visual clutter that obscures system understanding. These debt metrics are calculated during the **composition** phase and exposed through `archify validate` and `archify doctor` commands. This guide breaks down each debt type, how Archify computes it, and why it matters for maintaining readable system documentation.

## The Four Types of Technical Debt Archify Detects

Archify evaluates diagram quality through concrete, measurable visual defects. Each category targets a specific readability anti-pattern in architecture visualization.

### Proper Crossings: Unintentional Line Intersections

**Proper crossings** represent unintended orthogonal line crossings that create ambiguous relationships between components. Zero crossings indicate a clean planar layout where every relationship path is visually distinct.

In `archify/scripts/check-render-output.mjs`, this metric initializes at `0` and populates through `collectRelationshipCrossings`:

```javascript
// Lines 35-38 of check-render-output.mjs
const properCrossings = 0;
// ... collected via collectRelationshipCrossings during composition

```

Crossings introduce cognitive load—viewers must trace lines to determine actual connections versus accidental overlaps. Minimizing this debt ensures diagrams communicate dependencies without visual noise.

### Ambiguous Corridors: Overlapping Relationship Lanes

**Ambiguous corridors** occur when unrelated orthogonal relationship lanes overlap by 8 pixels or more, creating false impressions of merges or branches. This "corridor debt" deceives readers into perceiving connections where none exist.

Archify captures this through `collectAmbiguousCorridors` at line 94, with final mapping at line 173 of the same composition script:

```javascript
// From check-render-output.mjs — corridor detection logic
collectAmbiguousCorridors();  // Line 94
// Aggregation and reporting at line 173

```

Corridor overlaps are particularly insidious in dense diagrams where multiple services interact across container boundaries. The 8px threshold filters minor alignment noise while flagging genuinely confusing overlap.

### Container Border Runs: Intersecting Boundaries

**Container border runs** track sequences of container borders that intersect relationships—a distinct category called "container-border-run debt." These intersections break the visual hierarchy that containers (systems, subsystems, deployment zones) are meant to establish.

The `collectBorderRuns` function gathers this data starting at line 79, with reporting consolidation at line 132:

```javascript
// Lines 79-132 in check-render-output.mjs
collectBorderRuns();  // Gathers border-to-relationship intersections
// ... reported as containerBorderRuns at line 132

```

When relationship lines cut through container boundaries without clear entry/exit points, readers struggle to map components to their logical groupings. This debt metric enforces disciplined container modeling.

### Label-Route Clearance Issues: Crowded Relationship Labels

**Label-route clearance issues** flag relationship labels positioned too close to their routing paths. Insufficient clearance causes labels to blur into lines, making dependency annotations unreadable.

This completes Archify's four-category coverage of visual debt in diagram rendering.

## How Archify Surfaces Technical Debt Metrics

Debt detection occurs during the **composition phase** of diagram generation. The `check-render-output.mjs` script orchestrates analysis through specialized collection functions, then aggregates results into structured JSON.

Run validation with:

```bash

# Validate specific diagram

archify validate ./my-architecture.yml

# Or run full diagnostic

archify doctor

```

Output includes quantified debt scores per category, enabling:

- **Regression testing** — fail CI builds on debt threshold violations
- **Refactoring prioritization** — address highest-impact visual clutter first
- **Trend tracking** — monitor debt accumulation across diagram versions

## Why Visual Technical Debt Matters

Traditional code-centric technical debt tools (cyclomatic complexity, code duplication) miss a critical dimension: **system comprehension**. Architecture diagrams serve as the primary mental model for:

- New engineer onboarding
- Incident response navigation
- Stakeholder alignment on system scope

Visual debt directly degrades these workflows. A diagram with 12 proper crossings and 5 ambiguous corridors requires exponentially more cognitive effort to interpret than a clean planar layout. Archify bridges this gap by treating diagram hygiene as measurable, enforceable quality criteria.

## Summary

- **Proper crossings** — count unintended line intersections (lines 35-38, `collectRelationshipCrossings`)
- **Ambiguous corridors** — detect lane overlaps ≥8px (line 94, `collectAmbiguousCorridors`)
- **Container border runs** — flag boundary-to-relationship intersections (line 79, `collectBorderRuns`)
- **Label-route clearance issues** — identify crowded labels lacking path separation

All four metrics compute during composition in `archify/scripts/check-render-output.mjs` and report through `archify validate` / `archify doctor` JSON output.

## Frequently Asked Questions

### How does Archify define a "proper crossing" versus normal line intersections?

Archify distinguishes **proper crossings** as orthogonal intersections that create genuine ambiguity about relationship connectivity. The metric specifically targets crossings that could mislead a reader into tracing the wrong dependency path. Coincidental overlaps below significance thresholds or clearly separated crossing patterns may not increment this counter. The `collectRelationshipCrossings` implementation (line 35) applies geometric heuristics to classify crossings by their visual impact.

### Can Archify automatically fix the technical debt it detects?

No — as implemented in `tt-a1i/archify`, detection and remediation remain separate concerns. The `check-render-output.mjs` script computes debt metrics for reporting only. Automated layout optimization would require additional constraints on the underlying diagram engine's routing algorithms. Current workflows rely on human architects to refactor container structures, redistribute components, or adjust relationship paths based on debt reports.

### What threshold triggers a failure in `archify validate`?

The repository source does not encode universal debt thresholds; configuration likely passes through CLI flags or configuration files external to `check-render-output.mjs`. The composition script (lines 35-173) focuses purely on accurate measurement rather than policy enforcement. Teams typically establish contextual limits — for example, zero tolerance for ambiguous corridors in production architecture diagrams, with relaxed standards for draft documentation.

### How does label-route clearance detection work geometrically?

The implementation measures minimum distance between label bounding boxes and their associated relationship path segments. Insufficient clearance registers when this distance falls below a readability threshold (exact pixel value not specified in the analyzed source). This prevents labels from visually attaching to wrong relationships or becoming illegible against high-contrast line work.