gh-mgiovani-cc-arsenal/commands/docs/diagram.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Generate Mermaid diagrams from codebase analysis	<type> [context]	Read Write Grep Glob

Generate System Diagrams

Generate Mermaid diagrams including architecture, database schema, deployment, and security architecture.

Your Task

1. Parse Arguments:

   • Extract diagram type from $ARGUMENTS
   • Supported types: er, arch, deployment, security
   • Extract optional context (remaining arguments)

2. Validate Diagram Type:

   • If type not provided or invalid, show available types
   • Exit with helpful message

3. Analyze Codebase (based on diagram type):

   For ER Diagrams (er):

   • Find ORM model files
   • Supported ORMs:
     • Python: SQLAlchemy, Django, Tortoise, SQLModel, Peewee
     • JS/TS: Prisma, TypeORM, Sequelize, Mongoose
     • Other: GORM (Go), ActiveRecord (Ruby)
   • Extract:
     • Tables/entities
     • Columns with types
     • Relationships (one-to-one, one-to-many, many-to-many)
     • Constraints (PK, FK, unique)

   For Architecture Diagrams (arch):

   • Identify major components
   • Find services, APIs, workers
   • Detect queues, caches, databases
   • Map data flow between components
   • Identify external dependencies

   For Deployment Diagrams (deployment):

   • Find deployment configs (docker-compose, k8s, etc.)
   • Identify services and their relationships
   • Map CI/CD pipeline
   • Document environment configurations

   For Security Diagrams (security):

   • Find authentication/authorization code
   • Map security boundaries
   • Identify data encryption points
   • Document security controls

4. Generate Mermaid Diagram:

   • Create appropriate Mermaid syntax based on type
   • Include meaningful labels and relationships
   • Add comments for clarity
   • Keep diagram readable (not too complex)

5. Load Template:

   • Template location: commands/docs/templates/
   • Select based on diagram type:
     • er → data-model.md
     • arch → architecture.md
     • deployment → deployment.md
     • security → security.md

6. Populate Template: Replace placeholders:

   • {{PROJECT_NAME}} - Git repo or directory name
   • {{DATE}} - Current date
   • {{ER_DIAGRAM}} or {{DIAGRAM_CONTENT}} - Generated Mermaid code
   • {{ENTITIES}} or {{COMPONENTS}} - Entity/component descriptions
   • Other diagram-specific placeholders

7. Create or Update Documentation:

   • Output to appropriate file in docs/
   • If file exists, ask before overwriting
   • Preserve custom content if possible

8. Report Results:

   • Show diagram type and output file
   • Display summary of what was detected
   • Provide next steps

Supported Diagram Types

ER Diagram (er)

Output: docs/data-model.md

Entity-Relationship diagram from database models.

Detects:

• Tables and entities
• Columns with data types
• Primary keys
• Foreign keys
• Relationships
• Constraints

Mermaid syntax:

erDiagram
    USER ||--o| PROFILE : "has"
    USER {
        uuid id PK
        string email UK
        string password_hash
    }
    PROFILE {
        uuid id PK
        uuid user_id FK
        string bio
    }

Architecture Diagram (arch)

Output: docs/architecture.md

System architecture and component relationships.

Detects:

• Services and modules
• API endpoints
• Databases
• Caches
• Message queues
• External services

Mermaid syntax:

graph TB
    Client[Web Client]
    API[API Server]
    DB[(Database)]
    Cache[(Redis)]

    Client --> API
    API --> DB
    API --> Cache

Deployment Diagram (deployment)

Output: docs/deployment.md

Deployment infrastructure and CI/CD.

Detects:

• Docker containers
• Kubernetes resources
• Cloud services
• CI/CD pipeline stages
• Environment configurations

Mermaid syntax:

graph LR
    Dev[Development]
    CI[CI Pipeline]
    Stage[Staging]
    Prod[Production]

    Dev --> CI
    CI --> Stage
    Stage --> Prod

