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

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, 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 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, 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. 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

# 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 in the repository for a reference implementation.

Visualize the Architecture Graph

# Produce interactive HTML exploration page

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

Open architecture.html to explore module hierarchies, drill into class definitions, and trace import relationships through highlighted edges.

Compute Architecture Deltas Between Versions

# 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

# .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 – Complete specification of the design.json schema governing analysis behavior
• archify/test/ – Test suite covering graph generation, delta calculation, and visualization pipelines
• examples/archify-repo.architecture.json – Self-referential architecture output for the Archify repository itself
• examples/archify-repo.html – Interactive rendering of the above model
• .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 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 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 at the repository root. This file defines crawl patterns, parser mappings, and export preferences. See DESIGN.md in the tt-a1i/archify repository for the complete schema specification and configuration examples.

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