DFD

References:

• https://miro.com/diagramming/what-is-a-data-flow-diagram/ — components, levels, logical vs physical.
• https://www.visual-paradigm.com/guide/data-flow-diagram/what-is-data-flow-diagram/ — drawing rules, balancing.

A DFD shows where data moves and what transforms it. Sequencing belongs in a flowchart, object structure in UML; a DFD carries neither. Control signals are not data — leave them out.

Components

Four, and only four:

Component	Is	Gane–Sarson	Yourdon/DeMarco	Mermaid
External entity	A source or sink outside the system boundary	square	rectangle	E[Name]
Process	Work that transforms input data into output data	rounded rectangle	circle	P(1.0 Verb the thing)
Data store	Data at rest — a file, table, queue, keyring	open-ended rectangle	two parallel lines	S[(Name)]
Data flow	Named data moving between the above	labelled arrow	labelled arrow	A -->|data name| B

Name every element. Entities and stores take noun phrases, processes take verb phrases, flows take the name of the data itself (plaintext token), never the mechanism carrying it.

Levels

Each level decomposes one process from the level above.

• Context — the whole system as a single process numbered 0, surrounded by every external entity it exchanges data with. No data stores; internal storage is inside the system.
• Level 0 — process 0 opened up into its major processes, numbered 1.0, 2.0, 3.0. Data stores appear here first.
• Level 1 onward — one process from the level above opened up, numbered beneath it. Decomposing 2.0 gives 2.1, 2.2; decomposing 2.1 gives 2.1.1.

Stop at the level that answers the question asked, or at a process whose decomposition would only restate it.

Pick logical or physical per diagram and hold it: a logical DFD names business activities, a physical one names the software, hosts, and files doing the work.

Rules

Drawing:

• Every process consumes and produces, and its inputs account for its outputs. Input with no output is a black hole, output with no input a miracle, output the inputs can't account for a grey hole. Each is a missing flow or a wrong boundary.
• Data flows through a process. Store-to-store, entity-to-entity, and entity-to-store flows all need a process between them, because stores and entities are passive.
• Every flow has a labelled direction. A bidirectional arrow is two flows carrying two different pieces of data; draw both.

Balancing:

• A child diagram's inflows and outflows match its parent process's exactly — same set, same names.
• Only boundary-crossing flows balance; flows internal to the decomposition are new at the child level.
• Renaming a flow at one level renames it at every level it appears.

Currency:

• The diagram matches the system. Update it in the same change that adds, removes, or retunes an element it shows.

Output

Mermaid flowchart, fenced inline in the markdown document. Renders on GitHub with no export step and no tool to install. Classic node shapes only — the A@{ shape: ... } extended syntax needs a Mermaid version the renderer may not have.

flowchart LR
  user[User]
  mcp[Third-party MCP server]

  subgraph host[Workstation]
    decrypt(1.0 Decrypt secret)
    key[(age identity)]
  end

  user -->|passphrase| decrypt
  key -->|identity| decrypt
  decrypt -->|plaintext token| mcp

Trust boundaries are an overlay, not a fifth component. Draw them on DFDs for security work, where crossing one is the finding: one subgraph per boundary, named for who or what controls that side.

Location

A DFD explains a system, so it is a Diátaxis explanation — under docs/explanation/, and the diataxis skill owns the surrounding prose. Keep every level of one system's DFD in one file, each level under its own heading, so balancing is checkable in a single read.

Procedure

Draw:

1. Fix the system boundary — what is inside, which external entities exchange data with it, and, for security work, which trust boundaries the data crosses. Draw the context diagram.
2. List what each process consumes and produces before drawing its flows. A process whose two lists you can't complete is the wrong process, or sits on the wrong side of the boundary.
3. Decompose to Level 0, then further only where the question needs it, repeating step 2 at each level.
4. Name every element and every flow.

Check:

1. Walk Rules against the result, drawing rules first.
2. Balance each child diagram against its parent's flow set.