Dynamic Flow Architecture Skill
This skill provides guidance for designing and documenting runtime flows - how containers and components interact at runtime to fulfill use cases.
Agent Hierarchy Context
code
Repository Root
├── AGENTS.md # high-level-architect
├── .specs/
│ ├── flows/ # YOUR OPERATING CONTEXT
│ │ ├── README.md
│ │ └── {flow-name}.md # Individual flow specs
│ └── ...
└── {container}/
└── .specs/
└── internal-flows/ # Intra-container flows (container-architect)
Note: You are a cross-cutting agent referenced in root AGENTS.md, documenting cross-container flows. Internal container flows are documented by container-architects.
Scope Boundaries
| Level | In Scope | Out of Scope |
|---|---|---|
| Cross-Container Flows | Runtime sequences between containers | - |
| C4 Dynamic Diagrams | Numbered step sequences | Static architecture |
| Error Scenarios | Cross-container failures | Internal component errors |
| Use Case Mapping | Which flows fulfill which use cases | Use case definition |
| Internal Flows | NO | Container-architect's domain |
Directory Structure You Manage
Root .specs/flows/ Structure
code
.specs/flows/
├── README.md # Flow index
├── {use-case-name}.md # Primary flow for use case
├── {use-case-name}-errors.md # Error flows for use case
└── {use-case-name}-alt.md # Alternative flows
Documentation Templates
.specs/flows/README.md
markdown
# Runtime Flows - {System Name}
## Overview
This directory documents cross-container runtime flows that show how the system behaves at runtime.
## Flow Index
### Primary Flows
| Flow | Use Case | Containers Involved | Priority |
|------|----------|---------------------|----------|
| [user-registration](./user-registration.md) | New user signs up | API, User Service, Email | P0 |
| [order-placement](./order-placement.md) | Customer places order | API, Order, Payment, Inventory | P0 |
### Error Flows
| Flow | Triggered By | Recovery |
|------|--------------|----------|
| [payment-failure](./order-placement-errors.md#payment-failure) | Payment declined | Retry/Cancel |
### Alternative Flows
| Flow | Condition | Difference from Primary |
|------|-----------|------------------------|
| [guest-checkout](./order-placement-alt.md) | No account | Skips auth steps |
## Flow Conventions
### Numbering
- Steps numbered sequentially: 1, 2, 3...
- Sub-steps for detail: 1.1, 1.2...
- Error branches: E1, E2...
### Participants
- Use container names from `/.specs/containers.md`
- External systems marked with `_Ext`
- Actors (users) use `Person`
## Recent Changes
| Date | Flow | Change |
|------|------|--------|
| [Date] | [Name] | [Summary] |
.specs/flows/{flow-name}.md
markdown
# Flow: {Flow Name}
## Overview
- **Use Case**: {What user/system goal this fulfills}
- **Trigger**: {What initiates this flow}
- **Actors**: {Who/what participates}
- **Outcome**: {Expected result}
## Prerequisites
- {Condition that must be true before flow starts}
- {Required state}
## Diagram
```mermaid
C4Dynamic
title {Flow Name}
Person(actor, "Actor", "Initiates flow")
Container(c1, "Container 1", "Technology")
Container(c2, "Container 2", "Technology")
ContainerDb(db, "Database", "Technology")
Container_Ext(ext, "External System", "Technology")
Rel(actor, c1, "1. Action description")
Rel(c1, c2, "2. Request description", "Protocol")
Rel(c2, db, "3. Data operation")
Rel(c2, ext, "4. External call", "Protocol")
Rel(ext, c2, "5. Response")
Rel(c2, c1, "6. Result")
Rel(c1, actor, "7. Confirmation")
```
## Step-by-Step Details
### Step 1: {Action Name}
- **From**: {Actor/Container}
- **To**: {Container}
- **Action**: {What happens}
- **Data**: {What's passed}
- **Protocol**: {HTTP/gRPC/Event/etc}
**Request**
```json
{
"field": "value"
}
```
**Validation**
- {Validation performed}
### Step 2: {Action Name}
- **From**: {Container}
- **To**: {Container}
- **Action**: {What happens}
- **Data**: {What's passed}
- **Protocol**: {Protocol}
**Business Logic**
- {Logic performed}
- {Decisions made}
[Continue for all steps...]
## Data Flow Summary
| Step | Data | Source | Destination | Transformation |
|------|------|--------|-------------|----------------|
| 1 | {Data} | {From} | {To} | {How modified} |
## Timing Expectations
| Step | Expected Duration | SLA |
|------|-------------------|-----|
| 1-2 | < 50ms | p99 |
| 3 | < 100ms | p99 |
| Total | < 500ms | p99 |
## Error Scenarios
See [{flow-name}-errors.md](./{flow-name}-errors.md) for error handling.
| Error | Step | Handling |
|-------|------|----------|
| {Error type} | {Step #} | {Brief handling} |
## Related Flows
- [{Related flow}](./{related}.md) - {Relationship}
## Change Log
| Date | Change | Reason |
|------|--------|--------|
| [Date] | [What changed] | [Why] |
.specs/flows/{flow-name}-errors.md
markdown
# Error Flows: {Flow Name}
## Overview
Error scenarios and recovery paths for [{Flow Name}](./{flow-name}.md).
## Error Scenarios
### E1: {Error Name}
#### Trigger
- **Step**: {Which step fails}
- **Condition**: {What causes the error}
- **Detection**: {How it's detected}
#### Diagram
```mermaid
C4Dynamic
title {Flow Name} - {Error Name}
Person(actor, "Actor", "Description")
Container(c1, "Container 1", "Tech")
Container(c2, "Container 2", "Tech")
Rel(actor, c1, "1. Initial request")
Rel(c1, c2, "2. Request fails")
Rel(c2, c1, "3. Error response", "Error code")
Rel(c1, actor, "4. User-friendly error")
```
#### Recovery Steps
| Step | Actor | Action | Outcome |
|------|-------|--------|---------|
| E1.1 | {Container} | {Action} | {Result} |
| E1.2 | {Container} | {Action} | {Result} |
#### Compensation (Rollback)
- **Required**: Yes/No
- **Steps**:
1. {Rollback action}
2. {Rollback action}
#### User Experience
- **Message**: "{User-facing error message}"
- **Actions Available**: {What user can do}
- **Retry**: Allowed/Not allowed
#### Monitoring
- **Alert**: {Alert name}
- **Severity**: {Critical/Warning/Info}
- **Dashboard**: {Link}
---
### E2: {Another Error}
[Repeat structure...]
## Error Matrix
| Error | Step | Severity | Recovery | Compensation | Retry |
|-------|------|----------|----------|--------------|-------|
| E1 | 3 | High | Auto | Yes | 3x |
| E2 | 5 | Medium | Manual | No | No |
## Circuit Breaker Triggers
| Container | Error Threshold | Open Duration | Fallback |
|-----------|-----------------|---------------|----------|
| {Name} | {count in period} | {seconds} | {behavior} |
.specs/flows/{flow-name}-alt.md
markdown
# Alternative Flows: {Flow Name}
## Overview
Alternative paths for [{Flow Name}](./{flow-name}.md) based on different conditions.
## Alternative: {Alt Name}
### Condition
- **When**: {Condition that triggers this path}
- **Differs From Primary**: {What's different}
### Diagram
```mermaid
C4Dynamic
title {Flow Name} - {Alt Name}
[Modified diagram...]
```
### Different Steps
| Primary Step | Alternative | Reason |
|--------------|-------------|--------|
| Step 3 | {Different action} | {Why different} |
| Step 5 | Skipped | {Why skipped} |
### Additional Steps
| Step | Action | Reason |
|------|--------|--------|
| 3.5 | {New action} | {Why needed} |
Best Practices
Diagram Design
DO:
- •Number all steps - Clear sequence
- •Show protocols - HTTP, gRPC, Events, etc.
- •Include external systems - Full picture
- •Keep it readable - 7-10 steps max per diagram
- •Use consistent naming - Match container names from architecture
DON'T:
- •Mix multiple use cases in one diagram
- •Show internal component interactions
- •Forget error paths
- •Leave steps unnumbered
- •Use vague action descriptions
Step Documentation
DO:
- •Document data exchanged - Request/response shapes
- •Note validations - What's checked where
- •Include timing - Expected durations
- •Show transformations - How data changes
- •Link to contracts - Reference interface specs
DON'T:
- •Document implementation details
- •Skip error handling
- •Ignore asynchronous behavior
- •Forget about retries/timeouts
- •Leave business logic undocumented
Error Handling
DO:
- •Document all failure points - Every step can fail
- •Define compensation - How to rollback partial work
- •Specify retry behavior - When and how many times
- •User experience - What user sees on error
- •Monitoring hooks - How errors are detected
DON'T:
- •Assume happy path only
- •Ignore partial failures
- •Forget about timeouts
- •Skip circuit breaker design
- •Leave recovery undefined
Flow Categories
Synchronous Flows
- •User waits for response
- •All steps complete in sequence
- •Timeout defines max duration
mermaid
C4Dynamic
title Synchronous Flow Pattern
Person(user, "User", "Waits")
Container(a, "A", "Tech")
Container(b, "B", "Tech")
Rel(user, a, "1. Request")
Rel(a, b, "2. Process")
Rel(b, a, "3. Result")
Rel(a, user, "4. Response")
Asynchronous Flows
- •User doesn't wait
- •Event-driven processing
- •Eventual completion
mermaid
C4Dynamic
title Asynchronous Flow Pattern
Person(user, "User", "Doesn't wait")
Container(a, "A", "Tech")
ContainerQueue(q, "Queue", "Tech")
Container(b, "B", "Tech")
Rel(user, a, "1. Request")
Rel(a, user, "2. Accepted")
Rel(a, q, "3. Publish event")
Rel(q, b, "4. Process async")
Saga Flows
- •Distributed transaction
- •Compensation on failure
- •Eventually consistent
mermaid
C4Dynamic
title Saga Flow Pattern
Container(orchestrator, "Saga", "Tech")
Container(a, "Service A", "Tech")
Container(b, "Service B", "Tech")
Rel(orchestrator, a, "1. Step A")
Rel(a, orchestrator, "2. A done")
Rel(orchestrator, b, "3. Step B")
Rel(b, orchestrator, "4. B failed")
Rel(orchestrator, a, "5. Compensate A")
Checklist: New Flow Design
- • Identify use case this flow fulfills
- • List all participating containers
- • Create C4Dynamic diagram
- • Document each step in detail
- • Define data exchanged at each step
- • Set timing expectations
- • Document error scenarios
- • Define compensation/rollback
- • Create error flow diagram(s)
- • Add to flow index in README.md
Checklist: Processing Change
- • Assess impact on existing flows
- • Update affected flow diagrams
- • Update step details
- • Revise error handling if needed
- • Update timing expectations
- • Update flow index