Mermaid Requirement Diagram: Document Requirements as Code

# Mermaid Requirement Diagram: Document Requirements as Code

Most teams manage requirements in sprawling spreadsheets, Jira tickets, or Word docs that go stale the moment a developer closes the tab. There's a better way. Mermaid's requirementDiagram type lets you define requirements, risks, and verification methods right next to your code — and render them as clean, linkable diagrams in any Markdown-aware tool.

This guide walks through everything you need to start using Mermaid requirement diagrams today.

What Is a Mermaid Requirement Diagram?

A requirementDiagram is a structured way to capture:

• Requirements — what the system must do
• Elements — the components that fulfill requirements
• Relationships — traces between requirements and elements (satisfies, contains, copies, derives, refines, verifies)

It's based loosely on SysML requirement diagrams but much simpler to write. The output is a visual map that shows *which part of your system fulfills which requirement*.

Basic Requirement Diagram Syntax

Here's a minimal example showing a login feature requirement:

requirementDiagram

requirement LoginRequirement {
  id: REQ-001
  text: The system shall authenticate users with email and password.
  risk: high
  verifymethod: test
}

element AuthService {
  type: component
  docref: src/auth/AuthService.ts
}

AuthService - satisfies -> LoginRequirement

Breaking this down:

• requirement block defines a named requirement with an id, description, risk level, and how it's verified.
• element block defines a system component (class, module, service, etc.).
• The arrow satisfies links the element to the requirement it fulfills.

Risk Levels and Verification Methods

Mermaid supports the following values out of the box:

Risk: Low, Medium, High

Verify method: Analysis, Demonstration, Inspection, Test

These map directly to standard systems-engineering terminology, making requirement diagrams useful for formal documentation as well as agile teams.

A Real-World Example: E-Commerce Checkout

Here's a fuller diagram tracing requirements for a checkout flow:

requirementDiagram

requirement PaymentProcessing {
  id: REQ-010
  text: The system shall process credit card payments via Stripe.
  risk: high
  verifymethod: test
}

requirement OrderConfirmation {
  id: REQ-011
  text: The system shall send an order confirmation email within 30 seconds.
  risk: medium
  verifymethod: demonstration
}

requirement AuditLogging {
  id: REQ-012
  text: All payment events shall be logged for audit purposes.
  risk: high
  verifymethod: inspection
}

element StripeGateway {
  type: component
  docref: src/payments/StripeGateway.ts
}

element EmailService {
  type: component
  docref: src/notifications/EmailService.ts
}

element AuditLogger {
  type: component
  docref: src/logging/AuditLogger.ts
}

StripeGateway - satisfies -> PaymentProcessing
EmailService - satisfies -> OrderConfirmation
AuditLogger - satisfies -> AuditLogging
AuditLogging - contains -> PaymentProcessing

Notice the contains relationship — it shows that audit logging is a sub-requirement of payment processing. Mermaid supports these relationship types:

Linking Requirements to Your Codebase

The docref field on elements is key. Set it to the file path of the actual implementation:

requirementDiagram

requirement DataEncryption {
  id: SEC-001
  text: All PII data shall be encrypted at rest using AES-256.
  risk: high
  verifymethod: inspection
}

element DatabaseLayer {
  type: component
  docref: src/db/EncryptedRepository.ts
}

element ConfigStore {
  type: component
  docref: config/encryption.yaml
}

DatabaseLayer - satisfies -> DataEncryption
ConfigStore - satisfies -> DataEncryption

When this diagram lives in your repo's docs/requirements.md, any developer can instantly see *which files* handle a given compliance requirement. No ticket archaeology required.

Where to Use Requirement Diagrams

Architecture Decision Records (ADRs): Embed a requirementDiagram to show which components satisfy each architectural constraint.

GitHub / GitLab README: Requirement diagrams render natively in both platforms. Drop one in your project README to give new contributors instant context.

Confluence and Notion: Both support Mermaid blocks. Use requirement diagrams in your technical spec pages to replace static tables.

Sprint planning: Create a lightweight diagram per sprint showing which requirements the team will satisfy — link it to your Jira epics via the id field.

Tips for Better Requirement Diagrams

1. Use consistent ID prefixes — REQ- for features, SEC- for security, PERF- for performance. Makes search easy.
2. Keep text concise — Use "shall" language (ISO/IEC 29148 style). One requirement per block.
3. Set risk honestly — High-risk requirements are where your tests should be densest.
4. Commit the diagram file — Store .mmd files in docs/diagrams/ so they're versioned with the code.
5. Regenerate on CI — Pair with mmdc in your pipeline to auto-export SVGs so docs stay current.

Requirement Diagrams vs. Other Approaches

For most software teams, Mermaid hits the sweet spot: formal enough to be useful, lightweight enough to actually maintain.

Try It Now

The fastest way to experiment with requirement diagrams is mermaideditor.lol — paste any of the examples above and see them render instantly. No install, no signup.

Once you're happy with a diagram, copy the Mermaid source into your README, wiki, or docs/ folder. Your requirements are now living documentation — always in sync, always readable, always free.

Requirements as code isn't just a nice idea. With Mermaid, it's three lines of syntax away.