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

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 (colons, pipes, brackets)
• [ ] 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: 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