Billing & RCM Unified Master

Single entry point consolidating 9 billing/RCM docs: six-screen ownership matrix, three substrates + pipeline + export engine.

20 min read diagramsUpdated 2026-05-28docs/architecture/billing-rcm-unified-master.md

Status: unification draft (2026-05-27). Not a replacement for the nine source docs — a single entry point that resolves overlaps, names the canonical owner of each screen, and tells the end-to-end story in one read.

Why this doc exists: nine billing/RCM design docs have grown alongside each other. Several screens (Cashier, Close-Account, Tab 3 REP, CoderWorkstation) appear in 3+ docs; a handful of enums (ClaimStatus, CoderStatus/CodingStatus, scheme codes) collide; one route (/revenue-collection) is dead but still referenced. This doc maps that surface so a new reader doesn’t have to triangulate.

Read order for newcomers: this doc → the doc that owns the screen you care about → the substrate doc(s) it depends on. Don’t read all nine front-to-back.

0. One-paragraph TL;DR

The billing system is six operational screens (IPD billing arc) sitting on top of three substrates (pricing ledger, coverage axis, action-gating engine), feeding one revenue pipeline (the 8-stage RCM lifecycle), exported through one country-pluggable claim engine (NHSO 16-file generator for Thailand, multi-country registry stub for JP/PH/US). The whole thing is the spine of a larger revenue platform master plan (P0–P13) that adds payment-model abstraction, agentic substrate, and per-country pluggability.

SCREENS (operational UI)            SUBSTRATES (cross-cutting)             PIPELINE (lifecycle)
01 Coverage Authorization  ─┐                                      ┌─▶ CHECKOUT
02 Charges Edit            ─┤                                      ├─▶ CODING
03 Discharge Planning      ─┼─◀─  menu-price-ledger (pricing)      ├─▶ VALIDATION
04 Close-Account Dashboard ─┤      insurance-aware (coverage axis)  ├─▶ CLAIM_BATCH
05 Cashier Checkout        ─┤      policy-gates (action gating)     ├─▶ INVOICE
06 Invoice & Reconciliation┘                                       ├─▶ REP_RESULT
                                                                    ├─▶ AR_SETTLEMENT
                                                                    └─▶ SETTLED
                                                                              │
                                                            NHSO 16-file ◀────┘
                                                            export registry (multi-country)

1. The nine source docs (inventory)

#	Doc	Lines	Layer	Status	Single-sentence purpose
1	`ipd-billing-architecture.md`	453	Screens	design 2026-05-27	Six-screen IPD billing arc (01–06), Vajira-reverse-engineered, grounded against backend
2	`revenue-collection-progression-contract.md`	455	Screens	Phase 1 shipped 2026-05-20, `/revenue-collection` route is DEAD	3-tab progression (debtors group → export → REP) + 25-panel settlement workspace
3	`rcm-pipeline-unified-contract.md`	802	Pipeline	active 2026-05-27	Canonical 8-stage RCM lifecycle + type contracts + shared encounter pool
4	`nhso-revenue-engine-master-plan.md`	1179	Export	10 phases TBD	Missing chargemasters, auto-tagging, 16-file generator, revenue-optimization layers
5	`menu-price-ledger.md`	480	Substrate (pricing)	design, M0–M7 plan	Append-only `billable_ledger` + `resolve_menu_price()` — every queue row carries its price
6	`insurance-aware-workflows.md`	2207	Substrate (coverage)	design 2026-05-08, 0% built	4th orthogonal axis (Coverage) on `encounter_journey_cache.insurance_context`, SchemeSlot registry
7	`policy-gates-coverage.md`	303	Substrate (gating)	shipped, 6 gate points wired	Visual map of every UI button gated by the `policy_gates` JSON-predicate engine
8	`billing-queue-auto-sync.md`	259	Plumbing	shipped 2026-04-25	`trg_sync_billing_queue` — auto-spawn billing-pending rows from `financial_summary`
9	`revenue-platform-master-plan/00-MASTER.md`	294	Strategic	active 2026-05-27, P0–P13	Multi-country, multi-payment-model, agentic substrate envelope (Contract aggregate, VBHC, etc.)

Total surface: ~6,432 lines. About 30% is overlap or cross-reference.

2. The six screens — canonical owners and supporting docs

