Skip to content

mgiovani/ai-arsenal / skills/docs-diagram

docs-diagram

Verified

Generate a Mermaid diagram (ER, architecture, deployment, or security) by reading the actual codebase and writing it to docs/. Use for requests like "draw an ER diagram of these tables", "show me the architecture", "diagram the deployment setup", "visualize the security data flow", or "generate a system diagram". Not for scaffolding a new docs directory structure (use docs-init), syncing existing prose docs with code changes (use docs-update), or recording a design decision's rationale (use docs-adr), this skill only produces diagrams generated from code.

references/mermaid-patterns.md

View on GitHub
# Mermaid Patterns

Mermaid syntax reference for each supported diagram type.

## Contents

- [ER Diagram (`er`)](#er-diagram-er)
- [Architecture Diagram (`arch`)](#architecture-diagram-arch)
- [Deployment Diagram (`deployment`)](#deployment-diagram-deployment)
- [Security Diagram (`security`)](#security-diagram-security)
- [Example Output](#example-output)

## ER Diagram (`er`)

Entity-Relationship diagram from database models.

Detects: Tables and entities, columns with data types, primary keys, foreign keys, relationships, constraints.

```mermaid
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
    }
```

### Supported ORMs and what to extract

Python ORMs: SQLAlchemy, Django, Tortoise, SQLModel, Peewee

JS/TS ORMs: Prisma, TypeORM, Sequelize, Mongoose

Other: GORM (Go), ActiveRecord (Ruby)

Extract, per model: tables/entities, columns with types, relationships (one-to-one, one-to-many, many-to-many), and constraints (PK, FK, unique).

### For ER Diagrams Specifically

```
Agent 1 - Find Models:
- prompt: "Find all ORM model/entity files. Extract table names and column definitions."
- subagent_type: "Explore"

Agent 2 - Find Relationships:
- prompt: "In the model files found, identify all foreign keys and relationship decorators. Map actual relationships."
- subagent_type: "Explore"

Only include entities and relationships that both agents confirm exist.
```

## Architecture Diagram (`arch`)

System architecture and component relationships.

Detects: Services and modules, API endpoints, databases, caches, message queues, external services.

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

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

## Deployment Diagram (`deployment`)

Deployment infrastructure and CI/CD.

Detects: Docker containers, Kubernetes resources, cloud services, CI/CD pipeline stages, environment configurations.

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

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

## Security Diagram (`security`)

Security architecture and data flow.

Detects: Authentication flows, authorization boundaries, encryption points, security controls, trust boundaries.

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

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

## 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
```
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall