USM

Appearance

usm/gen-mermaid ​

Mermaid diagram generator — produces architecture, ER, sequence, and service-dependency diagrams from .usm data. The ER section is built as a pure function of the Prisma schema and composed into data/models.md by the markdown generator (single writer).

Why this exists ​

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.

How it works ​

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 ​

mermaid
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

Guarantees ​

mermaid-valid-syntax ​

Generated Mermaid files must parse without syntax errors

Acceptance criteria:

  • [ ] Special characters escaped using single-pass Mermaid entity codes (#<code>😉 — never chained HTML-entity replaces that re-escape '#' or leave a bare ';' in sequenceDiagram message text
  • [ ] Semicolons in spec text itself are escaped (#59;) because a raw ';' is a statement separator in sequenceDiagram
  • [ ] Escape applied per diagram type: quoted labels for flowcharts, entity-code text for sequenceDiagram messages and notes
  • [ ] Each participant declared exactly once — alias form ('participant X as Alias') where an alias exists, no redundant bare participant line
  • [ ] Explicit step.actor is honoured in arrows: 'system'/'agent' map to the Server participant, persona ids become their own sanitized participant, actor-less steps keep the historical User/Browser arrows
  • [ ] Each diagram in its own .mmd file

er-section-is-pure ​

The ER diagram section must be a pure function of the Prisma schema, never of prior on-disk output

Acceptance criteria:

  • [ ] buildERDiagramSection(root) reads only packages/db/prisma/schema.prisma
  • [ ] generateDataModelDoc is the sole writer of .usm-workspace/docs/data/models.md
  • [ ] No generator reads a file it is about to overwrite

Test specifications ​

arch-diagram-valid ​

Given:

  • system_with_services: true

Then:

  • assertion: sequenceDiagram messages contain no double-escaped sequences (no '&#') and no bare ' ;' outside entity codes
  • assertion: messages containing ' | & < > " ; ( ) [ ] { } parse via mermaid parse/mmdc without syntax errors

er-diagram-valid ​

Given:

  • data_models_present: true

Then:

  • assertion: er-diagram.mmd contains erDiagram syntax

seq-escape-issue-49 ​

Given:

  • feature_flow_with_special_chars: true

Then:

  • assertion: flow step target containing ' : ; | & < > " ( ) [ ] { } generates sequenceDiagram message text using Mermaid entity codes (#39; #58; #59; ...) with no double escaping
  • assertion: aliased participant (IdP as Identity Provider) is declared exactly once — no redundant bare participant line
  • assertion: step.actor 'system'/'agent' renders Server arrows; persona actors render their own participant; actor-less steps keep User/Browser arrows

Implementation ​

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

See Also ​

  • usm/cli-generate