Invoke docs-management skill for UML standards guidance
Verify diagram syntax using appropriate notation (PlantUML/Mermaid)
Base all guidance on UML 2.5 specification

UML Diagram Types

Structural Diagrams

Diagram	Purpose	When to Use
Class	Show classes, attributes, methods, relationships	Domain modeling, design
Component	Show components and dependencies	Architecture documentation
Deployment	Show physical deployment	Infrastructure planning
Object	Show object instances	Specific scenarios
Package	Show namespaces/modules	Code organization

Behavioral Diagrams

Diagram	Purpose	When to Use
Use Case	Show actor-system interactions	Requirements
Sequence	Show message flow over time	API design, protocols
Activity	Show workflows and processes	Business processes
State Machine	Show state transitions	Lifecycle modeling
Communication	Show object interactions	Design patterns

Class Diagram

PlantUML Syntax

@startuml
skinparam classAttributeIconSize 0

abstract class Entity {
  +Id: Guid
  +CreatedAt: DateTimeOffset
  +UpdatedAt: DateTimeOffset
}

class Order extends Entity {
  -_lineItems: List<LineItem>
  +CustomerId: Guid
  +Status: OrderStatus
  +Total: Money
  --
  +AddItem(product: Product, quantity: int): Result<LineItem>
  +RemoveItem(lineItemId: Guid): Result
  +Submit(): Result
  +Cancel(): Result
}

class LineItem extends Entity {
  +ProductId: Guid
  +ProductName: string
  +Quantity: int
  +UnitPrice: Money
  +LineTotal: Money
}

enum OrderStatus {
  Draft
  Submitted
  Paid
  Shipped
  Delivered
  Cancelled
}

class Money <<value object>> {
  +Amount: decimal
  +Currency: string
  +{static} Zero: Money
  +Add(other: Money): Money
  +Multiply(factor: decimal): Money
}

Order "1" *-- "0..*" LineItem : contains
Order --> OrderStatus
Order --> Money
LineItem --> Money

@enduml

Mermaid Class Diagram

classDiagram
    class Entity {
        <<abstract>>
        +Guid Id
        +DateTimeOffset CreatedAt
        +DateTimeOffset UpdatedAt
    }

    class Order {
        -List~LineItem~ _lineItems
        +Guid CustomerId
        +OrderStatus Status
        +Money Total
        +AddItem(Product, int) Result~LineItem~
        +RemoveItem(Guid) Result
        +Submit() Result
        +Cancel() Result
    }

    class LineItem {
        +Guid ProductId
        +string ProductName
        +int Quantity
        +Money UnitPrice
        +Money LineTotal
    }

    class OrderStatus {
        <<enumeration>>
        Draft
        Submitted
        Paid
        Shipped
        Delivered
        Cancelled
    }

    Entity <|-- Order
    Entity <|-- LineItem
    Order "1" *-- "0..*" LineItem : contains
    Order --> OrderStatus

Relationship Types

// UML Relationship Reference
public static class UMLRelationships
{
    // Association: uses, knows about
    // Customer --> Order (Customer uses Order)

    // Aggregation: has-a (shared ownership)
    // Team o-- Player (Team has Players, Players can exist independently)

    // Composition: contains (exclusive ownership)
    // Order *-- LineItem (Order contains LineItems, LineItems cannot exist without Order)

    // Inheritance: is-a
    // Dog --|> Animal (Dog extends Animal)

    // Implementation: implements
    // UserService ..|> IUserService (UserService implements IUserService)

    // Dependency: depends on
    // Controller ..> Service (Controller depends on Service)
}

Sequence Diagram

PlantUML Syntax

@startuml
title Order Submission Flow

actor Customer
participant "API Gateway" as API
participant "Order Service" as Orders
participant "Payment Service" as Payment
participant "Notification Service" as Notify
database "Order DB" as DB
queue "Message Bus" as Bus

Customer -> API: POST /orders/{id}/submit
activate API

API -> Orders: SubmitOrder(orderId)
activate Orders

Orders -> DB: GetOrder(orderId)
activate DB
DB --> Orders: Order
deactivate DB

alt Order is valid
    Orders -> Payment: ProcessPayment(order)
    activate Payment

    Payment --> Orders: PaymentResult
    deactivate Payment

    alt Payment successful
        Orders -> DB: UpdateStatus(Paid)
        Orders -> Bus: Publish(OrderSubmitted)
        Bus -> Notify: OrderSubmitted
        activate Notify
        Notify -> Notify: SendConfirmation()
        deactivate Notify

        Orders --> API: Success
        API --> Customer: 200 OK
    else Payment failed
        Orders --> API: PaymentFailed
        API --> Customer: 402 Payment Required
    end
else Order invalid
    Orders --> API: ValidationError
    API --> Customer: 400 Bad Request
end

deactivate Orders
deactivate API

@enduml

Mermaid Sequence Diagram

