houseofmvps/ultraship/architecture

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.