# How Archify Analyzes Code Architecture: A Three-Stage Pipeline Explained

> Discover how Archify analyzes code architecture using its three-stage pipeline. Learn how it transforms codebases into queryable models for better understanding and maintainability.

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

---

**Archify analyzes code architecture through a three-stage pipeline—repository crawling, static parsing with language-specific AST extraction, and graph construction—that converts any codebase into a structured, queryable architecture model.**

Archify is a lightweight, data-driven tool from `tt-a1i/archify` that inspects a codebase and builds a **structured architecture model** describing its components, relationships, and evolution over time. Unlike traditional static analysis tools that focus on quality metrics or security vulnerabilities, Archify centers on architectural understanding—mapping how modules connect, how dependencies flow, and how the system changes between versions.

## Three-Stage Analysis Pipeline

The core of how Archify analyzes code architecture unfolds in three coordinated stages, each implemented with specific design constraints for performance and extensibility.

### Stage 1: Repository Crawling

Archify begins by walking the file tree of a Git repository or any local source directory. The crawler operates with **configurable glob patterns** defined in [`.impeccable/design.json`](https://github.com/tt-a1i/archify/blob/main/.impeccable/design.json), filtering files by extension and path while respecting `.gitignore`-like exclusion rules.

During this phase, Archify collects:
- File paths and directory structures
- File extensions and size metadata
- Generated artifact exclusions (build outputs, dependencies, etc.)

The declarative configuration in [`design.json`](https://github.com/tt-a1i/archify/blob/main/design.json) drives which files are considered "source" versus "noise," making the crawl reproducible across different environments.

### Stage 2: Static Parsing and Classification

For each discovered source file, Archify selects a **language-specific parser**—supporting JavaScript/TypeScript, Python, HTML, and extensible to additional languages. These parsers extract high-level constructs from AST nodes:

| Construct | Extraction Method | Examples |
|-----------|-------------------|----------|
| **Modules/Packages** | Top-level containers, manifest files | [`package.json`](https://github.com/tt-a1i/archify/blob/main/package.json), [`setup.cfg`](https://github.com/tt-a1i/archify/blob/main/setup.cfg), folder boundaries |
| **Classes/Functions** | AST node identification | Signatures, docstrings, import/export statements |
| **Data Assets** | Schema-aware parsing | JSON, YAML, configuration files |

Parsed objects normalize into a generic **architecture node** shape with four fields: `id`, `type`, `props`, and `edges`. **Edges** capture critical relationships:
- `imports` – dependency relationships between modules
- `extends` – inheritance hierarchies
- `calls` – invocation links
- `data flow` – configuration or data propagation paths

This normalization makes Archify **language-agnostic** at its core. Parsers expose minimal concepts—module, symbol, import—and the engine treats every language uniformly.

### Stage 3: Graph Construction and Export

The final stage assembles nodes and edges into a **directed graph** using the graphlib format. From this unified representation, Archify produces three primary outputs:

1. **Interactive HTML visualization** – Browseable demos available in `examples/*.html`
2. **Machine-readable JSON** – `*.architecture.json` files for downstream tooling (semantic zoom, roadmap generators, compliance checkers)
3. **Architecture delta reports** – Change detection between snapshots highlighting added components, removed modules, or modified dependencies

## Key Design Decisions in Archify's Architecture Analysis

Several implementation choices distinguish Archify's approach to code architecture analysis.

### Declarative Configuration

Users control the entire analysis pipeline through [`.impeccable/design.json`](https://github.com/tt-a1i/archify/blob/main/.impeccable/design.json). This single file determines:
- Crawl scope and file inclusions
- Parser selection per file type
- Filtering logic for noise reduction

### Incremental Caching

Expensive parsing results are **cached on disk**, enabling rapid recomputation when only a subset of files changes. This makes Archify viable for large codebases and frequent CI executions.

### Extensible Export Formats

Beyond the default JSON architecture model, Archify outputs:
- **Mermaid** diagrams for Markdown embeds
- **GraphViz DOT** for advanced rendering
- **Custom schemas** for organization-specific tooling

These formats integrate Archify into CI pipelines, documentation generators, and visual analytics dashboards without custom adapters.

## Practical Usage: Analyzing Code Architecture with Archify

### Generate an Architecture Snapshot

```bash

# Install Archify

npm i -g @tt-a1i/archify

# Create architecture model for current directory

archify generate --output ./my-project.architecture.json

```

The `--output` flag writes a JSON model suitable for visualization and programmatic analysis. See [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) in the repository for a reference implementation.

### Visualize the Architecture Graph

```bash

# Produce interactive HTML exploration page

archify render ./my-project.architecture.json --html ./architecture.html

```

Open [`architecture.html`](https://github.com/tt-a1i/archify/blob/main/architecture.html) to explore module hierarchies, drill into class definitions, and trace import relationships through highlighted edges.

### Compute Architecture Deltas Between Versions

```bash

# Compare snapshots for change analysis

archify diff ./baseline.architecture.json ./new-branch.architecture.json \
  --output ./delta.report.json

```

Delta reports enumerate added, removed, and modified nodes—valuable for automated PR review, release notes generation, and architectural drift detection.

### Integrate into CI Workflows

```yaml

# .github/workflows/archify.yml

name: Architecture Check
on:
  push:
    branches: [main]

jobs:
  archify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Archify
        run: npm i -g @tt-a1i/archify
      - name: Generate Architecture Model
        run: archify generate --output ./archify.json
      - name: Upload Artifact
        uses: actions/upload-artifact@v3
        with:
          name: architecture
          path: archify.json

```

## Source Code Reference

Key files demonstrating how Archify analyzes code architecture:

- [`DESIGN.md`](https://github.com/tt-a1i/archify/blob/main/DESIGN.md) – Complete specification of the [`design.json`](https://github.com/tt-a1i/archify/blob/main/design.json) schema governing analysis behavior
- `archify/test/` – Test suite covering graph generation, delta calculation, and visualization pipelines
- [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) – Self-referential architecture output for the Archify repository itself
- [`examples/archify-repo.html`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.html) – Interactive rendering of the above model
- [`.impeccable/design.json`](https://github.com/tt-a1i/archify/blob/main/.impeccable/design.json) – Default configuration showing crawl and parse rules

## Summary

- Archify analyzes code architecture through **repository crawling**, **language-specific AST parsing**, and **unified graph construction**
- The **[`.impeccable/design.json`](https://github.com/tt-a1i/archify/blob/main/.impeccable/design.json)** configuration file controls all analysis parameters declaratively
- **Normalized architecture nodes** (`id`, `type`, `props`, `edges`) make the engine language-agnostic and extensible
- **Incremental caching** and **multiple export formats** (JSON, Mermaid, DOT, HTML) support CI integration and large-scale usage
- **Delta computation** between snapshots enables architectural change tracking over time

## Frequently Asked Questions

### What languages does Archify support for architecture analysis?

Archify currently ships parsers for JavaScript/TypeScript, Python, and HTML, with an extensible adapter pattern that allows adding new languages by implementing the minimal interface: module detection, symbol extraction, and import relationship identification. According to the `tt-a1i/archify` source code, new parsers integrate without modifications to the core graph engine.

### How does Archify handle large codebases efficiently?

Archify uses **incremental caching** of parsing results and respects `.gitignore` exclusions by default. The [`design.json`](https://github.com/tt-a1i/archify/blob/main/design.json) configuration allows targeted inclusion patterns, so only relevant source files enter the analysis pipeline. The graph construction stage operates on normalized nodes, keeping memory usage bounded regardless of source language complexity.

### Can Archify detect architectural changes between git commits?

Yes. The `archify diff` command compares two architecture snapshots and produces a structured delta report. This identifies added modules, removed dependencies, and modified component properties. The `examples/` directory in the repository demonstrates self-referential delta analysis on Archify's own evolution.

### Where is the architecture configuration stored?

Analysis behavior is controlled by [`.impeccable/design.json`](https://github.com/tt-a1i/archify/blob/main/.impeccable/design.json) at the repository root. This file defines crawl patterns, parser mappings, and export preferences. See [`DESIGN.md`](https://github.com/tt-a1i/archify/blob/main/DESIGN.md) in the `tt-a1i/archify` repository for the complete schema specification and configuration examples.