Template — <unit>/design.md

# Design — <unit name>

## Architecture

[1-2 paragraphs: how this unit fits in the larger system. Reference the C4 diagrams.]

## Components

| Component | Type | Path | Confidence |
|-----------|------|------|------------|
| OrdersController | Controller | src/controllers/OrdersController.cs | 🟢 |
| OrdersService | Service | src/services/OrdersService.cs | 🟢 |
| OrderRepository | Repository | src/repositories/OrderRepository.cs | 🟢 |

## Internal flows

[Document flows that are NOT externally observable. These are implementation detail; they don't need ATDD scenarios.]

### Flow: Order finalization (internal)
1. OrdersService.Finalize is called with an OrderId
2. Service loads the order via OrderRepository.GetById
3. Service calls InvoiceService.Calculate
4. Service emits the orders.created event
5. Repository persists the new state

Mermaid:
```mermaid
sequenceDiagram
  participant API as OrdersController
  participant SVC as OrdersService
  participant INV as InvoiceService
  participant REPO as OrderRepository
  API->>SVC: Finalize(orderId)
  SVC->>REPO: GetById(orderId)
  SVC->>INV: Calculate(order)
  SVC->>REPO: Save(order)
  SVC->>EventBus: Publish(orders.created)

interface Order {
  id: string;
  customerId: string;
  items: OrderItem[];
  status: 'pending' | 'finalized' | 'cancelled';
  subtotal: number;
  total: number;
}

stateDiagram-v2
  [*] --> pending
  pending --> finalized: Finalize()
  pending --> cancelled: Cancel()
  finalized --> [*]
  cancelled --> [*]

## Notes

- `design.md` documents how it works. `requirements.md` documents what it does. `tasks.md` documents what to build (or rebuild).
- Internal flows don't need scenarios — they're implementation detail.
- Always cite file:line for design claims.
- Use Mermaid for sequence diagrams and state machines.