10 — End use cases & operational flows

Status: draft Audience: onboarding engineers/PM/finance — read this to understand what the product does for a user, end to end Stance: Product outcome first. Chargebee/Hotglue are just where data enters; the deliverable is a correct, auditable ASC 606 subledger the finance team can close and report on.

Read with: 00-product.md (why) · 11-rules-reference.md (the rules) · 03-event-catalog.md (source→event) · 04-engine-scenarios.md (numbers)

1. Who uses it (personas)

The product’s job: let the accountant and controller trust the numbers without touching spreadsheets.

2. Use-case catalog

Each use case maps to a domain operation (see 03/08) and a customer outcome.

Anti–use-cases (the user should never have to): reconstruct a contract from invoices in a spreadsheet, hand-join invoices to terms, chase which of 3 stores is "true", or re-run a whole org to fix one contract.

3. Full flow F1 — Onboarding & backfill

Goal: stand up a tenant so its subledger equals (or is reconciled to) prior books.

Connect source (Chargebee creds)
  → Extract BULK window (all history)         [Temporal backfill]
  → Raw lake (immutable payloads)
  → Configure policies + SSP + calendar        [admin, see doc 11]
  → Normalize → domain events (ordered per contract)
  → Apply: open_contract / bill / pay / credit / amend  (idempotent)
  → Opening balances: deferred, AR, unbilled, revenue-to-date
  → Validate: shadow-compare vs prior system (accounting equality, not sheet equality)
  → Sign off opening balances → go live to incremental sync

Decisions to lock before go-live (per tenant): recognition calendar (daily vs monthly), functional currency, CN policy mapping, cancellation policy, SSP source. See 11-rules-reference.md.

Done when: opening deferred + revenue-to-date reconcile to prior books within tolerance, and an auditor can trace a sample contract end to end.

4. Full flow F2 — Steady-state sync (the apply loop)

Continuous, automatic, no user action.

Chargebee changes
  → Extract INCREMENTAL (cursor by updated_at / resource_version)   [Temporal schedule]
  → Raw lake append
  → Normalize → events   (subscription_created/changed/cancelled, invoice, payment, credit_note)
  → Apply (idempotent, ordered per subscription):
        subscription_created → open_contract
        subscription_changed → amend_contract
        invoice_generated    → record_billing
        payment_succeeded    → record_payment
        credit_note_created  → record_credit
        subscription_cancelled → terminate
  → Ops DB updated; AppliedEvent recorded

Properties (from 09): idempotent on (tenant, source, event_id); parallel by tenant/subscription; no full-history reload to understand current state; policies are config.

User visibility: sync health (lag, failures by entity), and any events parked as exceptions (unmapped policy, missing link) for review — see F7.

5. Full flow F3 — Monthly (or daily) close cycle

The controller’s core ritual. Period moves through explicit states.

Period state machine:
  OPEN ──pre-close──► READY ──recognize──► RECOGNIZED ──post──► POSTED ──lock──► LOCKED
                                   ▲                                  │
                                   └───────── reopen (pre-lock) ──────┘

Outcome: revenue + deferred + journals for the period, reconciled and auditable. This replaces "Camunda sync job finished loading Excel" with a real close workflow.

6. Full flow F4 — Mid-period change handling

Shows how UC4/UC5/UC6 travel through apply and surface in close. (Numbers: 04 S03/S04/S05.)

Change fact (upgrade / credit / cancel)
  → event → apply with NAMED POLICY (doc 11)
  → ops DB: remaining schedule reflows
        upgrade prospective : Jan–Jun untouched; Jul–Dec new amount
        CN refund_unrecog   : deferred ↓; recognized untouched
        cancel term.cancel  : remaining deferred resolved per policy
  → next recognize(period) uses the new schedule
  → audit trail links the change event → schedule delta

Key rule: past locked periods are never silently restated. A change effective in a closed period follows the modification/restatement rule in 11, not an in-place rewrite.

7. Full flow F5 — Audit & drill-down

The traceability chain that makes the product auditable (UC10).

GL journal line (period)
   ▼  post_journals
Subledger balance (revenue / deferred / AR)
   ▼
RecognitionScheduleLine (period, amount, status)
   ▼
PerformanceObligation (method, service window, allocated amount)
   ▼
Contract (customer, term, source_ref)
   ▼
AppliedEvent (type, policy applied, source_event_id)
   ▼
Raw payload in lake (verbatim Chargebee fact)

Every arrow is a stored link, not a re-computation. An auditor can pick any number and walk down to the original Chargebee JSON, and see which policy produced each treatment.

8. Full flow F6 — Reporting & disclosures

Served from projections (ClickHouse/analytics) off the subledger — reads never mutate state.

9. Full flow F7 — Exceptions & corrections

What happens when reality is messy (UC13).

Corrections are replay + policy, not manual spreadsheet edits. This is the payoff of event-sourced apply.

10. Use case → operation → entity quick map

Entity definitions: 08-mvp-spec.md §3.

11. Today vs Next (user-visible)

12. Open questions (track in decisions/)

1. Recognition calendar default: daily vs monthly (affects proration + schedule granularity).
2. Balance-sheet presentation: contract asset/liability labels required at MVP?
3. Restatement policy for facts landing in a locked period (catch-up vs prior-period adjustment).
4. RPO/disclosure scope for v1 (which ASC 606-10-50 disclosures are in scope).
5. Close cadence per tenant (monthly standard; any daily/continuous close demand?).