flowdrom
Flowdrom User Guide
Flowdrom is a web-based tool for creating transaction timing diagrams and sequence charts. It uses JSON-based definitions to generate visual diagrams that can be exported as SVG or PNG files.
Table of Contents
Getting Started
- Open Flowdrom in your web browser
- Edit the JSON in the top panel to define your diagram
- Click “Render” to generate the visual diagram
- Use “Export SVG” or “Export PNG” to save your diagram
- Use “Load SVG” to edit existing diagrams
Basic Concepts
Flowdrom diagrams consist of:
- Lanes: Vertical columns representing entities (processors, agents, memory, etc.)
- Messages: Arrows between lanes showing communication
- States: Boxes showing state changes within lanes
- Time: Horizontal axis showing sequence of events
- Lane Groups: Visual grouping of related lanes
- Info Boxes: Annotations explaining specific events
Lane Positioning and Manual Adjustment
- By default, lanes are spaced evenly.
- To manually shift a lane horizontally, prefix its name with
>(right) or<(left). Each symbol shifts by 20 pixels.- Example:
>CA0shifts CA0 right by 20px,<<CA1shifts CA1 left by 40px.
- Example:
- This affects all diagram elements referencing that lane (messages, states, info boxes, groups).
Feature Examples
1. Two-Lane Communication
simple-two-lane-communication
Let’s start with the simplest possible diagram - two entities exchanging a message:
{
title: 'Hello world',
lanes: ['Source', 'Target'],
messages: [
{ path: 'Source->Target', label: 'Hello', fromTime: 0, toTime: 1 },
{ path: 'Target->Source', label: 'World', fromTime: 1, toTime: 2 },
],
}
Adding color and style.
{
title: 'Basic Request-Response',
lanes: ['Client', 'Server'],
messages: [
{ path: 'Client->Server', label: 'Request', color: 'blue', style: 'solid', fromTime: 0, toTime: 1 },
{ path: 'Server->Client', label: 'Response', color: 'green', style: 'solid', fromTime: 1, toTime: 2 }
]
}
This creates a simple sequence showing a client sending a request to a server and receiving a response.
unordered-two-lane-communication
Since flowdrom is not just a sequence graph generator but actually has timing parameters, it opens the possibilities to create unordered sequences / non linear sequences.
{
title: 'Unordered traffic',
lanes: ['CA0', 'HN'],
messages: [
{ path: 'CA0->HN', label: 'RdData(k1)', color: 'red', style: 'solid', fromTime: 0, toTime: 4 },
{ path: 'HN->CA0', label: 'Data (k1)', color: 'red', style: 'solid', fromTime: 4, toTime: 6 },
{ path: 'CA0->HN', label: 'RdData(k2)', color: 'purple', style: 'solid', fromTime: 0.5, toTime: 2 },
{ path: 'HN->CA0', label: 'Data (k2)', color: 'purple', style: 'solid', fromTime: 2, toTime: 7 }
]
}
Here source and target sequences are different.
message label syntax
| use ‘ | ’ to create a multi line message label. In case of collisions (message label obscures another graph element) you can use prefix ‘>’ or ‘<’ in the label text to shift the message right or left accordingly along its arrow (can also use multiple for bigger distance ‘»>label’). |
- Each
>at the start of a label moves the label toward the arrow’s end; each<moves it toward the start. - This does not affect the arrow itself, only the label’s position.
{
title: 'Request-Response with collision',
lanes: ['Client', 'Server'],
messages: [
{ path: 'Client->Server', label: 'Request', color: 'blue', style: 'solid', fromTime: 0, toTime: 1 },
{ path: 'Client->Server', label: '>ctl|msg', color: 'red', style: 'solid', fromTime: 0, toTime: 4 },
{ path: 'Server->Client', label: 'Response', color: 'green', style: 'solid', fromTime: 1, toTime: 2 }
]
}
message defaults All given examples are full, however: If label is omitted the message would be arrow only If color is omitted the message would be black If style is omitted the style would be solid
2. Adding States
Now let’s add state changes to show what happens inside each entity:
{
title: 'Request-Response with States',
lanes: ['Client', 'Server'],
messages: [
{ path: 'Client->Server', label: 'Request', color: 'blue', style: 'solid', fromTime: 0, toTime: 1 },
{ path: 'Server->Client', label: 'Response', color: 'green', style: 'solid', fromTime: 2, toTime: 3 }
],
states: [
{ lane: 'Client', label: 'Waiting', color: 'yellow', fromTime: 1, toTime: 3 },
{ lane: 'Server', label: 'Processing', color: 'orange', fromTime: 1, toTime: 2 }
]
}
The states show that the client waits while the server processes the request.
3. Multi-Lane Systems
Real systems often involve multiple components. Here’s a three-lane system:
{
title: 'Three-Tier Architecture',
lanes: ['Frontend', 'Backend', 'Database'],
messages: [
{ path: 'Frontend->Backend', label: 'API Call', color: 'blue', style: 'solid', fromTime: 0, toTime: 1 },
{ path: 'Backend->Database', label: 'Query', color: 'purple', style: 'solid', fromTime: 1, toTime: 2 },
{ path: 'Database->Backend', label: 'Results', color: 'orange', style: 'solid', fromTime: 3, toTime: 4 },
{ path: 'Backend->Frontend', label: 'JSON Response', color: 'green', style: 'solid', fromTime: 4, toTime: 5 }
],
states: [
{ lane: 'Backend', label: 'Processing', color: 'yellow', fromTime: 1, toTime: 4 },
{ lane: 'Database', label: 'Query Execution', color: 'cyan', fromTime: 2, toTime: 3 }
]
}
This shows a typical web application flow: frontend → backend → database → backend → frontend.
4. Lane Groups
For complex systems, you can group related lanes visually:
{
title: 'Microservices Architecture',
lanes: ['Client', 'API Gateway', 'Auth Service', 'User Service', 'Database'],
laneGroups: [
{ label: 'Client Layer', lanes: ['Client'] },
{ label: 'Service Layer', lanes: ['API Gateway','Auth Service','User Service'] },
{ label: 'Data Layer', lanes: ['Database'] }
],
messages: [
{ path: 'Client->API Gateway', label: 'Login Request', color: 'blue', style: 'solid', fromTime: 0, toTime: 1 },
{ path: 'API Gateway->Auth Service', label: 'Validate', color: 'purple', style: 'solid', fromTime: 1, toTime: 2 },
{ path: 'Auth Service->User Service', label: 'Get User', color: 'orange', style: 'solid', fromTime: 2, toTime: 3 },
{ path: 'User Service->Database', label: 'Query User', color: 'red', style: 'solid', fromTime: 3, toTime: 4 }
]
}
Lane groups help organize complex diagrams by showing architectural boundaries.
5. Information Boxes
Add contextual information with info boxes:
{
title: 'Error Handling Example',
lanes: ['Client', 'Server', 'Database'],
infoBoxes: [
{ lane: 'Server', time: 2, text: '<130,30>Connection timeout|Retry with |exponential backoff' },
{ lane: 'Client', time: 4, text: '<-80,0>Display |error message|to user' }
],
messages: [
{ path: 'Client->Server', label: 'Data Request', color: 'blue', style: 'solid', fromTime: 0, toTime: 1 },
{ path: 'Server->Database', label: 'Query', color: 'purple', style: 'solid', fromTime: 1, toTime: 2 },
{ path: 'Server->Client', label: 'Timeout Error', color: 'red', style: 'dashed', fromTime: 3, toTime: 4 }
],
states: [
{ lane: 'Server', label: 'Error State', color: 'red', fromTime: 2, toTime: 3 }
]
}
Info boxes provide additional context about what’s happening at specific points in time. Use | for line breaks in the text.
Info box placement
- The renderer places info boxes using a simple explicit offset mechanism. By default an info box is drawn upper-right of the lane/time anchor using offsets x=50, y=-50 (pixels).
- To request a specific placement, prefix the info box text with an offset in the form
<x,y>where x and y are integer pixel offsets. Example:{ lane: 'Server', time: 2, text: '<8,-4>Connection timeout|Retry with backoff' }- Positive x shifts the box to the right; negative x shifts it left.
- Positive y shifts the box down; negative y shifts it up.
- How the offset is applied:
- The anchor point is the lane X coordinate and the time Y coordinate (anchorY = laneTop + time * timeStep).
- The box center is computed as (laneX + xOffset, anchorY + yOffset) before subtracting half the box width/height.
- The connector line is drawn from the lane/time anchor to the nearest vertical edge of the info box (right edge if the box is to the right of the lane, left edge if to the left).
- If no
<x,y>prefix is present the renderer uses the default<50,-50>. - Notes:
- The renderer does not currently perform advanced collision avoidance for info boxes — if boxes/labels overlap, adjust offsets manually.
- Offsets must be provided as integers in pixels and placed at the very start of the
textstring (no leading spaces).
6. Complex Transactions
Here’s an advanced example showing 2 new features of lanes by using a different name syntax:
-
Sublanes: these are handy to show a sub component interaction with the system. A lane may have 2 sublanes (one on each side). The Syntax for a sublane is to use one of the lane names and add a “.” concatination either on the left or the right. For example for Lane=”HN”, a sublane on the right is given by using “HN.MEM” (MEM.HN would place it on the left).
-
Medium: this is handy when describing a medium through a message may pass. This is done using underscores on both sides - “_Lane_”
{
title: 'Cache Coherency Conflict',
lanes: ['CA0', '_D2D_', 'CA1', 'HN', 'HN.MEM'],
laneGroups: [
{ label: 'Caching Agents', lanes: ['CA0','CA1'] },
{ label: 'System', lanes: ['HN','HN.MEM'] }
],
infoBoxes: [
{ lane: 'HN', time: 2, text: 'Conflict detected|serialize requests' }
],
messages: [
{ path: 'CA0->HN', label: 'Read|Unique(A)', color: 'red', style: 'solid', fromTime: 0, toTime: 1 },
{ path: 'CA1->HN', label: 'Read|Unique(A)', color: 'red', style: 'dashed', fromTime: 1, toTime: 2 },
{ path: 'HN->HN.MEM', label: 'Rd(A)', color: 'orange', style: 'solid', fromTime: 2, toTime: 3 },
{ path: 'HN.MEM->HN', label: 'D(A)', color: 'orange', style: 'solid', fromTime: 4, toTime: 5.5 },
{ path: 'HN->CA1', label: 'SnpInvalid(A)', color: 'purple', style: 'solid', fromTime: 2, toTime: 4 },
{ path: 'CA1->HN', label: 'SnpResp(I)', color: 'green', style: 'solid', fromTime: 4, toTime: 6 },
{ path: 'HN->CA0', label: 'CompData(A)', color: 'blue', style: 'solid', fromTime: 6, toTime: 7 },
{ path: 'HN->CA1', label: 'Retry', color: 'red', style: 'dashed', fromTime: 7, toTime: 8 }
],
states: [
{ lane: 'CA0', label: 'I->UD', color: 'yellow', fromTime: 0, toTime: 0.5 },
{ lane: 'CA1', label: 'S->I', color: 'orange', fromTime: 4, toTime: 4.5 },
{ lane: 'HN', label: 'Conflict', color: 'red', fromTime: 2, toTime: 7 }
]
}
This complex example shows how two caching agents conflict when trying to access the same memory address simultaneously.
7. Legends
Add legends to explain your color coding:
{
title: 'Protocol Messages with Legend',
lanes: ['Client', 'Router', 'Server'],
messages: [
{ path: 'Client->Router', label: 'HTTP GET', color: 'blue', style: 'solid', fromTime: 0, toTime: 1 },
{ path: 'Router->Server', label: 'Forward', color: 'green', style: 'solid', fromTime: 1, toTime: 2 },
{ path: 'Server->Router', label: 'HTTP 200', color: 'purple', style: 'solid', fromTime: 2, toTime: 3 },
{ path: 'Router->Client', label: 'Response', color: 'orange', style: 'solid', fromTime: 3, toTime: 4 }
],
legend: [
{ label: 'Request', color: 'blue', style: 'solid' },
{ label: 'Forward', color: 'green', style: 'solid' },
{ label: 'Response', color: 'purple', style: 'solid' },
{ label: 'Delivery', color: 'orange', style: 'solid' }
]
}
Legends help readers understand what different colors and line styles represent.
HTML / CSS named colors
You can use any standard HTML/CSS named color in your diagrams (for message colors, state backgrounds, legends, etc.). Below is the complete list of named colors and their hexadecimal values — copy the color name (for example red or RebeccaPurple) into your diagram JSON’s color field. On GitHub Pages the table will also display a small color swatch for each name.
| Swatch | Name | Hex |
|---|---|---|
| AliceBlue | #F0F8FF | |
| AntiqueWhite | #FAEBD7 | |
| Aqua | #00FFFF | |
| Aquamarine | #7FFFD4 | |
| Azure | #F0FFFF | |
| Beige | #F5F5DC | |
| Bisque | #FFE4C4 | |
| Black | #000000 | |
| BlanchedAlmond | #FFEBCD | |
| Blue | #0000FF | |
| BlueViolet | #8A2BE2 | |
| Brown | #A52A2A | |
| BurlyWood | #DEB887 | |
| CadetBlue | #5F9EA0 | |
| Chartreuse | #7FFF00 | |
| Chocolate | #D2691E | |
| Coral | #FF7F50 | |
| CornflowerBlue | #6495ED | |
| Cornsilk | #FFF8DC | |
| Crimson | #DC143C | |
| Cyan | #00FFFF | |
| DarkBlue | #00008B | |
| DarkCyan | #008B8B | |
| DarkGoldenRod | #B8860B | |
| DarkGray | #A9A9A9 | |
| DarkGrey | #A9A9A9 | |
| DarkGreen | #006400 | |
| DarkKhaki | #BDB76B | |
| DarkMagenta | #8B008B | |
| DarkOliveGreen | #556B2F | |
| DarkOrange | #FF8C00 | |
| DarkOrchid | #9932CC | |
| DarkRed | #8B0000 | |
| DarkSalmon | #E9967A | |
| DarkSeaGreen | #8FBC8F | |
| DarkSlateBlue | #483D8B | |
| DarkSlateGray | #2F4F4F | |
| DarkSlateGrey | #2F4F4F | |
| DarkTurquoise | #00CED1 | |
| DarkViolet | #9400D3 | |
| DeepPink | #FF1493 | |
| DeepSkyBlue | #00BFFF | |
| DimGray | #696969 | |
| DimGrey | #696969 | |
| DodgerBlue | #1E90FF | |
| FireBrick | #B22222 | |
| FloralWhite | #FFFAF0 | |
| ForestGreen | #228B22 | |
| Fuchsia | #FF00FF | |
| Gainsboro | #DCDCDC | |
| GhostWhite | #F8F8FF | |
| Gold | #FFD700 | |
| GoldenRod | #DAA520 | |
| Gray | #808080 | |
| Grey | #808080 | |
| Green | #008000 | |
| GreenYellow | #ADFF2F | |
| HoneyDew | #F0FFF0 | |
| HotPink | #FF69B4 | |
| IndianRed | #CD5C5C | |
| Indigo | #4B0082 | |
| Ivory | #FFFFF0 | |
| Khaki | #F0E68C | |
| Lavender | #E6E6FA | |
| LavenderBlush | #FFF0F5 | |
| LawnGreen | #7CFC00 | |
| LemonChiffon | #FFFACD | |
| LightBlue | #ADD8E6 | |
| LightCoral | #F08080 | |
| LightCyan | #E0FFFF | |
| LightGoldenRodYellow | #FAFAD2 | |
| LightGray | #D3D3D3 | |
| LightGrey | #D3D3D3 | |
| LightGreen | #90EE90 | |
| LightPink | #FFB6C1 | |
| LightSalmon | #FFA07A | |
| LightSeaGreen | #20B2AA | |
| LightSkyBlue | #87CEFA | |
| LightSlateGray | #778899 | |
| LightSlateGrey | #778899 | |
| LightSteelBlue | #B0C4DE | |
| LightYellow | #FFFFE0 | |
| Lime | #00FF00 | |
| LimeGreen | #32CD32 | |
| Linen | #FAF0E6 | |
| Magenta | #FF00FF | |
| Maroon | #800000 | |
| MediumAquaMarine | #66CDAA | |
| MediumBlue | #0000CD | |
| MediumOrchid | #BA55D3 | |
| MediumPurple | #9370DB | |
| MediumSeaGreen | #3CB371 | |
| MediumSlateBlue | #7B68EE | |
| MediumSpringGreen | #00FA9A | |
| MediumTurquoise | #48D1CC | |
| MediumVioletRed | #C71585 | |
| MidnightBlue | #191970 | |
| MintCream | #F5FFFA | |
| MistyRose | #FFE4E1 | |
| Moccasin | #FFE4B5 | |
| NavajoWhite | #FFDEAD | |
| Navy | #000080 | |
| OldLace | #FDF5E6 | |
| Olive | #808000 | |
| OliveDrab | #6B8E23 | |
| Orange | #FFA500 | |
| OrangeRed | #FF4500 | |
| Orchid | #DA70D6 | |
| PaleGoldenRod | #EEE8AA | |
| PaleGreen | #98FB98 | |
| PaleTurquoise | #AFEEEE | |
| PaleVioletRed | #DB7093 | |
| PapayaWhip | #FFEFD5 | |
| PeachPuff | #FFDAB9 | |
| Peru | #CD853F | |
| Pink | #FFC0CB | |
| Plum | #DDA0DD | |
| PowderBlue | #B0E0E6 | |
| Purple | #800080 | |
| RebeccaPurple | #663399 | |
| Red | #FF0000 | |
| RosyBrown | #BC8F8F | |
| RoyalBlue | #4169E1 | |
| SaddleBrown | #8B4513 | |
| Salmon | #FA8072 | |
| SandyBrown | #F4A460 | |
| SeaGreen | #2E8B57 | |
| SeaShell | #FFF5EE | |
| Sienna | #A0522D | |
| Silver | #C0C0C0 | |
| SkyBlue | #87CEEB | |
| SlateBlue | #6A5ACD | |
| SlateGray | #708090 | |
| SlateGrey | #708090 | |
| Snow | #FFFAFA | |
| SpringGreen | #00FF7F | |
| SteelBlue | #4682B4 | |
| Tan | #D2B48C | |
| Teal | #008080 | |
| Thistle | #D8BFD8 | |
| Tomato | #FF6347 | |
| Turquoise | #40E0D0 | |
| Violet | #EE82EE | |
| Wheat | #F5DEB3 | |
| White | #FFFFFF | |
| WhiteSmoke | #F5F5F5 | |
| Yellow | #FFFF00 | |
| YellowGreen | #9ACD32 |
JSON Schema Reference
Root Object
{
title: 'string', // Diagram title
lanes: ['string'], // Array of lane names
laneGroups: [...], // Optional lane groupings
messages: [...], // Message arrows
states: [...], // State changes
infoBoxes: [...], // Information annotations
legend: [...] // Legend entries
}
Message Object
{
path: 'Source->Target', // Lane1->Lane2 format
label: 'Message text', // Use | for line breaks
color: 'red|blue|green|purple|orange', // Message color
style: 'solid|dashed', // Line style
fromTime: 0, // Start time (number)
toTime: 1 // End time (number)
}
State Object
{
lane: 'LaneName', // Which lane
label: 'State Name', // State description
color: 'yellow|red|green|blue|orange|cyan', // Background color
fromTime: 0, // Start time
toTime: 1 // End time
}
Note: state may have a single time (i.e. Start time = End time)
Lane Group Object
{
label: 'Group Name', // Group title
lanes: ['Lane1', 'Lane2'] // Lanes to group
}
Info Box Object
{
lane: 'LaneName', // Which lane to attach to
time: 2, // Time position
text: 'Info text|Line 2' // Text with | for line breaks
}
Legend Entry
{
label: 'Description', // Legend text
color: 'red', // Color to show
style: 'solid' // Line style to show
}