Business Flows

Canonical state names and legal transitions are centralized in state-machine.md.

Flow index

Flow ID	Name	Main actors
BF-01	Account onboarding	User, API, Account service
BF-02	Membership + coupon validation	User, Membership, Coupon
BF-03	Reservation lifecycle	User/Admin, Reservation, Queue
BF-04	Notification completion	Queue, Notification, User

Domain flow map

flowchart TB
  subgraph Acquisition
    A1[User Signup/Login]
    A2[Profile + Eligibility Check]
  end

  subgraph Commercial
    C1[Membership Activation]
    C2[Coupon Claim/Apply]
    C3[Reservation Create/Change]
  end

  subgraph Fulfillment
    F1[Reservation Confirmation]
    F2[Notification Dispatch]
    F3[Audit + Reporting]
  end

  A1 --> A2 --> C1
  A2 --> C2
  C1 --> C3
  C2 --> C3
  C3 --> F1 --> F2 --> F3

BF-02 — membership + coupon validation

• Reject early on invalid membership (inactive, expired).
• Keep coupon usage atomic to prevent double-claim.
• Return explicit reason_code for support triage.

BF-03 — reservation lifecycle (write vs side effect)

flowchart LR
  W[Reservation write] -->|success| E[Emit event to queue]
  E -->|success| N[Notification delivered]
  E -->|failed| R1[Mark retryable + replay job]
  W -->|failed| R2[Rollback transaction]

Failure branch matrix

Step	Failure	Immediate effect	Safe action
Membership check	record missing	reject request	verify account binding + seed data
Coupon validation	quota exhausted	business reject (4xx)	use alternate coupon; do not retry blindly
Reservation write	deadlock/timeout	transaction rollback	retry with backoff + lock ordering review
Notification dispatch	queue fail	business write may succeed	replay failed job; do not re-create reservation

Canonical links

• State legality: state-machine.md
• Payload contracts: request-response-catalog.md
• Recovery playbook: operations-runbook.md