# How Archify Differs from Static Analysis Tools: A Visual-First Approach to Code Architecture

> Discover how Archify transcends static analysis tools by offering a visual-first platform that maps your code's architecture, data flows, and system behavior interactively.

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

---

**Archify is not a static-analysis linter or security scanner—it is a visual-first, architecture-centric platform that transforms code repositories into interactive diagrams of system behavior, data flows, and semantic relationships.**

Unlike traditional static analysis tools that flag code-level defects, Archify treats **software architecture as a first-class artifact**. The platform generates human-readable SVG and HTML visualizations from metadata-driven story declarations, enabling design reviews, team onboarding, and architecture drift detection.

## Archify vs. Static Analysis: Core Differences

| Aspect | Archify | Typical Static Analysis Tools |
|--------|---------|------------------------------|
| **Primary Goal** | Communicate architectural intent and runtime flow to humans. | Detect code-level defects automatically. |
| **Output** | Interactive diagrams, story-boards, lifecycle views. | Textual warnings, error codes, lint reports. |
| **Analysis Target** | Metadata and semantic relationships describing intended behavior. | Concrete AST, bytecode, and actual code patterns. |
| **Human Artifacts** | Story-Maps, Guides, Semantic Lenses rendered by `render-workflow.mjs`. | Raw diagnostics requiring separate documentation. |
| **Extensibility** | Plugin recipes and custom validators via `generate-validators.mjs`. | Rule-sets producing flat diagnostics. |
| **Runtime Support** | Ingests runtime artifacts like execution receipts. | Compile-time or static parsing only. |

## How Archify Builds Architecture Visualizations

The Archify pipeline starts at **`archify/bin/archify.mjs`**, the CLI entry point that orchestrates repository parsing, story-graph construction, and output generation. This differs fundamentally from static analysis tools, which traverse source code to emit machine-readable metrics.

### Generate a Full Architecture View

```bash
npx archify generate \
  --repo ./my-project \
  --out ./architecture.html

```

The CLI parses repository metadata, builds a **story-graph**, and produces an interactive HTML page for architectural exploration.

### Render a Workflow Diagram Programmatically

```javascript
import { renderWorkflow } from "archify/renderers/workflow/render-workflow.mjs";

const architecture = await loadArchitecture("./my-project");
const html = renderWorkflow(architecture, { theme: "light" });
await writeFile("./workflow.html", html);

```

The **`render-workflow.mjs`** renderer transforms the story graph into navigable workflow diagrams with theming support.

## Analyzing Architecture Changes Over Time

Static analysis tools operate on snapshots. Archify computes **deltas between architecture versions**, as implemented in **`archify/delta/architecture-delta.mjs`**.

### Compute an Architecture Delta

```bash
archify delta \
  --base v1.0.0 \
  --head v2.0.0 \
  --out delta.html

```

This compares two architectural snapshots and visualizes structural changes—critical for release notes and migration planning.

## Extending Archify with Custom Concerns

Archify's **recipe system** allows teams to model domain-specific architectural rules through **`archify/recipes/scenarios.mjs`** and the validator generator.

### Add a Custom Validation Rule

```javascript
// In archify/recipes/custom.mjs
export const myRule = {
  id: "no-circular-deps",
  description: "Prevent circular dependencies between modules",
  validate: (graph) => { /* … */ },
};

// Generate runtime validator
npx archify generate-validators --recipe ./archify/recipes/custom.mjs

```

The **`generate-validators.mjs`** script consumes recipe definitions and emits runtime validation functions—enforcing governance without sacrificing visual clarity.

## Key Source Files in Archify

| File | Purpose |
|------|---------|
| `archify/bin/archify.mjs` | CLI entry point orchestrating the full pipeline. |
| `archify/renderers/workflow/render-workflow.mjs` | Core renderer for interactive workflow diagrams. |
| `archify/delta/architecture-delta.mjs` | Structural differencing between architecture snapshots. |
| `archify/recipes/scenarios.mjs` | Reusable scenario recipes for common concerns. |
| `archify/scripts/generate-validators.mjs` | Recipe-to-validator code generation. |

Additional documentation in **[`DESIGN.md`](https://github.com/tt-a1i/archify/blob/main/DESIGN.md)** and **[`PRODUCT.md`](https://github.com/tt-a1i/archify/blob/main/PRODUCT.md)** at the repository root explains the architectural rationale and feature positioning against code-only tools.

## Summary

- **Archify differs from static analysis tools** by targeting human comprehension rather than automated defect detection.
- **Visual outputs** (diagrams, story-maps, lifecycle views) replace textual lint reports.
- **Metadata-driven analysis** of intended behavior complements static analysis of actual code patterns.
- **Delta computation** and runtime artifact ingestion support architectural governance over time.
- **Recipe-based extensibility** enables custom domain modeling without changing core tooling.

## Frequently Asked Questions

### Can Archify replace ESLint, SonarQube, or other static analysis tools?

No. Archify serves a complementary purpose. Static analysis tools detect bugs, security vulnerabilities, and style violations automatically. Archify visualizes system architecture and behavior for human stakeholders. Teams should use both: static analysis for CI gating, Archify for design reviews and documentation.

### Does Archify analyze source code directly like traditional static analysis?

Partially. Archify works primarily on **metadata**—story declarations and relationship objects that describe what code is intended to do. It does not traverse ASTs or bytecode to find actual defects. This metadata layer allows Archify to visualize architectural intent separately from implementation details.

### How does Archify handle architecture changes between software versions?

Archify computes structural differences via **`architecture-delta.mjs`**. The `archify delta` command compares two architecture snapshots and generates visual reports showing added, removed, or modified components—useful for release notes, migration guides, and drift detection.

### Can Archify visualize runtime behavior or only static structure?

Both. Archify can ingest **runtime artifacts** such as execution receipts and share-card JSON, visualizing them alongside static architectural definitions. This capability distinguishes it from strictly compile-time static analysis tools.