archrip

archrip

Generate interactive architecture diagrams from your codebase using AI.

archrip lets Claude Code analyze your codebase and produce a self-contained, interactive architecture viewer as static HTML — deployable anywhere.

Quick Start

Run these commands in Claude Code (the CLI):

# 1. Install the plugin (in Claude Code)
/plugin marketplace add yida29/archrip
/plugin install archrip@archrip

# 2. Scan the codebase (in Claude Code)
/archrip-scan

# 3. Build & preview the viewer
npx archrip build
npx archrip serve

How It Works

1. Install plugin — Run /plugin marketplace add yida29/archrip and /plugin install archrip@archrip in Claude Code
2. /archrip-scan — Claude reads your codebase and docs, asks you to review the draft, then generates .archrip/architecture.json
3. archrip build — validates the JSON, auto-installs the viewer if needed, computes layout with dagre, and builds a static React Flow viewer
4. archrip serve — opens the interactive architecture viewer in your browser

The output is a standalone dist/ folder you can deploy to GitHub Pages, Netlify, or share as a zip.

Skills

Skill	Description
/archrip-scan	Full codebase scan — reads code & docs, presents draft for review, generates architecture.json
/archrip-update	Update or refine the diagram — auto-detects changes from git diff, or apply manual edits

CLI Commands

Command	Description
npx archrip init [path]	Initialize archrip in a project (optional — build auto-setups the viewer)
npx archrip build	Build the architecture viewer to .archrip/dist/ (auto-installs viewer if needed)
npx archrip serve	Preview the built viewer at localhost:4173

architecture.json Format

{
  "version": "1.0",
  "project": {
    "name": "My App",
    "sourceUrl": "https://github.com/org/repo/blob/main/{filePath}"
  },
  "nodes": [
    {
      "id": "ctrl-users",
      "category": "controller",
      "label": "UsersController",
      "description": "Handles user registration, authentication, and profile management. Uses JWT for session tokens with 24h expiry.",
      "filePath": "src/controllers/users.ts",
      "layer": 1,
      "useCases": ["uc-user-mgmt"],
      "metadata": [
        { "label": "Rate Limit", "value": "10 req/s per IP", "type": "text" }
      ]
    }
  ],
  "edges": [
    { "source": "ctrl-users", "target": "svc-users", "type": "dependency" }
  ],
  "useCases": [
    {
      "id": "uc-user-mgmt",
      "name": "User Management",
      "nodeIds": ["ctrl-users", "svc-users", "entity-user"]
    }
  ]
}

Node Categories

Category	Color	Use For
controller	Blue	HTTP entry points (Controller, Route Handler, Resolver)
service	Green	Business logic (Service, UseCase)
port	Purple	Abstractions (Interface, Contract, Port)
adapter	Orange	Implementations (Repository impl, API client)
entity	Red	Domain entities, value objects (core business logic)
database	Amber	DB tables, migrations, ORMs
infrastructure	Indigo	IaC resources (Terraform, Pulumi, sst.config.ts, CloudFormation)
external	Gray	External services (API, DB, Queue)
job	Yellow	Background (Job, Worker, Cron)
dto	Cyan	Data transfer (DTO, Request, Response)

Custom categories are supported — they get a fallback color.

Layers

The layer field controls positioning. Higher = closer to domain core (more stable). Lower = closer to external world (more volatile). Dagre places higher layers lower on screen; concentric places them at the center. Use as many layers as the architecture requires (any non-negative integer, typically 3-6).

DDD / Clean Architecture example:

Layer	Content
0	External services (DB, APIs, queues)
1	Infrastructure / Adapters (Controllers, DB impl, API clients)
2	Application Core (Use Cases, Ports, DTOs)
3	Domain (Entities, Value Objects)

MVC example (Rails, Laravel, Django):

Layer	Content
0	External services
1	Controllers / Views
2	Services / Business logic
3	Entities

For concentric layout ("layout": "concentric"), category semantics override layer numbers to ensure correct ring placement — entities always at center, external always at outer ring.

Edge Types

Type	Meaning
dependency	Component A depends on B
implements	Adapter implements Port/Interface
relation	Data relationship (hasMany, belongsTo)

Edges support optional description and metadata fields for richer context (e.g., SQL queries on DB edges).

Framework Support