This is the screen-ownership matrix. ★ = primary owner (where to make changes). ✓ = supporting (reads from / extends / consumes). Read the primary first; consult supporting docs only when you need the layer they own.

#	Screen	Thai	Primary	Supporting	Status	Sandbox
01	Coverage Authorization (AR gate)	บัตรอนุมัติ / ลำดับสิทธิ	ipd-billing §4.01 ★	insurance-aware ✓	⚠️ prototype only	`CoverageRecordTarget.tsx`
02	Charges Edit (per-AN ledger)	แก้ไขรายการ ค่ารักษา	ipd-billing §4.02 ★	rcm-pipeline ✓, menu-price ✓	⚠️ partial — grid live-wired to `v_receivables_unified` (2026-05-28, rcm-pipeline §6.4)	`ReceivablesGridTarget.tsx`, `ChargeInquiryTarget.tsx`
03	Discharge Planning ward tick	พร้อมจำหน่าย	ipd-billing §4.03 ★	—	⚠️ flag spec’d, not built	`IpdBillCloseTarget.tsx` (partial)
04	Close-Account Dashboard	ปิด บัญชี	ipd-billing §4.04 ★	rev-collection-progression ✓, rcm-pipeline ✓	✅ exists `containers/revenue-settlement/`	`RevenueSettlementTarget.tsx`
05	Cashier Checkout	แคชเชียร์	ipd-billing §4.05 ★	rcm-pipeline ✓, menu-price ✓, billing-queue-sync ✓, nhso ✓	✅ exists `containers/cashier/`	—
06	Invoice & Reconciliation	ใบเรียกเก็บ / กระทบยอด	ipd-billing §4.06 ★	rev-collection-progression ✓, rcm-pipeline ✓, nhso ✓	⚠️ entity exists, generator designed	`ClaimAdjustmentDrawerTarget.tsx`, `RepImportTarget.tsx`

Screens beyond the IPD-billing six

Several screens belong to adjacent domains but plug into the same backbone. Listed here so this doc is a complete index — do not edit these from ipd-billing, edit their primary doc.

Screen	Thai	Primary	Status	Sandbox
Tab 1 `MedicalDebtorsGroup`	แก้ไขกลุ่ม ลูกหนี้	rev-collection-progression §3 ★	✅ Phase 1 shipped 2026-05-20	`Fdh16FileExportTarget.tsx`, `ArGroupEditorTarget.tsx`
Tab 2 `InvoiceRecord`	นำข้อมูล ออก	rev-collection-progression §3 ★	✅ Phase 1 shipped	—
Tab 3 REP / ใบเรียกเก็บ	บันทึก REP	rev-collection-progression §3 ★	⚠️ ipd-billing §4.06 references it as page 06	`RevenueSettlementTarget.tsx`
Medical Coder Landing	—	rcm-pipeline §4.1 ★	✅ shipped (commit 7c349cedd)	`MedicalCoderLandingTarget.tsx`
Coder Worklist	—	rcm-pipeline §4.1 ★	✅ shipped (commit 7c8e869c7)	`CodingWorklistTarget.tsx`
CoderWorkstation	—	rcm-pipeline §4.2 ★	✅ shipped	`CoderWorkstationTarget.tsx`
CDI Query Card	—	rcm-pipeline §4.2 ★	✅ shipped	—
Revenue Reports / FPA Dashboard	รายงานรายรับ	rcm-pipeline §4.4 ★	✅ wired	`RevenueReportsTarget.tsx`, `FpaDashboardTarget.tsx`
`/admin/nhso-masters` (4 tabs)	—	nhso §Phase 0 ★	❌ not built	—
Cashier auto-tag panel	—	nhso §Phase 2 ★	❌ not built	—
Charge reconciliation per-line	—	nhso §Phase 6 ★	❌ not built	—
Appeal / Write-off panels	อุทธรณ์ / จำหน่ายหนี้	nhso §Phase 7 ★	❌ not built	—
Fee Schedule prompt	—	nhso §Phase 8 ★	❌ not built	—
Revenue-at-Risk Dashboard	—	nhso §Phase 9 ★	❌ not built	—
HIPData / Authen Code	สปสช. Authen	nhso §Phase 4 ★	⚠️ partial (production `UcAuthenSettlementPanel`)	`UcAuthenSettlementTarget.tsx`
`/admin/policy-gates` + builder	กฎ ระบบ	policy-gates-coverage ★	✅ shipped	—
`` host + main-flow-editor scheme nodes	—	insurance-aware §3 ★	❌ not built (0% per ipd-billing cross-ref)	—
Bill Cycle Admin	—	rev-platform-master §13 ★	✅ wired (stubs)	`BillCycleAdminPageTarget.tsx`
Country profile / export registry	—	rev-platform-master §6 ★	❌ not built	`ExportTestTarget.tsx` (Thailand only)

