Uml Diagramming

Quality Rules

• Choose the minimal diagram type that fits the purpose.
• Limit size: roughly <25 nodes for Mermaid, <30 for PlantUML.
• Naming: Consistent, short names; qualifiers in notes if needed.
• Grouping: Use subgraphs (Mermaid) or packages/frames (PlantUML): e.g. Client, API, Services, DB.
• Sequence: Show key messages only; use alt/opt for branches. In Mermaid, put each sequenceDiagram statement on its own line (do not pack with ; — uml-mcp strict validation rejects that).
• Class: Include main attributes/methods; show relationships with multiplicities where known.
• State: Clear start and end; label transitions with events/guards.
• Activity: One start, one end; decisions as diamonds; label yes/no paths.
• If the request is ambiguous, make reasonable assumptions and note them in comments inside the diagram.

Process

1. Parse the prompt: extract entities, actions, relationships, lifelines, states, modules.
2. Choose Mermaid or PlantUML (see "Choosing Mermaid vs PlantUML").
3. Select the diagram form from the type mapping tables above.
4. Apply direction: default TB; LR for architecture/component/deployment/network.
5. Emit a single code block with the diagram script.
6. If the MCP generate_uml tool is available, call it with the produced diagram_type and code (e.g. diagram_type: "mermaid", "class", "sequence", "activity", "usecase" as appropriate). Prefer generate_uml_image when the user asked to show the diagram in chat.

Examples

Example 1 (Mermaid – login flow)

User request: "User login flow: enter credentials, API validates, DB check, return JWT or error."

sequenceDiagram
    actor User
    participant Client
    participant API
    participant DB
    User->>Client: Enter credentials
    Client->>API: Validate request
    API->>DB: Check credentials
    alt Valid
        DB-->>API: OK
        API-->>Client: JWT
        Client-->>User: Logged in
    else Invalid
        DB-->>API: Fail
        API-->>Client: Error
        Client-->>User: Show error
    end

Example 2 (PlantUML – login sequence)

User request: "Login: validate, DB check, JWT or error."

@startuml
title Login flow
actor User
participant "API" as API
database DB
User -> API : credentials
API -> DB : validate
alt valid
  DB --> API : OK
  API --> User : JWT
else invalid
  DB --> API : fail
  API --> User : error
end
@enduml

Example 3 (Mermaid – API call sequence)

User request: "Show me a Mermaid sequence diagram for an API call."

Use sequenceDiagram with participants such as Client, API, Auth, DB. Show request/response and optional alt for success/error. See uml://examples (key mermaid) or docs/diagrams/mermaid.md for sample text. Then call generate_uml("mermaid", code).

Example 4 (Mermaid – Gantt)

User request: "Generate a Gantt chart using Mermaid syntax."

Use a Mermaid gantt block with title, dateFormat, section, and tasks (with ids and durations or after). See uml://examples (key mermaid) or docs/diagrams/mermaid.md for a Gantt sample. Then call generate_uml("mermaid", code).

Convert class diagram to Mermaid

When the user asks to convert a class diagram (PlantUML or prose) into Mermaid:

1. Map each class to classDiagram syntax: class name, then lines for attributes/methods with + - #.
2. Map relationships: inheritance --|>, composition *--, aggregation o--, association -- with : label, dependency ..>.
3. Emit one Mermaid code block and call generate_uml("mermaid", code).

BPMN process model

When the user asks how to draw a BPMN process model:

• Describe core BPMN 2.0.2 elements: Start/End events, Task, Gateways (Exclusive, Parallel, Inclusive), Sequence Flow, Lanes, Pools.
• Point to the BPMN guide, uml://templates / uml://examples (key bpmn), and generate_uml with diagram_type bpmn for BPMN XML.

Additional Resources

For full diagram-type mappings and optional constraints (direction, detail_level, max_nodes, naming_style, group_by), see references/DIAGRAM-TYPES.md.