User Flows¶

Status: Draft — scaffolded alongside ADR-0066. Flows completed under CVN-N008-EA stories.

Every flow has an ID (FLOW-<area>-<nnn>) that is reused in Figma frames, MkDocs screen pages, Storybook MDX doc blocks, and PR bodies. Flows are Mermaid diagrams embedded in this file — no standalone .mmd files.

FLOW-CONFIG-001 — Edit + Save a non-critical parameter¶

The baseline operator journey. The parameter is not flagged critical in the catalog, so no approval is needed; the Save propagates directly to the active configuration.

sequenceDiagram
  autonumber
  actor Operator
  participant UI as Config Editor
(UI-CONFIG-002)
  participant API as Configuration API
  participant Catalog as variable_catalog
  participant Active as active_config
  participant Audit as config_history

  Operator->>UI: Navigate to /config/{env}
  UI->>API: GET /api/config/{env}
  API->>Active: SELECT current values
  API->>Catalog: SELECT metadata + LoV
  API-->>UI: hydrated form
  Operator->>UI: Edit parameter value
  UI->>UI: Client-side Zod validate
  Operator->>UI: Review diff + Save
  UI->>API: POST /api/config/{env}/save
  API->>API: Server-side Zod + RBAC + coherence
  alt validation fails
    API-->>UI: 400 with field errors
    UI->>Operator: ValidationBanner (CMP-CONFIG-003)
  else validation ok
    API->>Active: UPDATE (SELECT FOR UPDATE)
    API->>Audit: INSERT history row
    API-->>UI: 200 + new version id
    UI->>Operator: Toast success + reset dirty state
  end

FLOW-CONFIG-002 — Edit a critical parameter with approval¶

Same editor, but the parameter is flagged critical = TRUE in the catalog. The editor submits a draft, the approver signs it, and only then is it written to the active configuration.

sequenceDiagram
  autonumber
  actor Editor
  actor Approver
  participant UI as Config Editor
(UI-CONFIG-002)
  participant API as Configuration API
  participant Draft as drafts_queue
  participant Active as active_config
  participant Audit as config_history

  Editor->>UI: Edit critical parameter
  UI->>UI: ApprovalDialog (CMP-CONFIG-006) opens
  Editor->>UI: Provide change_reason + Submit
  UI->>API: POST /api/config/{env}/drafts
  API->>Draft: INSERT draft row (status=pending)
  API-->>UI: 202 + draft id
  UI->>Editor: Pending-approval badge visible
  Note over Approver,UI: Approver receives notification (out-of-band: Slack / email — TBD)
  Approver->>UI: Navigate to /admin/drafts
  UI->>API: GET /api/config/{env}/drafts
  API->>Draft: SELECT pending
  API-->>UI: list
  Approver->>UI: Review diff + Approve
  UI->>API: POST /api/config/{env}/drafts/{id}/approve
  API->>Active: UPDATE (SELECT FOR UPDATE)
  API->>Audit: INSERT history row (approved_by=approver)
  API->>Draft: UPDATE status=approved
  API-->>UI: 200
  UI->>Approver: Toast success

FLOW-CONFIG-003 — Rollback from the audit trail¶

Operator looks at the audit trail, picks a past configuration, and rolls back to it. The rollback goes through the same validation + safe-boundary path as a forward change.

flowchart TD
  Start[Operator opens /history] --> Pick[Pick a past snapshot]
  Pick --> Preview[View diff vs current]
  Preview --> Confirm{Confirm
rollback?}
  Confirm -->|no| Exit[Exit]
  Confirm -->|yes| Draft[Create restore draft]
  Draft --> Critical{Any critical
param changed?}
  Critical -->|yes| Approval[Route through ApprovalDialog]
  Critical -->|no| Apply[Write to active_config]
  Approval -->|approved| Apply
  Approval -->|rejected| Exit
  Apply --> NotifyRuntime[PG NOTIFY config_changed]
  NotifyRuntime --> RuntimeHotReload[Workers hot-reload
at safe boundary
see CVN-N008 §9.4]
  Apply --> AuditEntry[Record 'restore' entry
in config_history]

Placeholders for upcoming flows¶

References¶

• Binding ADR: ADR-0066
• Architecture: CONFIGURATION_PLATFORM.md §6-7 (real-time distribution + safe boundaries)
• Parent Need: CVN-N008