Mermaid Diagrams in Specsource

Specsource now renders Mermaid diagrams in the Data Flows editor. You write a diagram as text, a lightweight DSL for the common sequence case or raw Mermaid for any other type, and it renders live next to the rest of the spec. Here is what that covers and where to find it.

What are Mermaid diagrams

Mermaid is a text-based diagramming syntax. You describe a diagram in plain text and a renderer turns it into an SVG, rather than drawing it by hand on a canvas. Because the source is text, it can live in a document, be version-controlled, and be read by tools and agents.

Specsource renders any diagram type Mermaid supports, including:

• sequence diagrams
• flowcharts (flowchart or graph)
• entity-relationship diagrams (erDiagram)
• state diagrams (stateDiagram-v2)
• class diagrams
• C4 context diagrams (C4Context)
• user journeys, Gantt charts, pie charts, mindmaps, timelines, gitGraph, quadrant, requirement, block and sankey diagrams

Syntax errors are surfaced inline rather than rendering an empty diagram.

Writing them: the DSL or raw Mermaid

The text field accepts two things.

The lightweight sequence DSL covers the common case, a sequence of calls between services. You write one line per message:

Client -> Auth Service: POST /login
Auth Service -> Database: Validate credentials
Database --> Auth Service: User record
Auth Service --> Client: 200 { token }

A solid arrow (->) is a call, a dashed arrow (-->) is a response, and the text after the colon is the message. Specsource compiles this into a Mermaid sequence diagram and works out the participants for you.

Raw Mermaid covers everything else. If the text begins with a Mermaid diagram header, such as flowchart, erDiagram or stateDiagram-v2, it is passed straight to Mermaid unchanged, so you can write any diagram type directly.

Examples

The sequence DSL above renders as:

A flowchart, written as raw Mermaid:

An entity-relationship diagram, also raw Mermaid:

These are rendered by the same component the app uses, so this is what they look like in a project.

How to access and use them

1. Open a project and go to Data Flows, under Design in the sidebar.
2. Create a data flow, or open an existing one.
3. Type the DSL or Mermaid into the text field. The preview renders as you type and reports syntax errors inline.
4. Save. The diagram is stored as text on the data flow, alongside the features and decisions it relates to.

Because it is stored as text, a data flow is versioned with the rest of the spec and can be read by an AI agent over MCP, the same as any other entity. Architects and engineers use the same editor: write the flow once, and it is available both as a rendered diagram in the app and as text to anything that reads the project.