Mermaid Overview Diagrams

Rules

• prefer flowchart (graph) with TD or LR direction
• wrap in ```mermaid fenced code block
• use stadium-shaped nodes: ([text])
• use meaningful node IDs reflecting component names
• use --> for dependencies, -.-> for optional/async dependencies
• label arrows only when ambiguous: Gateway -->|routes| Service
• visualize only high-level concepts — omit classes, methods, implementation details
• use subgraphs for logical grouping (subsystems)
• write diagram into the target file (e.g. README.md) when context is clear

Mapping Selection

• pick the shape mapping matching the architecture the user named or the composed skill implies:
  • BCE business components, or sdd4j-bce in context → BCE mapping
  • technical layer packages, or sdd4j-package-by-layer in context → Package By Layer mapping
  • feature/capability packages, or sdd4j-package-by-feature in context → Package By Feature mapping
  • ports-and-adapters layout, or sdd4j-hexagonal in context → Hexagonal mapping
• when invoked via diagrams, use the architecture it detected — the router is architecture-neutral
• no clear architecture → use the Default mapping
• never mix mappings inside one diagram

Palette

Colors carry the same meaning across all mappings:

Default Mapping

Use when no architecture mapping applies.

classDef comp fill:#dae8fc,stroke:#6c8ebf,color:#000
classDef ext fill:#fff2cc,stroke:#d6b656,color:#000,stroke-dasharray:5 5

BCE Mapping

classDef bc fill:#dae8fc,stroke:#6c8ebf,color:#000
classDef ext fill:#fff2cc,stroke:#d6b656,color:#000,stroke-dasharray:5 5
classDef boundary fill:#d5e8d4,stroke:#82b366,color:#000
classDef control fill:#e1d5e7,stroke:#9673a6,color:#000
classDef entity fill:#fff2cc,stroke:#d6b656,color:#000

Package By Layer Mapping

Layers are subgraphs; nodes are the capability's classes inside each layer.

classDef cap fill:#dae8fc,stroke:#6c8ebf,color:#000
classDef ext fill:#fff2cc,stroke:#d6b656,color:#000,stroke-dasharray:5 5
classDef entrypoint fill:#d5e8d4,stroke:#82b366,color:#000
classDef application fill:#e1d5e7,stroke:#9673a6,color:#000
classDef domain fill:#fff2cc,stroke:#d6b656,color:#000
classDef infrastructure fill:#f5f5f5,stroke:#666666,color:#000

Package By Feature Mapping

Nodes are feature packages; subgraphs group by module or base package. Drawing inside a feature package reuses the layer classes from the Package By Layer mapping.

classDef cap fill:#dae8fc,stroke:#6c8ebf,color:#000
classDef shared fill:#f5f5f5,stroke:#666666,color:#000,stroke-dasharray:5 5
classDef ext fill:#fff2cc,stroke:#d6b656,color:#000,stroke-dasharray:5 5

Hexagonal (Ports & Adapters) Mapping

Nodes are adapters, ports, use cases, and domain types; the capability core is a subgraph (the hexagon boundary) or a hexagon node. Prefer graph LR and draw driving side left, driven side right. Edges show call flow through ports — interface indirection is elided.

classDef cap fill:#dae8fc,stroke:#6c8ebf,color:#000
classDef driving fill:#d5e8d4,stroke:#82b366,color:#000
classDef port fill:#e1d5e7,stroke:#9673a6,color:#000
classDef application fill:#e1d5e7,stroke:#9673a6,color:#000
classDef domain fill:#fff2cc,stroke:#d6b656,color:#000
classDef driven fill:#f5f5f5,stroke:#666666,color:#000
classDef ext fill:#fff2cc,stroke:#d6b656,color:#000,stroke-dasharray:5 5

Example — BCE Between Components

graph LR
    subgraph Billing
        Orders([Orders]) -->|charges| Payments([Payments])
    end
    Orders -.->|async| Notifications([Notifications])
    Payments -->|REST| PayGW([Payment Gateway])

    classDef bc fill:#dae8fc,stroke:#6c8ebf,color:#000
    classDef ext fill:#fff2cc,stroke:#d6b656,color:#000,stroke-dasharray:5 5
    class Orders,Payments,Notifications bc
    class PayGW ext

Example — Package By Layer

graph TD
    subgraph Entrypoints
        CheckoutResource([CheckoutResource])
    end
    subgraph Application
        CheckoutService([CheckoutService])
    end
    subgraph Domain
        Order([Order])
    end
    subgraph Infrastructure
        OrderRepository([OrderRepository])
    end
    CheckoutResource --> CheckoutService
    CheckoutService --> Order
    CheckoutService --> OrderRepository
    CheckoutService -.->|events| Broker([Message Broker])

    classDef entrypoint fill:#d5e8d4,stroke:#82b366,color:#000
    classDef application fill:#e1d5e7,stroke:#9673a6,color:#000
    classDef domain fill:#fff2cc,stroke:#d6b656,color:#000
    classDef infrastructure fill:#f5f5f5,stroke:#666666,color:#000
    classDef ext fill:#fff2cc,stroke:#d6b656,color:#000,stroke-dasharray:5 5
    class CheckoutResource entrypoint
    class CheckoutService application
    class Order domain
    class OrderRepository infrastructure
    class Broker ext

Example — Package By Feature

graph LR
    subgraph Ordering
        Checkout([Checkout]) -->|reserves| Inventory([Inventory])
        Checkout -->|charges| Payments([Payments])
    end
    Checkout --> Shared([Shared Kernel])
    Payments -.->|events| Notifications([Notifications])
    Payments -->|REST| PayGW([Payment Gateway])

    classDef cap fill:#dae8fc,stroke:#6c8ebf,color:#000
    classDef shared fill:#f5f5f5,stroke:#666666,color:#000,stroke-dasharray:5 5
    classDef ext fill:#fff2cc,stroke:#d6b656,color:#000,stroke-dasharray:5 5
    class Checkout,Inventory,Payments,Notifications cap
    class Shared shared
    class PayGW ext

Example — Hexagonal Inside a Component

graph LR
    OrderResource(["OrderResource"])
    subgraph Checkout
        PlaceOrder(["PlaceOrderUseCase"])
        CheckoutService(["CheckoutService"])
        Order(["Order"])
        LoadOrderPort(["LoadOrderPort"])
        ChargePort(["ChargePaymentPort"])
    end
    OrderPersistence(["OrderPersistenceAdapter"])
    PaymentClient(["PaymentClient"])
    DB(["Database"])
    PayGW(["Payment Gateway"])

    OrderResource -->|REST| PlaceOrder
    PlaceOrder --> CheckoutService
    CheckoutService --> Order
    CheckoutService --> LoadOrderPort
    CheckoutService --> ChargePort
    LoadOrderPort --> OrderPersistence
    ChargePort --> PaymentClient
    OrderPersistence -->|JPA| DB
    PaymentClient -->|REST| PayGW

    classDef driving fill:#d5e8d4,stroke:#82b366,color:#000
    classDef port fill:#e1d5e7,stroke:#9673a6,color:#000
    classDef application fill:#e1d5e7,stroke:#9673a6,color:#000
    classDef domain fill:#fff2cc,stroke:#d6b656,color:#000
    classDef driven fill:#f5f5f5,stroke:#666666,color:#000
    classDef ext fill:#fff2cc,stroke:#d6b656,color:#000,stroke-dasharray:5 5
    class OrderResource driving
    class PlaceOrder,LoadOrderPort,ChargePort port
    class CheckoutService application
    class Order domain
    class OrderPersistence,PaymentClient driven
    class DB,PayGW ext