usm/gen-mermaid

Mermaid diagram generator — produces architecture, ER, sequence, and service-dependency diagrams from .usm data.

Intent

Visual diagrams make the system structure immediately understandable. Mermaid diagrams render natively on GitHub and in most markdown viewers, providing zero-cost visualization of services, data models, and user flows.

Flows

Generate architecture diagram (arch-diagram)

Produce a C4-style architecture diagram from system + service .usm files

1. parse → system.usm and all service files
2. generate → architecture.mmd showing services and dependencies
3. submit → write to docs/diagrams/architecture.mmd

Flow Diagrams

sequenceDiagram
    participant User
    participant Browser
    participant Server

    User->>Browser: parse system.usm and all service files
    User->>Browser: generate architecture.mmd showing services and dependencies
    User->>Browser: submit write to docs/diagrams/architecture.mmd

Contracts

mermaid-valid-syntax

Generated Mermaid files must parse without syntax errors

Acceptance criteria:

• [ ] Special characters escaped (colons, pipes, brackets)
• [ ] Each diagram in its own .mmd file

Tests

arch-diagram-valid

Given:

• system_with_services: true

Then:

• assertion: architecture.mmd contains valid Mermaid flowchart syntax

er-diagram-valid

Given:

• data_models_present: true

Then:

• assertion: er-diagram.mmd contains erDiagram syntax

Implementation

• Primary: src/generators/mermaid.ts
• Test code status: none

See Also

• usm/cli-generate