Security Diagram (security)

Output: docs/security.md

Security architecture and data flow.

Detects:

• Authentication flows
• Authorization boundaries
• Encryption points
• Security controls
• Trust boundaries

Mermaid syntax:

graph TB
    User[User]
    Auth[Auth Service]
    API[Protected API]
    DB[(Encrypted DB)]

    User -->|JWT| Auth
    Auth -->|Validated| API
    API -->|TLS| DB

Usage

Generate specific diagram type:

/docs:diagram er
/docs:diagram arch
/docs:diagram deployment
/docs:diagram security

With additional context:

/docs:diagram er for user and order tables
/docs:diagram arch for microservices architecture
/docs:diagram deployment with Docker and Kubernetes

Show available types:

/docs:diagram

ORM Detection Examples

Python ORMs

# SQLAlchemy
!`find . -name "*models.py" -exec grep -l "Base\|Column\|relationship" {} \; | head -10`

# Django
!`find . -name "models.py" -exec grep -l "models.Model" {} \; | head -10`

# Tortoise ORM
!`find . -name "*.py" -exec grep -l "tortoise.models" {} \; | head -10`

JavaScript/TypeScript ORMs

# Prisma
!`find . -name "schema.prisma"`

# TypeORM
!`find . -name "*.entity.ts" -o -name "*entity.js" | head -10`

# Sequelize
!`find . -name "*.model.js" -o -name "*.model.ts" | head -10`

Architecture Detection Examples

# Find services
!`find . -name "*service*.ts" -o -name "*service*.py" -o -name "*service*.js" | head -15`

# Find API routes
!`find . -name "*router*.ts" -o -name "*routes*.py" -o -name "*controller*.js" | head -15`

# Find configs
!`find . -name "*.config.js" -o -name "*.config.ts" -o -name "config.py" | head -10`

Deployment Detection Examples

# Docker
!`find . -name "Dockerfile" -o -name "docker-compose.yml" -o -name "docker-compose.yaml"`

# Kubernetes
!`find . -name "*.k8s.yaml" -o -name "*.k8s.yml" -o -name "*deployment.yaml"`

# CI/CD
!`find . -name ".github/workflows/*.yml" -o -name ".gitlab-ci.yml" -o -name "Jenkinsfile"`

Important Notes

• Auto-detection: Diagrams generated from actual code
• Mermaid format: Uses GitHub-compatible Mermaid syntax
• Readable diagrams: Limits complexity for clarity
• Incremental: Can regenerate as code evolves
• Template-based: Uses templates for consistent formatting
• Context-aware: Uses optional context to guide generation

Example Output

ER Diagram Generated ✓

Detected: 5 entities, 12 relationships
File: docs/data-model.md

Entities Found:
  ✓ User (SQLAlchemy model)
  ✓ Profile (SQLAlchemy model)
  ✓ Role (SQLAlchemy model)
  ✓ Permission (SQLAlchemy model)
  ✓ UserRole (junction table)

Relationships:
  ✓ User → Profile (one-to-one)
  ✓ User → UserRole (one-to-many)
  ✓ Role → UserRole (one-to-many)
  ✓ Role → Permission (many-to-many)

Next Steps:
  1. Review generated ER diagram
  2. Add entity descriptions if needed
  3. Update when schema changes
  4. Reference in architecture docs

When to Run

Run when:

• Database schema has been modified (er)
• Architecture has evolved (arch)
• Deployment configuration changed (deployment)
• Security architecture modified (security)
• Onboarding new team members (all diagrams)
• Documentation review (all diagrams)

Best Practices

• Keep current: Regenerate after significant changes
• Review generated: Always review auto-generated content
• Add context: Supplement with manual descriptions
• Link diagrams: Reference diagrams in related docs
• Version control: Commit diagram updates with code changes
• Simplify: Break complex diagrams into multiple views

---

Template Location: commands/docs/templates/ Output Directory: docs/