# 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`.

---

```markdown
# [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

```mermaid
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"|`)