Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.


Render graphs using a declarative markup. Currently supports DFD ( and sequence diagrams (

DFD Output


  • To install using cabal run:

    $ cabal install dataflow
  • There are some binaries available in Releases.

  • If you want to use Docker there are images available on Docker Hub.

  • For build instructions see


The following forms are supported by DataFlow.


An ID can contain letters, numbers and underscores. It must start with a letter.



String literals are written using double quotes.

"this is a string and it can contain everything but double quotes and newlines"

NOTE! Escaping characters inside strings is not supported at the moment.

Text Blocks

Text blocks are special strings, enclosed in backticks, that are can span multiple lines in the source document. The space characters before the first non-space characters on each line are trimmed, regardless of the indentation.

`this is

... is converted to:

this is


Arrays can contain other values (arrays, strings, text blocks).

["hello", "world", ["I", "am", `nested


Attributes are key-value pairs for diagrams and nodes that are used by output renderers. Attributes are enclosed by curly brackets. For nodes that can contain other nodes, attributes must appear before nodes.

Keys have the same rules as IDs. Values can be strings or text blocks.

  key1 = "attr value"
  key2 = `attr
  key3 = ["value1", "value2"]


diagram is the top-level form and must appear exactly once in a DataFlow document. It can contain attributes and nodes.

diagram {
  title = "My diagram"


The boundary form declares a TrustBoundary node that can contain attributes and other nodes. Boundaries are only allowed in the top-level diagram and they must have unique IDs.

diagram {
  boundary my_boundary {
    title = "My System"

nodes: io, function, database

The io, function and database forms declare InputOutput, Function and Database nodes, respectively. The nodes have IDs and they can contain attributes. Empty attribute brackets can be omitted.

diagram {
  io thing1

  io thing2 {
    title = "Thing 2"


The -> form declares a Flow between the nodes referenced by their IDs. It can contain attributes. Empty attribute brackets can be omitted. Flows must be declared after all nodes.

Note that the arrow can be reversed as well (<-).

diagram {
  thing1 -> thing2

  thing1 <- thing2 {
    operation = "Greet"
    data = "A nice greeting"


Comments are written using /* and */ and are ignored by the Reader. They're only used for human consumption.

diagram {
  /* I can write
   * whatever I
   * want in here! */


The image from the top of this README is rendered from the following DataFlow document.

diagram {
  title = "Webapp"

  /* Some comment about this... */
  threats = `
    No particular threats at this point.

    It's **extremely** safe.`

  boundary browser {
    title = "Browser"

    function client {
      title = "Client"

  boundary aws {
    title = "Amazon AWS"

    function server {
      title = "Web Server"
    database logs {
      title = "Logs"
  io analytics {
    title = "Google Analytics"

  client -> server {
    operation = "Request /"
    description = `User navigates with a browser to see some content.`
  server -> logs {
    operation = "Log"
    data = `The user
            IP address.`
    description = `Logged to a ELK stack.`
  server -> client {
    operation = "Response"
    data = "User Profile"
    description = `The server responds with some HTML.`
  analytics <- client {
    operation = "Log"
    data = "Page Navigation"
    description = `The Google Analytics plugin sends navigation
                   data to Google.`

Run DataFlow

The dataflow executable takes an output format and a DataFlow source document and writes the output to stdout.

dataflow (dfd|seq) FILE


DFD Legend

To use the DFD output you need Graphviz installed.

dataflow dfd webapp.flow | dot -Tpng > webapp.png


DFD Output

Sequence Diagram

Sequence Diagram Legend

You can use PlantUML to generate a sequence diagram.

dataflow seq webapp.flow | java -Djava.awt.headless=true -jar plantuml.jar -tpng -pipe > webapp.png


Sequence Diagram Output


You can use Mustache to output arbitrary text.

dataflow template template.ha webapp.flow > webapp.html

Built-in Functions and Values

  • markdown - Convert the attribute at the given key from Markdown to HTML.

  • html_linebreaks - Replace \n with <br/> elements in the attribute at the given key, to retain linebreaks in HTML output.

  • filename_without_extension - The input .flow file name with no path and no extension. Useful when generating graphics and text/HTML with matching filenames (e.g. my-flow.html includes my-flow.png).

    <img src="{{filename_without_extension}}.png" />
  • flows - a list of all the Flow nodes in the diagram. Attributes of the flow is accessible inside the iteration scope, including a number.

      <li>{{number}} - {{description}}</li>

For an example see template.ha and the output HTML in webapp.html.


Sequence Diagram Output

Makefile Example

The following Makefile finds .flow sources in src and generates DFDs, in SVG format, in dist.

SOURCES=$(shell find src/*.flow)

K := $(if $(shell which dataflow),,$(error "No dataflow executable in PATH. See for install instructions)))"))

dist/%.dfd.svg: src/%.flow
	@dataflow dfd $< | dot -Tsvg > $@

dfd: $(TARGETS)

  rm -f $(TARGETS)