medOS ultra

Note-Based Charging

Domain-separated architecture for charging derived from clinical notes.

2 min read diagramsUpdated 2026-05-28docs/architecture/note-based-charging.md

Status: Design approved 2026-05-28. Phase 1 in progress. Epic reference: eMERGE Note Based Charging tip sheet (provider-prompted charge filing after note signing). Plan file: .claude/plans/zesty-popping-tiger.md

Overview

When a billable provider signs a billable clinical note (H&P, Progress Note, Op Note, Discharge Summary, Consult Note, Procedure Note), the system auto-opens a charge filing modal. The provider selects charges from a preference list, attaches diagnosis pointers, modifiers, and bill area, then files or defers.

OFF by default for all existing markets (TH/JP/PH). Enabled per market via market_billing_config table — the US market pack seeds it ON.

Bounded Contexts

BC Domain New Tables Key Hook
BC1 Note Signing Events billable_note_types useNoteSigningEmitter
BC2 Charge Capture Session charge_preference_lists, charge_preference_items, note_charge_sessions, note_charges useNoteChargeSession, useChargePreferenceList
BC3 Provider Billing Identity provider_billing_credentials useResolveBillingProvider
BC4 Charge Attribution charge_diagnosis_links, billing_modifiers, place_of_service, bill_areas DiagnosisLinker, ModifierPicker, BillAreaSelector
BC5 Market Billing Adapter market_billing_config useMarketBillingConfig
BC6 Hospital-Insurance Bridge (no new tables - wires into existing Contract, payer, scheme, insurance_context) coverage-aware preference list enrichment

End-to-End Flow

Provider signs note
  -> useNoteSigningEmitter checks billable_note_types
  -> if is_billable && market_billing_config.enabled:
       auto-open NoteChargeModal (Epic style)
  -> Provider selects charges, attaches DX/modifiers/bill area
  -> "File Charges" -> note_charges rows -> MarketBillingAdapter -> charge_ledger
  -> trg_sync_billing_queue fires -> billing queue -> cashier
  -> OR "Defer" -> deferred session -> Charge Capture tab

Configuration by Hospital Type

Type note_based_charging Coverage-Aware Pre-Auth Split Posting
Thai public (UC/SSS) OFF N/A N/A N/A
Thai private ON (optional) YES YES (policy gates) YES
US hospital ON YES YES YES (CMS-1500/UB-04)
JP hospital OFF (auto-map) YES (kaigo) NO YES
PH hospital OFF (auto-map) YES (PhilHealth) NO YES

Key Files

File Purpose
infrastructure/medbase/migrations/20260528w_note_based_charging.sql Foundation tables + seeds
web/src/hooks/useMarketBillingConfig.ts Runtime market config hook
web/src/hooks/useNoteSigningEmitter.ts Note sign event emitter
web/packages/miniapps/charge-capture/index.tsx Existing charge capture UI (reused)
infrastructure/market-packs/medos-united-states/manifest.json US market pack (Phase 5)
  • docs/architecture/billing-rcm-unified-master.md — billing system overview
  • docs/architecture/insurance-aware-workflows.md — coverage infrastructure
  • docs/architecture/policy-gates.md — configurable workflow gates
  • docs/architecture/revenue-platform-master-plan/00-MASTER.md — multi-country billing
Ask Anything