Screens with no sandbox today (gap list): nhso /admin/nhso-masters, all Phase-7 appeal/write-off panels, Phase-8 fee schedule, Phase-9 revenue-at-risk, ``, scheme-aware flow-editor nodes, ipd-billing page 03 ward tick, ipd-billing page 06 reconciliation. Build these as sandbox targets first (see §9 sandbox conventions).

3. End-to-end story — one ordered read

This is the narrative that threads the screens through the substrates. Each step names the doc that owns it.

                                  ┌───────────────────────────┐
                                  │ PATIENT REGISTERS / ADMITS │
                                  │ (HN/VN/AN issued)          │
                                  └─────────────┬─────────────┘
                                                ▼
                ┌──────────────────────────────────────────────────────┐
   STEP 1      │ COVERAGE ASSIGNED                              [01]    │
   AR action   │ EpisodeOfCarePayorPlan rows created from intake        │
                │ → state PENDING → AWAITING_AR                          │
                │ Owned by: ipd-billing §4.01                            │
   substrate   │ Coverage context populated in encounter_journey_cache  │
                │ .insurance_context (insurance-aware §4.1 migration 070)│
                └──────────────────────────────────────────────────────┘
                                                ▼
                ┌──────────────────────────────────────────────────────┐
   STEP 2      │ CHARGES ACCRUE                                 [02]    │
   ongoing     │ Per-line SalesOrder.orderRequestItems[]                │
                │ Owned by: ipd-billing §4.02                            │
   substrate   │ Each line stamped via billable_ledger row              │
                │ (menu-price-ledger §M2-M4 + trg_or_case_costing_sync)  │
                │ Resolver chain: contract → scheme → payor → standard  │
                │ (menu-price-ledger D1 + resolve_menu_price())          │
                │ Per-line coverage routing (ลำดับสิทธิ) — see §7.6     │
   gating      │ place_order policy gate fires per-line                 │
                │ (policy-gates-coverage Gate 1, DialogOrder.tsx)        │
   plumbing    │ Top-ups (เงินมัดจำ) recorded at cashier in parallel    │
                │ (ipd-billing §4.05 + billing-queue-sync §1)            │
                └──────────────────────────────────────────────────────┘
                                                ▼
                ┌──────────────────────────────────────────────────────┐
   STEP 3      │ WARD: DISCHARGE-READY                          [03]    │
   single-tick │ Task[ward.discharge-readiness-check]:ready             │
                │ → encounter.billClosed = true                          │
                │ Owned by: ipd-billing §4.03                            │
                │ Canonical flag spec: delivery-room-remaining-backend   │
                │ (referenced by ipd-billing §15 + menu-price M6)        │
                └──────────────────────────────────────────────────────┘
                                                ▼
                ┌──────────────────────────────────────────────────────┐
   STEP 4      │ AR WORKBENCH: ASSIGN PAYER REFERENCE NUMBER    [01]    │
   AR action   │ The ONE billable-ready operational action              │
                │ EpisodeOfCarePayorPlan.claimCodeBkk / logNumber set   │
                │ → coverage state VERIFIED → CLOSED                     │
                │ Owned by: ipd-billing §4.01 (operational truth #1-2)   │
                │ ⚠️ Today this is the gate (NOT page 04 — that's read-  │
                │    only). Common mental model mistake.                 │
                └──────────────────────────────────────────────────────┘
                                                ▼
   ┌───────────────────────────────┐         ┌─────────────────────────────┐
   │ STEP 5: CASHIER COLLECTS  [05]│         │ STEP 6: OBSERVATIONAL    [04] │
   │ residual = ΣchargeS − Σtopups │         │ Close-Account Dashboard       │
   │            − Σclaimable        │◀──┬───▶│ color-coded exceptions        │
   │ Owned by: ipd-billing §4.05    │   │     │ Owned by: ipd-billing §4.04   │
   │ /cashier route fed by          │   │     │ ⚠️ Read-only, NOT a state    │
   │   trg_sync_billing_queue       │   │     │   transition                  │
   │   (billing-queue-sync §2)      │   │     │ Lives in containers/          │
   └────────────────┬───────────────┘   │     │   revenue-settlement/         │
                    │                   │     └─────────────┬─────────────────┘
                    │     CodingStatus enum (frontend)      │
                    │     CoderStatus enum (backend)        │
                    │     See §7.3 contradiction            │
                    ▼                                       │
   ┌────────────────────────────────────────────────────────┘
   │ STEP 7: CODING WORKLIST + WORKSTATION
   │ Auto-populated via fn_auto_populate_coding_worklist
   │   trigger on encounter_journey_cache
   │ Owned by: rcm-pipeline §4.1-4.2
   │ → 8-stage RCM pipeline begins (CHECKOUT done → CODING starts)
   └─┬──────────────────────────────────────────────────────
     │
     ▼
   ┌───────────────────────────────────────────────────────┐
   │ STEP 8: REVENUE COLLECTION (3 tabs)                    │
   │ Owned by: revenue-collection-progression §3            │
   │ ⚠️ /revenue-collection route is DEAD                  │
   │    (see §7.10 contradiction). Workspace lives in       │
   │    containers/revenue-settlement/ with 25+ panels.     │
   │ Tab 1: assign กลุ่มลูกหนี้                              │
   │ Tab 2: export 16 แฟ้ม (handoff to nhso engine)         │
   │ Tab 3: REP / ใบเรียกเก็บ (= ipd-billing page 06)       │
   └─┬──────────────────────────────────────────────────────
     │
     ▼
   ┌───────────────────────────────────────────────────────┐
   │ STEP 9: NHSO 16-FILE EXPORT                            │
   │ ADP/ADT/CHA/CHT/DIA/DRG/INS/IPD/IRF/LVD/ODX/OOP/OPD/   │
   │ ORF/PAT/PRO                                            │
   │ Lives in: eclaim-connector/generators/nhso-16files.ts  │
   │ Owned by: nhso-revenue-engine §Phase 3                 │
   │ Auto-tag fed by: nhso §Phase 2 (charge category map)   │
   │ Eligibility from: nhso §Phase 4 (HIPData/Authen Code)  │
   └─┬──────────────────────────────────────────────────────
     │
     ▼
   ┌───────────────────────────────────────────────────────┐
   │ STEP 10: REP RESULT → AR SETTLEMENT → SETTLED          │
   │ rcm-pipeline §1 stages 5-7                             │
   │ DialogImportRepBill (rev-collection-progression §7)    │
   │   loads response → rcm_charge_reconciliation           │
   │   (nhso §Phase 6) → advance to AR_SETTLEMENT           │
   │ Denial → DenialTriagePanel (nhso §Phase 7) → appeal /  │
   │   write-off                                            │
   └────────────────────────────────────────────────────────┘

4. The three substrates

These are cross-cutting — every screen above either reads them or writes them. They are not owned by any screen doc.

4.1 Pricing — `menu-price-ledger.md`

What it owns: menu_items (Supabase projection of financial.Product), menu_item_price_history, billable_ledger (append-only), resolve_menu_price() Postgres function, trg_or_case_costing_sync_ledger.

Resolution order (D1): contract → scheme → payor → standard.

Migration order: M0 (event-naming bridge) → M1 (menu_items + D6 schema re-export) → M2 (ledger shadow) → M3 (resolve fn) → M4 (orchestrator handlers + D5 trigger) → M5 (shadow→canonical cutover) → M6 (ER/LR encounter-driven ledger) → M7 (swap salesOrder pricing — deferred).

Read by: every queue row writer, cashier UI running totals, pre-op briefings (estimate=true filter), FPA fact tables (long-term), reconciliation diffs.

4.2 Coverage — `insurance-aware-workflows.md`

What it owns: encounter_journey_cache.insurance_context JSONB column (migration 070), benefit_schemes lookup table (migration 073), workflow_templates.scheme_overlay_of + scheme_codes (071), edge condition JSONB DSL on workflow_templates.edges, four ReactFlow node types (SchemeBranchNode, CoverageCheckNode, PreauthGateNode, SchemeSlotNode), `` registry-driven host component.

Edge DSL primitives: schemeIn / schemeNotIn / entitlementHas / entitlementNot / coverageStatus / all / any / not.

Status: 0% built — all five phases TBD. Migrations 070-075 not yet shipped.

4.3 Action gating — `policy-gates-coverage.md` (+ `policy-gates.md`)

What it owns: policy_gates table (scope_json, predicate_json, action_json, graph_json), /admin/policy-gates form editor, /admin/policy-gates/builder ReactFlow visual builder, usePolicyGate(ctx) hook, evaluateGates(rules, ctx) engine, graphToGate() serializer.

Wired today (6 gates): place_order (DialogOrder), collect_specimen × 3 dialogs, send_specimen × 2 dialogs.

Phase 2 candidates declared but not wired: dispense_medication, perform_imaging, discharge_patient, admit_patient, cancel_order.

ipd-billing §2/§7 proposes new triggers (rebind_coverage, transfer_charge, split_charge, route_act) — these need a coordination decision; see §7.14.

4.4 Plumbing — `billing-queue-auto-sync.md`

What it owns: trg_sync_billing_queue Postgres trigger + sync_billing_queue_from_financial_summary() function, two-layer patient-context backfill (SQL trigger trg_propagate_patient_context + frontend usePatientContextBackfill hook), useWorkflowConfigWorklist lift logic.

Reads: encounter_journey_cache.financial_summary. Writes: department_queues with dept_type='billing'.

Why it’s here: every page-05 cashier row reaches the UI through this trigger. Without it, billing-pending encounters never queue.

5. The pipeline — `rcm-pipeline-unified-contract.md`

Canonical 8 stages (frontend PIPELINE_STAGES const has 7 because CHECKOUT is implicit — see §7.2 below):

1 CHECKOUT       → cashier (page 05 finishes)
2 CODING         → coder worklist + workstation
3 VALIDATION     → rcmValidation service + coding-rules-engine edge fn
4 CLAIM_BATCH    → batch creation, eclaim-connector
5 INVOICE        → claimInvoice + ClaimInvoiceEncounter linkage
6 REP_RESULT     → DialogImportRepBill → rcm_charge_reconciliation
7 AR_SETTLEMENT  → settlement service + ar-close workflow
8 SETTLED        → marked C, collection code stamped, loop closes

Types defined here (use these names everywhere): CodingOutput, ReceivableRow, AnomalyFlag, EncounterPipelineState, shared 80-encounter mock pool contract (transform functions per surface), SCHEME_COLORS palette, PIPELINE_STAGES const.

Cross-nav links (frontend): coder landing ↔ worklist ↔ workstation ↔ ReceivablesDataGrid ↔ revenue settlement ↔ FPA dashboard.

Status: frontend visualization + contract layer largely shipped. Read model now live (2026-05-28): v_receivables_unified + prereqs (20260528f contract aggregate, 20260528p claim lifecycle, 055 journey-cache columns) applied to demo Supabase; the Receivables grid reads it via the useReceivablesUnified hook (live at 91 rows). See rcm-pipeline §6.4. Still pending: coding migrations 041/042 deployment, the rcm.pipeline.advance write command, and amount/name key-mapping (cosmetic).

6. The export engine — `nhso-revenue-engine-master-plan.md`

10 phases, ~12,700 LOC, 62 files, 8 new tables, 3 new edge functions. None built. Lives at infrastructure/medbase/functions/eclaim-connector/generators/nhso-16files.ts (to be created).

Phase	Scope	Outputs
0	Charge item masters	`nhso_adp_master`, `nhso_chrgitem_map`, `nhso_fee_schedule`, `nhso_project_code_rule`, `nhso_ucef_marker` + `/admin/nhso-masters` UI (4 tabs)
1	TMT/TMLT terminology seeds	Backfill `terminology_concept_map`
2	Auto-tagger	`nhso-auto-tagger` edge fn + cashier panel + `BatchCreationPanel` summary
3	16-file generator	ADP/ADT/CHA/CHT/DIA/DRG/INS/IPD/IRF/LVD/ODX/OOP/OPD/ORF/PAT/PRO
4	HIPData / Authen Code	`hipdata-connector` + patient eligibility cache
5	Revenue optimization	`revenue-optimizer` edge fn + `RevenueSuggestionPanel`
6	Charge-level reconciliation	`rcm_charge_reconciliation` + extended `ReconciliationLedgerDetailDialog`
7	Appeal / Write-off workflow	`DenialTriagePanel` + `AppealPreparationDialog` + `AppealBatchPanel` + `WriteOffApprovalDialog` + `DenialAnalyticsDashboard`
8	Fee schedule	`FeeSchedulePrompt` + `/admin/department-nhso-config`
9	Revenue-at-Risk dashboard	6 sections: leakage waterfall, coding opportunity, submission timeliness, denial prevention, auto-tag coverage, per-scheme profitability

Multi-country future: the rev-platform-master P0c phase moves this generator into a country-pluggable export registry so Japan (介護, kaigo) and Philippines (PhilHealth) get peer engines, not forks.

7. Overlap & contradiction report

The unification audit found 20 specific overlaps. Listed here as a deduplication map with the recommended canonical owner. Numbers track the source audit.

7.1 Aligned cross-doc dependencies (no action needed)

#	Topic	Layer references	Verdict
1	`trg_sync_billing_queue`	billing-queue-sync §2-3 defines; ipd-billing §8 + rcm-pipeline §3 + menu-price reference	Aligned
14	`policy_gates` reach	policy-gates-coverage owns; ipd-billing §2/§7 + insurance-aware §2 extend	Aligned
16	REP import path	rev-collection-progression §7 → nhso §Phase 6 → rcm-pipeline §1 stage 5	Aligned chain
13	`billable_ledger.metadata.estimate` for OR	menu-price D3/D5 owns, single-doc	Aligned
11	`encounter.billClosed` canonical home	External (`delivery-room-remaining-backend-work.md`); ipd-billing + menu-price both defer	Aligned, external owner

7.2 Real contradictions to resolve

#	Topic	Conflict	Recommended resolution
2	Pipeline stage count: 8 vs 7 vs 3 vs 6	rcm-pipeline §1 declares 8 stages but `PIPELINE_STAGES` const has 7; rev-collection-progression §2 uses 3; ipd-billing §3 uses 6 screens	✅ RESOLVED 2026-05-28 in favor of 7. The shipped DB enum `rcm_pipeline_stage` (migration `20260528s`) = `CODING…SETTLED` (7), matching the frontend const. CHECKOUT is the entry condition into CODING, not a stage. The TL;DR/§5 “8-stage” framing is the outlier — read it as “7 pipeline stages + CHECKOUT gate”. Other docs describe surfaces over the pipeline.
3	`CoderStatus` vs `CodingStatus` enum	rcm-pipeline §11 presents 1:1; rev-platform-master §4.1 corrects to “loose 1:1” with backend typo `REGISTED`	Trust rev-platform-master §4.1. Patch rcm-pipeline §11 to call out the loose mapping. Fix backend typo `REGISTED → REGISTERED` (separate ticket).
4	`ClaimStatus` enum	rcm-pipeline §2.3: `Prepare\|Pending\|Verified\|Exported\|Mismatch\|Flagged`. rev-collection-progression §2: `Prepare→Pending→Reviewing` + `Draft\|Confirmed\|Exported\|Sent\|Settled`	Two different enums for two different objects. SalesOrder.claimStatus (rev-collection) vs ClaimInvoice.status (rcm-pipeline). Rename one — recommend `ReceivableLifecycleStatus` for the rcm-pipeline version. Doc this in §2 of rcm-pipeline.
8	Chargemaster ownership: `menu_items` vs `nhso_adp_master`	menu-price-ledger and nhso §Phase 0 both claim chargemaster territory; nhso plan does not reference `menu_items`	menu-price `menu_items` is the canonical price catalog. nhso `nhso_adp_master` is a mapping table (`menu_item_id → ADP code`), not a parallel catalog. Update nhso §Phase 0 to declare this FK relationship. Sequencing: menu-price M1 must ship before nhso Phase 0.
10	`/revenue-collection` route status	rev-collection-progression §12 explicitly: “DEAD”. rcm-pipeline §7 still links to it	Patch rcm-pipeline §7 to link `/revenue-settlement` instead, or revive the route (rev-collection §12 says container exists). Decide before next demo.
17	Multi-tenancy stance	menu-price D4: no `tenant_id`, on-prem only. rev-platform-master §6 principle 10: `tenantId` on every aggregate, day-one	Strategic intent (rev-platform-master) supersedes implementation shortcut (menu-price D4). When cloud tenancy migration arrives (rev-platform-master P0c), menu-price tables must be backfilled. Add a TODO marker in menu-price §“Schema additions”.
20	Scheme code vocabulary	At least 4 styles: `ลูกหนี้ สปสช.` (rev-collection §14), `philhealth/kaigo/sss/nhso/private/self_pay` (insurance-aware §4.4), `UC/SSS/CSMBS/LGO/MVA/INS/SELF/AIA` (rcm-pipeline §5), `NHSO_UC` (nhso)	insurance-aware §4.4 `benefit_schemes` is the only doc proposing a centralized lookup table. Adopt those canonical codes. Add a translation layer in rcm-pipeline §5 mapping each frontend display style to the canonical code.

7.3 Complementary (no action — different layers)

#	Topic	Layers
5	Discharge readiness signal	`SalesOrder.status='Paid'` (rcm-pipeline) ≠ `encounter.billClosed` (ipd-billing) — different events at different times
6	Per-line coverage binding	encounter-level (insurance-aware) → per-line ledger row (menu-price) → display (ipd-billing)
7	16-file generator location	rcm-pipeline §8 declares it; nhso §Phase 3 owns the implementation; ipd-billing §4.06 + rev-collection §7 are call sites
9	Split rule location	absolute amount = `resolve_menu_price()` (menu-price); split proportion = `resolveSplit` BRE (ipd-billing §7)
12	Coverage write vs read	Mongo `EpisodeOfCarePayorPlan` (write, ipd-billing) vs Supabase `insurance_context` (read, insurance-aware) — different stores by design
15	Coding worklist source	`coding_worklist` table (rcm-pipeline) ≠ `encounter_coded_diagnosis` (rev-platform-master) — worklist vs artifact
18	`fpa_fact_charge` data source	Long-term plan moves from `salesOrder` (status quo) to `billable_ledger`. Sequence: menu-price M5 before nhso Phase 6.
19	Cashier ownership	Screen = ipd-billing §4.05; route mechanics = billing-queue-sync; running totals = menu-price; pipeline stage = rcm-pipeline. Four layers of the same screen.

8. Reconciliation TODOs

Concrete edits to source docs that this unification surfaced. Each is a small, mechanical patch — not a redesign.

rcm-pipeline §1 — add explicit CHECKOUT to PIPELINE_STAGES const ✅ RESOLVED 2026-05-28 the other way: shipped DB enum rcm_pipeline_stage + frontend const both = 7 stages; CHECKOUT stays the pre-pipeline entry gate. No const change. See contradiction #2.
rcm-pipeline §11 — replace “1:1” with “loose 1:1” + note backend REGISTED typo, link to rev-platform-master §4.1.
rcm-pipeline §2.3 — rename ClaimStatus → ReceivableLifecycleStatus, declare it’s distinct from SalesOrder.claimStatus.
rcm-pipeline §5 — add SCHEME_COLORS → benefit_schemes.code translation note.
rcm-pipeline §7 — replace /revenue-collection links with /revenue-settlement (or revive the route).
nhso §Phase 0 — declare nhso_adp_master.menu_item_id FK to menu_items; declare sequencing (menu-price M1 → nhso Phase 0).
menu-price §“Schema additions” — add multi-tenancy TODO marker per rev-platform-master P0c.
insurance-aware §4.4 — promote benefit_schemes to “canonical scheme vocabulary” status; add adoption note for other docs.
policy-gates-coverage §“Phase 2” — coordinate with ipd-billing §2/§7 proposed triggers (rebind_coverage, transfer_charge, split_charge, route_act). Pick a sequencing decision.
All nine docs — add a top-line link back to this doc: **See also:** billing-rcm-unified-master.md.

9. Sandbox conventions pattern

The pattern that has worked for shipping these screens:

Sandbox-first. Every new screen lands in web/sandbox/targets/Target.tsx with a mock data fixture before any production wiring. This is what enabled the 7-target dangling-stash recovery on 2026-05-21.
Shared encounter pool. Use the 80-encounter mock pool (rcm-pipeline §5.2 transform functions) so every sandbox shares the same patient/encounter/scheme cast — cross-surface navigation works in the sandbox the same way as production.
Register in web/sandbox/registry.ts. Comment-out entries are stripped by the recovery process; if you stash, untracked files in the registry can orphan.
Production passthrough when ready. Once wired, sandbox target re-exports the production component (IpdSystemsShowcaseTarget is the pattern reference).
Same-day backup file naming. If you rewrite an existing target, save the previous version as Target..tsx (see ArGroupEditorTarget.2026-05-27.tsx + RevenueSettlementTarget.2026-05-27.tsx for the convention).

Gap list — sandbox targets to build next (from §2 above):

Doc	Screen	Suggested target file
nhso §Phase 0	`/admin/nhso-masters` 4 tabs	`NhsoMastersTarget.tsx`
nhso §Phase 7	DenialTriagePanel	`DenialTriageTarget.tsx`
nhso §Phase 7	AppealPreparationDialog + AppealBatchPanel	`AppealPreparationTarget.tsx`
nhso §Phase 7	WriteOffApprovalDialog	`WriteOffApprovalTarget.tsx`
nhso §Phase 7	DenialAnalyticsDashboard	`DenialAnalyticsTarget.tsx`
nhso §Phase 8	FeeSchedulePrompt	`FeeScheduleTarget.tsx`
nhso §Phase 9	Revenue-at-Risk 6-section dashboard	`RevenueAtRiskTarget.tsx`
nhso §Phase 5	RevenueSuggestionPanel	`RevenueSuggestionTarget.tsx`
ipd-billing §4.03	Ward discharge-readiness tick	`WardDischargeReadyTarget.tsx`
ipd-billing §4.06	Invoice & Reconciliation full page	`InvoiceReconciliationTarget.tsx`
insurance-aware §3	`` host demo	`SchemeSlotHostTarget.tsx`
insurance-aware §3	main-flow-editor scheme-aware nodes	`SchemeFlowEditorTarget.tsx`

10. Cross-reference index

By concern

Question	Read
How does a charge get a price?	menu-price-ledger §M1-M4
How does coverage attach to a charge?	ipd-billing §4.02 (per-line) + insurance-aware §4.1 (encounter-level)
How does the cashier know what to collect?	ipd-billing §4.05 + billing-queue-auto-sync §1
How does the worklist auto-populate?	rcm-pipeline §4.1 (`fn_auto_populate_coding_worklist`)
How does a claim file get generated?	nhso-revenue-engine §Phase 3
How does a denial come back?	rcm-pipeline §1 stage 5-6 + nhso §Phase 7
What gates a particular button?	policy-gates-coverage (the 6 wired gates)
Where do I add a per-country scheme?	insurance-aware §4.4 `benefit_schemes` + rev-platform-master §6
How do I add a new payment model?	rev-platform-master §3 Contract aggregate (P3)
Why is `/revenue-collection` 404’ing?	rev-collection-progression §12 — route is dead, use `/revenue-settlement`

By doc

ipd-billing-architecture.md · revenue-collection-progression-contract.md · rcm-pipeline-unified-contract.md · nhso-revenue-engine-master-plan.md · menu-price-ledger.md · insurance-aware-workflows.md · policy-gates-coverage.md · billing-queue-auto-sync.md · revenue-platform-master-plan/00-MASTER.md

encounter-orchestrator-triggers.md · admission-to-ward-unified-contract.md · delivery-room-remaining-backend-work.md · fpa-data-warehouse.md · medical-coder-remaining-backend-work.md · cross-region-policy-gates-deployment.md · acknowledgement-system.md · cron-jobs-registry.md

11. Change log

2026-05-27 — initial unification draft. Audited 9 docs (6,432 lines), produced screen ownership matrix, end-to-end story, 20-item overlap report, 10 reconciliation TODOs. Sandbox gap list compiled.
2026-05-28 — Receivables read model went live. v_receivables_unified + prereqs (20260528f/20260528p/055) applied to demo Supabase hynsmfrevlsegbmjnoiy; 6 latent bugs in the view SQL fixed; useReceivablesUnified hook built; ReceivablesGridTarget reads it live (91 rows). Screen 02 + §5 status updated. Contradiction #2 + TODO #1 (8-vs-7 stages) resolved in favor of 7 (CHECKOUT = entry gate, not a stage), confirmed by the shipped rcm_pipeline_stage enum. New read model documented in rcm-pipeline §6.4.