ai-training/.cursor/skills/plan/templates/system-flows.md

System Flows Template

Use this template for the system flows document. Save as _docs/02_document/system-flows.md. Individual flow diagrams go in _docs/02_document/diagrams/flows/flow_[name].md.

---

# [System Name] — System Flows

## Flow Inventory

| # | Flow Name | Trigger | Primary Components | Criticality |
|---|-----------|---------|-------------------|-------------|
| F1 | [name] | [user action / scheduled / event] | [component list] | High/Medium/Low |
| F2 | [name] | | | |
| ... | | | | |

## Flow Dependencies

| Flow | Depends On | Shares Data With |
|------|-----------|-----------------|
| F1 | — | F2 (via [entity]) |
| F2 | F1 must complete first | F3 |

---

## Flow F1: [Flow Name]

### Description

[1-2 sentences: what this flow does, who triggers it, what the outcome is]

### Preconditions

- [Condition 1]
- [Condition 2]

### Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant ComponentA
    participant ComponentB
    participant Database

    User->>ComponentA: [action]
    ComponentA->>ComponentB: [call with params]
    ComponentB->>Database: [query/write]
    Database-->>ComponentB: [result]
    ComponentB-->>ComponentA: [response]
    ComponentA-->>User: [result]

Flowchart

flowchart TD
    Start([Trigger]) --> Step1[Step description]
    Step1 --> Decision{Condition?}
    Decision -->|Yes| Step2[Step description]
    Decision -->|No| Step3[Step description]
    Step2 --> EndNode([Result])
    Step3 --> EndNode

Data Flow

Step	From	To	Data	Format
1	[source]	[destination]	[what data]	[DTO/event/etc]
2

Error Scenarios

Error	Where	Detection	Recovery
[error type]	[which step]	[how detected]	[what happens]

Performance Expectations

Metric	Target	Notes
End-to-end latency	[target]	[conditions]
Throughput	[target]	[peak/sustained]

---

Flow F2: [Flow Name]

(repeat structure above)

---

## Mermaid Diagram Conventions

Follow these conventions for consistency across all flow diagrams:

- **Participants**: use component names matching `components/[##]_[name]`
- **Node IDs**: camelCase, no spaces (e.g., `validateInput`, `saveOrder`)
- **Decision nodes**: use `{Question?}` format
- **Start/End**: use `([label])` stadium shape
- **External systems**: use `[[label]]` subroutine shape
- **Subgraphs**: group by component or bounded context
- **No styling**: do not add colors or CSS classes — let the renderer theme handle it
- **Edge labels**: wrap special characters in quotes (e.g., `-->|"O(n) check"|`)