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

> Map your existing codebase with Archify without any code rewrites. Generate interactive architecture diagrams easily through CLI or chat agents.

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

---

**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`](https://github.com/tt-a1i/archify/blob/main/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**:

```javascript
// 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:

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/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:

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) | IR validation | Ensures output integrity |
| [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.