--- name: diagram description: "Generate Mermaid architecture diagrams from your codebase. Produces C4 context and container diagrams, sequence diagrams for key flows, ER diagrams from database schemas, and module dependency graphs. Use when you need architecture diagrams, system diagrams, database ERD, sequence diagrams, dependency visualization, or C4 model diagrams." version: "2.0.0" category: docs platforms: - CLAUDE_CODE --- You are in AUTONOMOUS MODE. Do NOT ask questions. Analyze the project codebase and generate comprehensive architecture diagrams using Mermaid. INPUT: $ARGUMENTS Accepted arguments: - No arguments: generate all applicable diagram types. - `c4`: generate C4 Context and Container diagrams only. - `sequence`: generate sequence diagrams for key flows only. - `er`: generate ER diagram from database schema only. - `deps` or `dependency`: generate module dependency graph only. - A specific flow description (e.g., "user login flow"): generate a sequence diagram for that specific flow. ============================================================ PHASE 1: CODEBASE ANALYSIS ============================================================ Step 1.1 -- Tech Stack and Architecture Detection Scan config files to determine: project type (web app, API, mobile, CLI, library, monorepo), primary language/framework, database(s), external services (auth, payment, email, storage), message queues, caching layers, and API gateway config. Step 1.2 -- Service and Module Mapping For monorepos/microservices: read docker-compose.yml or K8s manifests for service definitions, map inter-service communication, identify external deps per service. For monoliths: read directory structure to identify modules/domains, trace import statements to map module dependencies, identify layer boundaries. Step 1.3 -- Database Schema Extraction Scan for schema definitions in: schema.prisma, *.entity.ts (TypeORM/MikroORM), models/*.js (Sequelize), models.py (Django), db/schema.rb (Rails), models/*.py (SQLAlchemy), schema.ts (Drizzle), migrations/*.sql, *.model.ts (Mongoose). Extract: table/collection names, columns with types, primary/foreign keys, relationships (1:1, 1:N, M:N), indexes, and enums. Step 1.4 -- Key Flow Identification Identify the most important flows to diagram: - Authentication flow (login, signup, token refresh) - Primary business flow (main use case) - Data write flow (create/update through layers) - API request lifecycle (middleware, validation, handler, response) - Background job flow (if applicable) For each flow, trace: entry point, middleware, service layer, data access, external calls, and response construction. ============================================================ PHASE 2: DIAGRAM GENERATION ============================================================ Generate Mermaid diagrams. Use C4 syntax for architecture diagrams. Step 2.1 -- C4 Context Diagram Show the system in its environment: users/actors, the system boundary, and all external systems it connects to. Use `C4Context` with `Person`, `System`, `System_Ext`, and `Rel` elements. Keep it high-level -- no internal details. Step 2.2 -- C4 Container Diagram Show major containers within the system boundary: web apps, API servers, databases, caches, workers, message queues. Use `C4Container` with `Container`, `ContainerDb`, `ContainerQueue` elements. Show relationships with protocols (HTTPS, SQL, AMQP). Step 2.3 -- Sequence Diagrams For each key flow, generate a `sequenceDiagram` showing participants and message flow. Always generate auth flow if auth exists. Generate the primary business flow. Include request/response payloads as notes where helpful. Step 2.4 -- ER Diagram Generate from extracted schema using `erDiagram` syntax. Include all tables with columns (name, type, PK/FK/UK markers) and relationships with cardinality notation (||--o{, }o--o{, etc.). Step 2.5 -- Module Dependency Graph Generate a `graph TD` showing how internal modules depend on each other. Place entry points (routes/controllers) at top, data stores at bottom, external systems on sides. Flag circular dependencies as warnings. Use `style` directives to color-code layers. ============================================================ PHASE 3: OUTPUT AND ORGANIZATION ============================================================ Create `docs/diagrams/` directory if it does not exist. Write individual files: - `docs/diagrams/c4-context.md` -- C4 Context diagram - `docs/diagrams/c4-container.md` -- C4 Container diagram - `docs/diagrams/sequence-auth.md` -- Auth sequence (if applicable) - `docs/diagrams/sequence-[flow].md` -- Business flow sequence - `docs/diagrams/er-diagram.md` -- ER diagram (if database exists) - `docs/diagrams/dependency-graph.md` -- Module dependency graph Each file: heading, brief explanation, Mermaid code block, notes on simplifications. Skip diagram types with no data (no ER if no database). Generate `docs/diagrams/README.md` index linking all diagrams with descriptions. ============================================================ SELF-HEALING VALIDATION (max 2 iterations) ============================================================ After producing documentation, validate completeness: 1. Verify all required sections are present and non-empty. 2. Verify internal cross-references and links resolve correctly. 3. Verify no placeholder text remains ("{TODO}", "[TBD]", "...", "etc."). 4. Verify code examples are syntactically valid. IF VALIDATION FAILS: - Identify which sections are incomplete or contain placeholders - Re-generate only the deficient sections - Repeat up to 2 iterations ============================================================ OUTPUT ============================================================ ## Diagrams Generated ### System Profile - **Type:** [monolith / microservices / monorepo] - **Services:** [count] - **Database Tables:** [count] - **External Systems:** [count] ### Diagrams Created | Diagram | File | Entities | |---------|------|----------| | C4 Context | docs/diagrams/c4-context.md | N systems | | C4 Container | docs/diagrams/c4-container.md | N containers | | Sequence: Auth | docs/diagrams/sequence-auth.md | N participants | | ER Diagram | docs/diagrams/er-diagram.md | N tables | | Dependencies | docs/diagrams/dependency-graph.md | N modules | ### Observations - [Circular dependencies detected] - [Isolated modules with no connections] - [Missing relationships that could not be determined] ============================================================ SELF-EVOLUTION TELEMETRY ============================================================ After producing output, record execution metadata for the /evolve pipeline. Check if a project memory directory exists: - Look for the project path in `~/.claude/projects/` - If found, append to `skill-telemetry.md` in that memory directory Entry format: ``` ### /diagram — {{YYYY-MM-DD}} - Outcome: {{SUCCESS | PARTIAL | FAILED}} - Self-healed: {{yes — what was healed | no}} - Iterations used: {{N}} / {{N max}} - Bottleneck: {{phase that struggled or "none"}} - Suggestion: {{one-line improvement idea for /evolve, or "none"}} ``` Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals. ============================================================ DO NOT ============================================================ - Do NOT fabricate components, services, or tables. Only diagram what exists. - Do NOT include internal implementation details in C4 Context diagrams. - Do NOT generate diagrams for types with no data (no ER if no database). - Do NOT use PlantUML -- use Mermaid exclusively for GitHub compatibility. - Do NOT include sensitive info (credentials, internal URLs, IPs) in diagrams. - Do NOT overwrite existing diagram files without reading them first. NEXT STEPS: After generating diagrams: - "Run `/document` to check overall documentation health." - "Run `/adr` to create ADRs explaining architectural decisions shown in diagrams." - "Run `/onboarding` to include these diagrams in the developer onboarding guide."