/architecture

name: architecture
description: "Living Architecture Map — auto-generate Mermaid diagrams of your codebase. Use when user wants to visualize architecture, understand code structure, generate diagrams, or document system design."
allowed-tools: Bash, Read, Grep, Glob, Write

Living Architecture Map

Auto-generates and maintains architecture diagrams from your actual code. Always up-to-date.

Process

Phase 1: Scan

node ${CLAUDE_PLUGIN_ROOT}/tools/architecture-mapper.mjs <project-directory>

Parse the JSON output for architecture data and diagrams.

Phase 2: Present Diagrams

Display each Mermaid diagram with context:

**System Architecture:** High-level view of all components and how they connect.

[system diagram from tool output]

**API Route Map:** All endpoints organized by resource.

[routes diagram from tool output]

**Database Schema:** Entity-relationship diagram of all tables and relations.

[database ER diagram from tool output]

**Data Flow:** Sequence diagram showing how a typical request flows through the system.

[data flow diagram from tool output]

Phase 3: Architecture Analysis

Based on the scanned data, provide analysis:

**Strengths:**

• Clear layer separation
• No circular dependencies
• Well-organized middleware chain

**Concerns:**

• Circular dependencies found (list them)
• Orphan modules (files imported by nothing)
• Large files that may need splitting
• Missing middleware (no auth, no rate limiting, etc.)

**Service Dependencies:** List all external services and how they're used. Flag any that are single points of failure.

Phase 4: Save Diagrams

Save architecture documentation:

1. Create `docs/architecture/` directory 2. Save `docs/architecture/ARCHITECTURE.md` with all diagrams 3. Save individual diagram files if needed

The document should be self-contained and renderable in GitHub (GitHub supports Mermaid in markdown).

Phase 5: Recommendations

Based on architecture analysis:

1. **Circular dependencies** — suggest how to break cycles 2. **Orphan modules** — suggest removal or integration 3. **Missing patterns** — suggest middleware, error handling, or caching if absent 4. **Scalability concerns** — identify bottlenecks (single database, no caching, synchronous processing)

Keeping Diagrams Updated

Recommend running `/architecture` after any significant structural change:

• Adding new API routes
• Adding new database tables
• Integrating new external services
• Major refactors

The diagrams are generated from code, so they're always accurate when re-run.

Key Principle

**The map IS the territory.** Architecture diagrams that drift from reality are worse than no diagrams. Because these are auto-generated from code, they're always truthful.