sequenceDiagram
    participant C as Customer
    participant A as API Gateway
    participant O as Order Service
    participant P as Payment Service
    participant D as Database

    C->>A: POST /orders/{id}/submit
    activate A
    A->>O: SubmitOrder(orderId)
    activate O
    O->>D: GetOrder(orderId)
    D-->>O: Order

    alt Order valid
        O->>P: ProcessPayment(order)
        P-->>O: PaymentResult

        alt Payment successful
            O->>D: UpdateStatus(Paid)
            O-->>A: Success
            A-->>C: 200 OK
        else Payment failed
            O-->>A: PaymentFailed
            A-->>C: 402 Payment Required
        end
    else Order invalid
        O-->>A: ValidationError
        A-->>C: 400 Bad Request
    end

    deactivate O
    deactivate A

Activity Diagram

PlantUML Syntax

@startuml
title Order Processing Workflow

start

:Customer submits order;

:Validate order;

if (Order valid?) then (yes)
  :Calculate totals;
  :Reserve inventory;

  fork
    :Process payment;
  fork again
    :Send confirmation email;
  end fork

  if (Payment successful?) then (yes)
    :Confirm inventory;
    :Create shipment;
    :Update order status;
    stop
  else (no)
    :Release inventory;
    :Notify customer;
    stop
  endif
else (no)
  :Return validation errors;
  stop
endif

@enduml

Use Case Diagram

PlantUML Syntax

@startuml
left to right direction

actor Customer
actor "Warehouse Staff" as Warehouse
actor Admin

rectangle "E-Commerce System" {
  usecase "Browse Products" as UC1
  usecase "Add to Cart" as UC2
  usecase "Checkout" as UC3
  usecase "Track Order" as UC4
  usecase "Process Refund" as UC5
  usecase "Manage Inventory" as UC6
  usecase "Fulfill Order" as UC7
  usecase "Generate Reports" as UC8

  Customer --> UC1
  Customer --> UC2
  Customer --> UC3
  Customer --> UC4
  Customer --> UC5

  Warehouse --> UC6
  Warehouse --> UC7

  Admin --> UC6
  Admin --> UC8

  UC3 ..> UC2 : <<include>>
  UC5 ..> UC4 : <<extend>>
}

@enduml

State Machine Diagram

PlantUML Syntax

@startuml
title Order State Machine

[*] --> Draft : Create

Draft --> Submitted : Submit
Draft --> Cancelled : Cancel

Submitted --> Paid : PaymentReceived
Submitted --> Cancelled : Cancel
Submitted --> Draft : RequiresChanges

Paid --> Shipped : Ship
Paid --> Refunded : Refund

Shipped --> Delivered : Deliver
Shipped --> Returned : Return

Delivered --> Completed : Finalize
Delivered --> Returned : Return

Returned --> Refunded : ProcessReturn

Completed --> [*]
Refunded --> [*]
Cancelled --> [*]

@enduml

Mermaid State Diagram

stateDiagram-v2
    [*] --> Draft : Create

    Draft --> Submitted : Submit
    Draft --> Cancelled : Cancel

    Submitted --> Paid : PaymentReceived
    Submitted --> Cancelled : Cancel
    Submitted --> Draft : RequiresChanges

    Paid --> Shipped : Ship
    Paid --> Refunded : Refund

    Shipped --> Delivered : Deliver
    Shipped --> Returned : Return

    Delivered --> Completed : Finalize
    Delivered --> Returned : Return

    Returned --> Refunded : ProcessReturn

    Completed --> [*]
    Refunded --> [*]
    Cancelled --> [*]

Component Diagram

PlantUML Syntax

@startuml
title System Components

package "Presentation Layer" {
  [Web Application] as Web
  [Mobile App] as Mobile
}

package "API Layer" {
  [API Gateway] as Gateway
  [GraphQL Server] as GraphQL
}

package "Business Layer" {
  [Order Service] as Orders
  [Payment Service] as Payment
  [Notification Service] as Notify
  [User Service] as Users
}

package "Data Layer" {
  database "Order DB" as OrderDB
  database "User DB" as UserDB
  queue "Message Bus" as Bus
}

package "External" {
  [Payment Provider] as PaymentExt
  [Email Service] as EmailExt
}

Web --> Gateway
Mobile --> Gateway
Gateway --> GraphQL
Gateway --> Orders
Gateway --> Users

Orders --> OrderDB
Orders --> Bus
Users --> UserDB

Payment --> PaymentExt
Notify --> EmailExt
Notify --> Bus

@enduml

Best Practices

General Guidelines

Keep diagrams focused: One concept per diagram
Use consistent notation: Choose PlantUML or Mermaid per project
Add meaningful names: Clear, descriptive labels
Include legends: For complex diagrams
Version control: Store in repository with code

Diagram Selection Guide

Need	Diagram Type
Data structures, domain model	Class Diagram
API flow, protocols	Sequence Diagram
Business processes	Activity Diagram
Actor interactions	Use Case Diagram
Lifecycle, state transitions	State Machine
System structure	Component Diagram
Infrastructure	Deployment Diagram

Workflow

When creating UML diagrams:

Identify purpose: What question does the diagram answer?
Select diagram type: Choose most appropriate type
Draft in text: Use PlantUML or Mermaid notation
Review for accuracy: Verify against code/requirements
Add context: Title, notes, legend as needed
Render and verify: Ensure diagram renders correctly

References

For detailed notation guides:

Last Updated: 2025-12-26

uml-modeling

UML Modeling Skill

When to Use This Skill

Overview

MANDATORY: Documentation-First Approach