How Archify Handles Large Projects: Scalable Architecture for Enterprise Codebases

Archify handles large projects through a typed JSON intermediate representation, deterministic layout engines, canvas‑size clamping, progressive focus navigation, and static self‑contained HTML outputs that scale from tiny repositories to thousands of files without re‑parsing or runtime dependencies.

How does Archify handle large projects? This is a critical question for teams managing enterprise codebases with thousands of modules. According to the tt-a1i/archify source code, the tool is explicitly architected to scale deterministically from small examples to very large repositories while preserving performance, browser memory limits, and CI/CD reproducibility. The following sections break down the six core strategies that make this possible.

Typed JSON Intermediate Representation (IR)

Everything in Archify starts with a clean separation between data and rendering.

In archify/schemas/README.md, the toolchain defines a typed JSON intermediate representation that converts repository trees, system descriptions, or manual JSON inputs into a pure data model. This IR contains complete structural information—nodes, edges, metadata—without any rendering concerns.

Because the IR is decoupled from output formats, the same source can be processed by any of Archify's five renderers without re‑parsing original code. For large projects, this means:

• One validation pass, multiple outputs
• No redundant file system traversal
• Deterministic caching of the IR between builds

# Generate IR for a large repository

node archify/bin/archify.mjs generate ./my-large-repo --output diagram.html

The archify/bin/archify.mjs CLI handles this pipeline: parse → IR → validate → render.

Deterministic Validation and Layout

Before any pixel is drawn, Archify validates and stabilizes the entire structure.

Per the validation flow in README.md (lines 96–104), the IR passes JSON schema validation, then feeds into a layout engine that produces stable pos and size coordinates. Because layout is pure data transformation:

• The same large diagram regenerates identically on every change
• Unrelated regions don't trigger re‑computation
• CI/CD pipelines get bitwise‑reproducible outputs

This deterministic approach prevents the "layout drift" common in dynamic diagram tools when dependencies shift.

Canvas-Size Clamping for Massive ViewBoxes

Large diagrams risk silent rendering failures on memory‑constrained environments.

Archify solves this through intelligent canvas‑size clamping documented in CHANGELOG.md (lines 251–255). The rasterize() helper automatically selects the highest integer scale that keeps the output under a 16 million pixel safety cap:

Scale	Typical Use Case
4×	Standard diagrams (~1000 × 680)
3×	Large projects (~1600 × 1200)
2×	Very large viewBoxes
1×	Massive diagrams at minimum viable resolution

# Export with automatic scale selection

node archify/bin/archify.mjs rasterize diagram.html --scale auto --output diagram.png

The --scale auto flag triggers this stepped degradation, preventing "blank canvas" failures on mobile Safari and keeping export times predictable.

Progressive Focus and Semantic Zoom

Exploring a 500‑node diagram requires selective attention, not overwhelming detail.

As implemented in docs/research-visual-evolution-round-2.md (lines 24–38), Archify breaks large diagrams into focusable sub‑graphs. User interactions trigger progressive disclosure:

• Click or Enter on a node dims unrelated parts and highlights the one‑hop neighborhood
• Deep linking via #focus=<id> restores focus on reload
• Direct navigation jumps to areas of interest without full‑detail loading

# Preview with immediate focus on auth-service

node archify/bin/archify.mjs preview diagram.html --focus auth-service

The viewer updates the URL to diagram.html#focus=auth-service, enabling shareable links into specific architectural regions.

Optional Minimap and Fisheye Navigation

Global context aids for truly massive graphs stay opt‑in.

Per docs/research-visual-evolution-round-8.md (line 15), Archify adds minimap and fisheye views only when diagrams exceed configurable size thresholds. This keeps standard projects lightweight while providing navigation aids for exceptional cases.

Enable via IR metadata:

{
  "meta": {
    "visual_preset": "signal-flow",
    "minimap": true
  }
}

The renderer in archify/renderers/architecture/render-architecture.mjs respects these flags alongside viewBox, scaling, and focus logic.

Static, Self-Contained HTML Artifacts

The final output contains zero external runtime dependencies.

Archify emits a single HTML file embedding SVG and all interaction logic. For large projects, this delivers critical operational benefits:

• Shareable via simple file transfer or CDN
• Cacheable with immutable content hashing
• Archivable without network dependency rot
• Exportable to PNG/WebM with consistent scaling logic

Per README.md (lines 79–87), the export workflow guarantees that even very large diagrams render crisply in all formats.

Summary

• Typed JSON IR in archify/schemas/README.md decouples parsing from rendering for large codebases
• Deterministic validation and layout produce stable, reproducible coordinates
• Canvas‑size clamping automatically scales down massive viewBoxes to prevent memory failures
• Progressive focus and deep linking enable navigation without loading full detail
• Optional minimap/fisheye activate only when diagrams exceed thresholds
• Static HTML artifacts eliminate runtime dependencies for sharing and archiving

Frequently Asked Questions

What is the maximum repository size Archify can process?

There is no fixed file count limit. Archify's typed JSON IR and deterministic layout handle thousands of files, with actual constraints coming from browser memory for final rendering and the 16 million pixel cap on raster exports. The rasterize() helper in archify/bin/archify.mjs automatically adjusts scale to stay within safe limits.

Does Archify support incremental updates for large projects?

The deterministic IR and layout engine regenerate complete diagrams quickly without re‑parsing unchanged regions, though full incremental updates are not yet implemented. The pure‑data pipeline means the same large diagram rebuilds fast enough for most CI/CD workflows.

How does focus mode affect performance on massive diagrams?

Focus mode in archify/renderers/architecture/render-architecture.mjs dims rather than removes nodes, keeping the DOM stable. The semantic zoom approach avoids expensive relayout operations—only visual opacity changes, making interaction responsive even with hundreds of visible elements.

Can I export large diagrams for presentations without quality loss?

Yes. The --scale auto flag selects the highest safe resolution, and vector SVG outputs remain lossless. For pixel‑perfect PNG exports, Archify steps down scale factors (4× → 3× → 2× → 1×) rather than failing, ensuring usable output even for very large viewBoxes per CHANGELOG.md (lines 251–255).

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