Behavior
Behavior Documentation
This section documents runtime behavior — how components interact over time to accomplish tasks.
Why Sequence Diagrams?
Sequence diagrams are ideal for illustrating:
- Multi-step workflows across services or components
- Request/response patterns including error handling
- Async operations with callbacks, retries, or timeouts
- Side effects and their ordering
When to Create One
Rule of thumb: If a flow involves 3+ actors or has non-obvious error handling, document it with a sequence diagram.
Common scenarios:
- User authentication flows
- Data synchronization between systems
- Event-driven workflows
- API call chains with fallbacks
Format
We store diagrams as Mermaid or PlantUML source code:
| Format | Pros | Best For |
|---|---|---|
| Mermaid | Native Hugo rendering, simpler syntax | Quick diagrams, basic flows |
| PlantUML | More features, styling options | Complex diagrams, formal docs |
Templates
See the Sequence Diagram Template for examples and best practices.