Mermaid Data Flow Diagram Guide

# Mermaid Data Flow Diagram Guide

A data flow diagram explains where information enters a system, how it changes, where it is stored, and which services depend on it. For developer documentation, Mermaid is a strong fit because the diagram lives as text beside the API spec, data contract, README, or architecture decision record.

This guide shows how to create practical data flow diagrams with Mermaid. The examples cover APIs, databases, ETL jobs, event streams, third-party services, and security boundaries without requiring a separate drawing tool.

When to Use a Mermaid Data Flow Diagram

Use a Mermaid data flow diagram when readers need to answer questions like:

- What happens to a user event after it is collected?

- Which service writes to the source-of-truth database?

- Where does personally identifiable information move?

- What job transforms raw data into reporting tables?

- Which downstream systems depend on this API response?

Mermaid is especially useful when the diagram must stay current. A pull request can update code, schema changes, and the diagram in the same review.

Simple API Data Flow Diagram

Start with the main actors, services, and data stores. A flowchart is usually the clearest Mermaid diagram type for data movement.

flowchart LR
    Client["Web or mobile client"] -->|POST /orders| API["Orders API"]
    API -->|validate request| Rules["Business rules"]
    Rules -->|write order| Orders[("Orders database")]
    Rules -->|publish event| Bus["Event bus"]
    Bus --> Email["Email service"]
    Bus --> Warehouse[("Analytics warehouse")]

This is more useful than a component list because it shows direction. The reader can see which systems receive data synchronously and which systems are updated through events.

Show Inputs, Processes, and Stores

Classic data flow diagrams separate external entities, processes, and data stores. Mermaid does not enforce those shapes, but you can create a consistent convention.

flowchart TD
    User["External entity: Customer"] --> Checkout["Process: Checkout"]
    Checkout --> Payment["Process: Payment authorization"]
    Payment --> Ledger[("Data store: Payments ledger")]
    Checkout --> Orders[("Data store: Orders")]
    Orders --> Fulfillment["Process: Fulfillment"]
    Fulfillment --> Carrier["External entity: Shipping carrier"]

Use labels that explain roles, not implementation trivia. A node named Orders database is usually clearer than a generated cluster name or table prefix.

Data Pipeline Diagram

For ETL and analytics systems, show raw inputs, transformation steps, quality checks, and serving layers.

flowchart LR
    App["Application events"] --> Raw[("Raw event storage")]
    CRM["CRM export"] --> Raw
    Raw --> Validate["Validate schema"]
    Validate --> Clean["Clean and deduplicate"]
    Clean --> Model["Build reporting models"]
    Model --> Mart[("Analytics mart")]
    Mart --> BI["BI dashboards"]
    Mart --> ML["ML feature jobs"]

This style helps data teams explain ownership. If a dashboard breaks, readers can trace whether the problem likely started in ingestion, validation, modeling, or the serving layer.

Event-Driven Data Flow

Modern systems often move data through queues, streams, and webhooks. Mermaid makes fan-out and asynchronous delivery visible.

flowchart TB
    API["API service"] -->|OrderCreated| Stream["Kafka topic"]
    Stream --> Inventory["Inventory consumer"]
    Stream --> Billing["Billing consumer"]
    Stream --> Search["Search indexer"]

    Inventory --> Stock[("Inventory database")]
    Billing --> Invoices[("Invoices database")]
    Search --> Index[("Search index")]

    Stream --> DLQ["Dead-letter topic"]
    DLQ --> Alert["On-call alert"]

Include the dead-letter queue or failure topic when it matters operationally. Error paths are part of the data flow, not an implementation footnote.

Show Trust Boundaries and Sensitive Data

Data flow diagrams are often used in security reviews. Subgraphs can show ownership, networks, regions, or trust boundaries.

flowchart LR
    subgraph Public["Public internet"]
        Browser["Customer browser"]
        Vendor["Payment provider"]
    end

    subgraph App["Application boundary"]
        API["Checkout API"]
        Tokenizer["Tokenization service"]
        Orders[("Orders DB")]
    end

    subgraph Secure["Restricted data boundary"]
        Vault[("Payment token vault")]
    end

    Browser -->|cart + customer details| API
    API -->|card details| Vendor
    Vendor -->|payment token| Tokenizer
    Tokenizer --> Vault
    API --> Orders

If the diagram is for a threat model, label sensitive fields directly on edges: email address, payment token, IP address, medical record ID, or account identifier.

Mermaid Styling for Data Flow Diagrams

A small amount of styling can make a data flow diagram easier to scan.

flowchart LR
    Source["Data source"] --> Job["Transform job"]
    Job --> Store[("Warehouse table")]
    Store --> Report["Dashboard"]

    classDef external fill:#eef2ff,stroke:#4f46e5,color:#111827
    classDef process fill:#ecfeff,stroke:#0891b2,color:#111827
    classDef store fill:#fef3c7,stroke:#d97706,color:#111827

    class Source,Report external
    class Job process
    class Store store

Keep the palette simple. Color should communicate category or risk, not decorate every node independently.

Data Flow Diagram Checklist

Before publishing a Mermaid data flow diagram, check that it answers these questions:

1. What are the external data sources and destinations?
2. Which processes transform, validate, enrich, or filter the data?
3. Which databases, buckets, queues, or warehouses store it?
4. Are synchronous calls and asynchronous events easy to distinguish?
5. Are sensitive data fields and trust boundaries visible?
6. Does the diagram avoid secrets, credentials, and unnecessary internal IDs?
7. Will the diagram be updated when the schema or pipeline changes?

Final Recommendation

Use Mermaid for data flow diagrams that need to be reviewed and maintained by engineers. Flowcharts are flexible enough for API flows, ETL pipelines, event streams, and security reviews, while the text format keeps the diagram versioned with the system it describes.

A good Mermaid data flow diagram is selective. It does not show every class or every table. It shows how information moves, where it changes, and which teams or systems depend on it.