@codihaus/claude-skills 1.0.0

package/skills/utils/diagram/references/diagram-types.md

@@ -0,0 +1,636 @@
+# Mermaid Diagram Types
+
+Complete syntax reference for all supported diagram types.
+
+## Quick Reference
+
+| Type | Keyword | Best For |
+|------|---------|----------|
+| Flowchart | `flowchart` | Process flows, decisions |
+| Sequence | `sequenceDiagram` | API interactions |
+| State | `stateDiagram-v2` | Status lifecycle |
+| ER Diagram | `erDiagram` | Database schema |
+| Class | `classDiagram` | Object structures |
+| Gantt | `gantt` | Project timelines |
+| Journey | `journey` | User experience |
+| Mindmap | `mindmap` | Hierarchical ideas |
+| Pie | `pie` | Distribution |
+| Timeline | `timeline` | Chronological events |
+| Git Graph | `gitGraph` | Version control |
+| Block | `block-beta` | System blocks |
+| **Architecture** | `architecture-beta` | Cloud/AWS diagrams |
+| Quadrant | `quadrantChart` | Priority matrix |
+| XY Chart | `xychart-beta` | Line/bar charts |
+| Sankey | `sankey-beta` | Flow visualization |
+| Packet | `packet-beta` | Network protocols |
+| C4 | `C4Context` | Software architecture |
+| Requirement | `requirementDiagram` | Requirements tracking |
+| Kanban | `kanban` | Task boards |
+
+---
+
+## Flowchart
+
+**Best for**: User journeys, decision trees, process flows.
+
+```mermaid
+flowchart LR
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action 1]
+    B -->|No| D[Action 2]
+    C --> E[End]
+    D --> E
+```
+
+**Directions**: `LR` (left-right), `TD` (top-down), `RL`, `BT`
+
+**Node shapes**:
+- `[text]` - Rectangle
+- `(text)` - Rounded
+- `{text}` - Diamond (decision)
+- `([text])` - Stadium
+- `[[text]]` - Subroutine
+- `[(text)]` - Cylinder (database)
+- `((text))` - Circle
+- `>text]` - Flag
+- `{{text}}` - Hexagon
+
+**Links**:
+- `-->` - Arrow
+- `---` - Line
+- `-.->` - Dotted arrow
+- `==>` - Thick arrow
+- `-->|text|` - Arrow with label
+- `--o` - Circle end
+- `--x` - Cross end
+
+**Subgraphs**:
+```mermaid
+flowchart TB
+    subgraph API[API Layer]
+        A1[Route] --> A2[Controller]
+    end
+    subgraph DB[Database]
+        D1[(PostgreSQL)]
+    end
+    A2 --> D1
+```
+
+---
+
+## Sequence Diagram
+
+**Best for**: API flows, multi-actor interactions.
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant API
+    participant DB
+
+    User->>API: Request
+    activate API
+    API->>DB: Query
+    DB-->>API: Result
+    API-->>User: Response
+    deactivate API
+```
+
+**Arrows**:
+- `->>` - Solid with arrowhead
+- `-->>` - Dotted with arrowhead
+- `-x` - Solid with cross (async)
+- `--x` - Dotted with cross
+
+**Features**:
+```mermaid
+sequenceDiagram
+    participant A
+    participant B
+
+    Note over A,B: Shared note
+
+    loop Every minute
+        A->>B: Heartbeat
+    end
+
+    alt Success
+        B-->>A: OK
+    else Failure
+        B-->>A: Error
+    end
+
+    opt Optional step
+        A->>B: Extra call
+    end
+
+    par Parallel
+        A->>B: Request 1
+    and
+        A->>B: Request 2
+    end
+```
+
+---
+
+## State Diagram
+
+**Best for**: Status lifecycle, state machines.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Review: Submit
+    Review --> Approved: Accept
+    Review --> Draft: Reject
+    Approved --> Published: Publish
+    Published --> [*]
+
+    state Review {
+        [*] --> Pending
+        Pending --> InProgress
+        InProgress --> Complete
+    }
+```
+
+---
+
+## ER Diagram
+
+**Best for**: Data relationships, database schema.
+
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ ORDER_ITEM : contains
+    PRODUCT ||--o{ ORDER_ITEM : "ordered in"
+
+    USER {
+        int id PK
+        string email UK
+        string name
+        datetime created_at
+    }
+    ORDER {
+        int id PK
+        int user_id FK
+        decimal total
+        string status
+    }
+```
+
+**Relationships**:
+- `||--||` - One to one
+- `||--o{` - One to many
+- `o{--o{` - Many to many
+- `|o--o|` - Zero or one
+
+---
+
+## Architecture Diagram (Cloud/AWS)
+
+**Best for**: Cloud infrastructure, AWS/GCP/Azure diagrams, CI/CD pipelines.
+
+### Basic Syntax
+
+```mermaid
+architecture-beta
+    group api(cloud)[API]
+
+    service db(database)[Database] in api
+    service server(server)[Server] in api
+    service disk(disk)[Storage] in api
+
+    db:L -- R:server
+    disk:T -- B:server
+```
+
+### Components
+
+**Groups** - Container for services:
+```
+group {id}({icon})[{label}]
+group {id}({icon})[{label}] in {parent}
+```
+
+**Services** - Individual components:
+```
+service {id}({icon})[{label}]
+service {id}({icon})[{label}] in {group}
+```
+
+**Edges** - Connections with direction (L/R/T/B):
+```
+{service1}:{side} -- {side}:{service2}
+{service1}:{side} --> {side}:{service2}    # with arrow
+```
+
+**Junctions** - 4-way connectors:
+```
+junction {id}
+junction {id} in {parent}
+```
+
+### Default Icons
+
+| Icon | Keyword |
+|------|---------|
+| Cloud | `cloud` |
+| Database | `database` |
+| Disk/Storage | `disk` |
+| Internet | `internet` |
+| Server | `server` |
+
+### AWS Architecture Example
+
+```mermaid
+architecture-beta
+    group aws(cloud)[AWS]
+
+    group vpc(cloud)[VPC] in aws
+    group public(cloud)[Public Subnet] in vpc
+    group private(cloud)[Private Subnet] in vpc
+
+    service internet(internet)[Internet]
+    service alb(server)[ALB] in public
+    service ec2(server)[EC2] in private
+    service rds(database)[RDS] in private
+    service s3(disk)[S3] in aws
+
+    internet:R --> L:alb
+    alb:R --> L:ec2
+    ec2:R --> L:rds
+    ec2:B --> T:s3
+```
+
+### Custom Icons (Iconify)
+
+For AWS-specific icons, register icon packs:
+```javascript
+// In your setup
+import { icons } from '@iconify-json/logos';
+mermaid.registerIconPacks([{ name: icons.prefix, icons }]);
+```
+
+Then use:
+```
+service lambda(logos:aws-lambda)[Lambda]
+service s3(logos:aws-s3)[S3 Bucket]
+service ec2(logos:aws-ec2)[EC2 Instance]
+service rds(logos:aws-aurora)[Aurora DB]
+```
+
+### CI/CD Pipeline Example
+
+```mermaid
+architecture-beta
+    group cicd(cloud)[CI/CD Pipeline]
+
+    service github(internet)[GitHub]
+    service ci(server)[CI Server] in cicd
+    service test(server)[Test Runner] in cicd
+    service deploy(server)[Deploy] in cicd
+    service prod(cloud)[Production]
+
+    github:R --> L:ci
+    ci:R --> L:test
+    test:R --> L:deploy
+    deploy:R --> L:prod
+```
+
+### Microservices Example
+
+```mermaid
+architecture-beta
+    group frontend(cloud)[Frontend]
+    group backend(cloud)[Backend Services]
+    group data(cloud)[Data Layer]
+
+    service web(server)[Web App] in frontend
+    service mobile(server)[Mobile API] in frontend
+
+    service auth(server)[Auth Service] in backend
+    service api(server)[API Gateway] in backend
+    service orders(server)[Orders] in backend
+    service payments(server)[Payments] in backend
+
+    service postgres(database)[PostgreSQL] in data
+    service redis(database)[Redis] in data
+    service s3(disk)[S3] in data
+
+    junction junc1 in backend
+
+    web:B --> T:api
+    mobile:B --> T:api
+    api:B --> T:junc1
+    junc1:L --> R:auth
+    junc1:R --> L:orders
+    junc1:B --> T:payments
+    orders:B --> T:postgres
+    auth:B --> T:redis
+    payments:B --> T:s3
+```
+
+---
+
+## Quadrant Chart
+
+**Best for**: Priority matrix, effort/impact analysis.
+
+```mermaid
+quadrantChart
+    title Priority Matrix
+    x-axis Low Effort --> High Effort
+    y-axis Low Impact --> High Impact
+    quadrant-1 Do First
+    quadrant-2 Schedule
+    quadrant-3 Delegate
+    quadrant-4 Eliminate
+
+    Feature A: [0.8, 0.9]
+    Feature B: [0.2, 0.8]
+    Feature C: [0.7, 0.3]
+    Feature D: [0.3, 0.2]
+```
+
+---
+
+## XY Chart
+
+**Best for**: Line charts, bar charts, trends.
+
+```mermaid
+xychart-beta
+    title "Monthly Revenue"
+    x-axis [Jan, Feb, Mar, Apr, May, Jun]
+    y-axis "Revenue (USD)" 0 --> 10000
+    bar [5000, 6000, 7500, 8200, 7800, 9200]
+    line [5000, 6000, 7500, 8200, 7800, 9200]
+```
+
+### Multi-series
+
+```mermaid
+xychart-beta
+    title "Sales Comparison"
+    x-axis [Q1, Q2, Q3, Q4]
+    y-axis "Sales" 0 --> 100
+    bar "Product A" [30, 45, 60, 80]
+    bar "Product B" [20, 35, 50, 70]
+    line "Target" [40, 50, 60, 70]
+```
+
+---
+
+## Sankey Diagram
+
+**Best for**: Flow visualization, resource allocation, conversion funnels.
+
+```mermaid
+sankey-beta
+
+Website,Signup,5000
+Website,Bounce,3000
+Signup,Free Trial,4000
+Signup,Direct Buy,1000
+Free Trial,Convert,2000
+Free Trial,Churn,2000
+```
+
+### Budget Flow Example
+
+```mermaid
+sankey-beta
+
+Revenue,Operations,40
+Revenue,Marketing,25
+Revenue,R&D,20
+Revenue,Admin,15
+Operations,Salaries,30
+Operations,Infrastructure,10
+Marketing,Ads,15
+Marketing,Events,10
+```
+
+---
+
+## Packet Diagram
+
+**Best for**: Network protocols, binary data formats.
+
+```mermaid
+packet-beta
+    0-15: "Source Port"
+    16-31: "Destination Port"
+    32-63: "Sequence Number"
+    64-95: "Acknowledgment Number"
+    96-99: "Data Offset"
+    100-105: "Reserved"
+    106-111: "Flags"
+    112-127: "Window Size"
+    128-143: "Checksum"
+    144-159: "Urgent Pointer"
+```
+
+---
+
+## C4 Diagram
+
+**Best for**: Software architecture at different abstraction levels.
+
+### Context
+
+```mermaid
+C4Context
+    title System Context
+
+    Person(user, "User", "End user of the system")
+    System(system, "Our System", "Main application")
+    System_Ext(email, "Email Service", "Sends emails")
+
+    Rel(user, system, "Uses")
+    Rel(system, email, "Sends emails via")
+```
+
+### Container
+
+```mermaid
+C4Container
+    title Container Diagram
+
+    Person(user, "User")
+
+    Container_Boundary(system, "System") {
+        Container(web, "Web App", "React", "Frontend")
+        Container(api, "API", "Node.js", "Backend")
+        ContainerDb(db, "Database", "PostgreSQL", "Stores data")
+    }
+
+    Rel(user, web, "Uses", "HTTPS")
+    Rel(web, api, "Calls", "REST")
+    Rel(api, db, "Reads/Writes", "SQL")
+```
+
+---
+
+## Mindmap
+
+**Best for**: Feature breakdown, brainstorming.
+
+```mermaid
+mindmap
+    root((Project))
+        Features
+            Auth
+                Login
+                Signup
+                OAuth
+            Payments
+                Checkout
+                Subscriptions
+                Refunds
+        Technical
+            Frontend
+                React
+                Tailwind
+            Backend
+                Node.js
+                PostgreSQL
+```
+
+---
+
+## Timeline
+
+**Best for**: Project phases, milestones, history.
+
+```mermaid
+timeline
+    title Project Roadmap
+    section Phase 1
+        2024-Q1 : Requirements
+                : Design
+    section Phase 2
+        2024-Q2 : Development
+                : Testing
+    section Phase 3
+        2024-Q3 : Beta Launch
+        2024-Q4 : GA Release
+```
+
+---
+
+## Journey
+
+**Best for**: User experience mapping, satisfaction tracking.
+
+```mermaid
+journey
+    title User Onboarding
+    section Discovery
+        Visit website: 5: User
+        Read docs: 4: User
+    section Signup
+        Create account: 3: User
+        Verify email: 2: User
+    section First Use
+        Complete tutorial: 4: User
+        Create first item: 5: User
+```
+
+Score: 1 (worst) to 5 (best)
+
+---
+
+## Pie Chart
+
+**Best for**: Distribution, percentages.
+
+```mermaid
+pie showData
+    title Traffic Sources
+    "Organic" : 45
+    "Direct" : 25
+    "Referral" : 20
+    "Social" : 10
+```
+
+---
+
+## Git Graph
+
+**Best for**: Branch strategies, version control flows.
+
+```mermaid
+gitGraph
+    commit id: "Initial"
+    branch develop
+    checkout develop
+    commit id: "Feature 1"
+    commit id: "Feature 2"
+    checkout main
+    merge develop id: "Release v1.0"
+    branch hotfix
+    commit id: "Fix bug"
+    checkout main
+    merge hotfix
+```
+
+---
+
+## Block Diagram
+
+**Best for**: System architecture blocks, layouts.
+
+```mermaid
+block-beta
+    columns 3
+
+    Frontend:3
+    block:backend:2
+        API
+        Worker
+    end
+    Cache
+    Database:2
+    Storage
+```
+
+---
+
+## Requirement Diagram
+
+**Best for**: Requirements tracking, traceability.
+
+```mermaid
+requirementDiagram
+    requirement user_auth {
+        id: REQ-001
+        text: Users must authenticate
+        risk: high
+        verifymethod: test
+    }
+
+    element login_page {
+        type: ui
+    }
+
+    login_page - satisfies -> user_auth
+```
+
+---
+
+## Tips
+
+1. **Keep diagrams focused** - One concept per diagram
+2. **Use meaningful IDs** - `userLogin` not `A`
+3. **Add labels** - Especially on decision branches
+4. **Test incrementally** - Validate after each addition
+5. **Use subgraphs/groups** - Organize complex diagrams
+6. **Match direction to reading** - LR for processes, TD for hierarchies
+
+## References
+
+- [Mermaid Official Docs](https://mermaid.js.org/)
+- [Architecture Diagrams](https://mermaid.js.org/syntax/architecture.html)
+- [Iconify Icons](https://iconify.design/)