Can Archify Be Used with Existing Codebases? How to Map Any Project Without Rewrites

Yes—Archify works directly on any existing repository without code changes, parsing source files and generating interactive architecture diagrams through CLI or chat agents.

The tt-a1i/archify skill is built specifically for retroactive architecture visualization. Instead of requiring annotations or refactorings, it ingests your current codebase as-is, resolves source-line references, and produces a schema-validated, shareable system map. This article explains the exact mechanisms, file paths, and commands you need to deploy Archify on legacy projects today.

---

How Archify Handles Existing Codebases

Zero-Rewrite Design Philosophy

According to the tt-a1i/archify source code, the tool's core value proposition is turning a codebase or system description into a polished, interactive system map—no preprocessing required. The README explicitly states that Archify operates on "any existing repository or system description," making it suitable for brownfield adoption.

The design achieves this through three architectural decisions visible in the source:

• File system introspection rather than AST instrumentation
• JSON IR generation that validates against archify/schemas/architecture.schema.json
• Source-line receipts that maintain traceability without code modification

The --repo-root Parameter: Point and Map

In archify/bin/archify.mjs (lines 77-95), the CLI implements a --repo-root argument that accepts any local folder containing a project:

// From archify/bin/archify.mjs
{ name: 'repo-root', type: String, defaultValue: process.cwd() }

This parameter resolves relative paths, validates source-line references against the JSON schema, and forwards the validated structure to archify/renderers/architecture/render-architecture.mjs for HTML generation. The result is a self-contained artifact that embeds both visual layout and navigable code links.

---

Running Archify on Your Existing Project

Method 1: One-Time CLI Mapping

For standalone use, install the skill globally and render directly:

# Install once

npx skills add tt-a1i/archify -g

# Map current directory

archify render architecture archify-output.html --repo-root $(pwd)

The command:

1. Recursively reads files under the specified root
2. Generates archify-output.html with deterministic output
3. Prints validation diagnostics to stderr if source-line references fail resolution

Method 2: Chat-Agent Invocation

Archify integrates with Raven, Cursor, Claude Code, Codex CLI, and OpenCode. The agent handles repository loading automatically:

User: Map the runtime architecture of this Node.js service.
Agent: (invokes Archify skill with implicit --repo-root)
Agent: Interactive diagram ready → [shareable URL]

The agent supplies the repository root, executes the skill, and returns a hosted or local artifact. This workflow requires zero CLI familiarity from the user.

Method 3: CI Pipeline Integration

Track architectural drift by generating versioned snapshots:

# Generate base snapshot

git checkout main
archify render architecture base.json --repo-root .

# Generate feature snapshot  

git checkout feature-branch
archify render architecture head.json --repo-root .

# Produce delta visualization

archify compare architecture base.json head.json arch-delta.html

The arch-delta.html output highlights added/removed components with verified receipts for each diff—useful for PR reviews and architectural governance.

---

Validation and Traceability Guarantees

Schema-Validated Output

All generated artifacts conform to archify/schemas/architecture.schema.json. This enforces type safety on the intermediate representation before HTML emission. Invalid source-line references surface as structured diagnostics rather than silent failures.

Source-Line Receipts

Archify embeds receipts—provenance metadata linking each visual element to its originating file and line number. This makes the output auditable and safe for:

• Legacy codebases without documentation
• Compliance-sensitive environments
• Long-running systems where original authors have departed

---

Real-World Verification: The mco-org/mco Example

The tt-a1i/archify README documents a concrete case: running Archify against the public mco-org/mco repository produced a complete architecture diagram without any repository modification. This demonstrates:

• Cross-language applicability (mco is a multi-service project)
• No dependency on project-specific build systems
• Successful parsing of real-world code complexity

The example output is referenced in README section "A real repository, mapped from source" (lines 65-70).

---

Key Files for Existing Codebase Adoption

File	Purpose	Critical for Existing Projects
archify/bin/archify.mjs	CLI entry, --repo-root parsing	Direct invocation on any folder
archify/renderers/architecture/render-architecture.mjs	Layout engine, HTML generation	Produces final artifacts
archify/schemas/architecture.schema.json	IR validation	Ensures output integrity
examples/web-app.html	Local viewer	Review generated maps offline

---

Summary

Archify is purpose-built for existing codebases through these mechanisms:

• --repo-root CLI parameter accepts any local project folder without preparation
• Chat-agent activation removes tooling burden entirely
• Schema-validated JSON IR ensures output reliability across languages and structures
• Source-line receipts maintain full traceability to original code
• Deterministic HTML/SVG/PNG/WebM output integrates into documentation and CI pipelines

The mco-org/mco public example proves production viability on unmodified repositories.

---

Frequently Asked Questions

Does Archify require code annotations or decorators?

No. Archify parses source files directly without AST instrumentation or decorator injection. The render-architecture.mjs renderer performs static analysis on the file tree you provide via --repo-root.

What happens if source-line references become stale?

The JSON schema validation in architecture.schema.json catches unresolved references during generation. CLI execution prints diagnostics; you can regenerate from the current codebase state to synchronize.

Can Archify handle monorepos with multiple languages?

Yes. The mco-org/mco example is a multi-service repository. The --repo-root parameter accepts the monorepo root, and the renderer processes all recognizable source files within that tree.

Is there a cost to repeatedly running Archify in CI?

Generation is deterministic and file-based—no external API calls for core functionality. Runtime scales with repository size; JSON snapshots enable diff-based workflows without full regeneration.

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