EU Billing Country-Packs — Pluggable Jurisdiction Billing

EU Billing Country-Packs — Pluggable Jurisdiction Billing

A second, RELATIONAL billing path that runs parallel to the FHIR billing facades: a full EU billing system-of-record (Coverage → ChargeItem → Invoice, plus the insurance Claim → ClaimResponse → PaymentReconciliation chain) stored in ddx_api_acc (Prisma-accounting), where all jurisdiction-specific behaviour — tariffs, VAT, payer schemes, e-invoice format — is keyed to a country PURELY by data through CountryPackService. Adding a new country (FR/CH/AT/MENA) is a DATA operation, never a code change.

Business Purpose

The FHIR billing path (see Billing) is optimised for interoperability — Invoice/Account/ChargeItem as FHIR R4 resources. But reimbursement in the EU is jurisdiction-specific: Germany uses GOÄ/EBM fee schedules with §238 HGB gap-less numbering; France uses CCAM/NGAP; each has its own VAT rules, payer-ID schemes, and e-invoice formats (ZUGFeRD, Factur-X). Branching billing logic on a literal country code per feature is a maintenance dead-end.

The country-pack model solves this with a single jurisdiction seam:

1. Relational system-of-record — EuBillingService owns Coverage / ChargeItem / Invoice CRUD + lifecycle in ddx_api_acc, with money kept in Prisma.Decimal (never JS float) and every query scoped by organizationId.
2. Pluggable country seam — CountryPackService is the ONLY place billing behaviour is keyed to a jurisdiction. Every billing service resolves tariff prices, VAT rules, and payer schemes THROUGH it by passing a country code — never by branching on a literal country.
3. Platform-shared catalogs — GOÄ/EBM/CCAM/NGAP/TARMED are federal fee schedules that do not differ per clinic, so CatalogService (CR-049) persists them as platform rows (organizationId = NULL), visible to every tenant, with per-org overrides layerable later.
4. ICD-10 diagnosis catalog — Icd10Service provides the diagnosis-code catalog (ICD-10-GM) used on charge items and claims.

Audiences

• Investor: adding a country is a data operation (INSERT a CountryPack + tariff/VAT rows) — no schema migration, no code change. This makes EU-wide expansion a configuration exercise, not an engineering project, and is the moat vs. HMS vendors who hard-code one country's rules.
• Clinical buyer: reception/finance staff bill in their jurisdiction's fee schedule (GOÄ/EBM for DE) with correct VAT and payer handling, without the software "knowing" it is German in code — the pack supplies it.
• Developer/partner: EuBillingController (@Controller('billing/eu')) + EuBillingService (relational, ACC-backed). Never branch on a literal country — resolve tariff/VAT/payer through CountryPackService. Catalog reads via CatalogService / Icd10Service. DTOs in billing/dto/eu-billing.types.
• Internal (ops/support): catalog rows are platform-shared (organizationId = NULL) per the products_platform_country_code_uq partial unique index (migration 20260522150000_catalog_platform_shared). The add-a-country runbook is ddx-api/docs/country-packs.md.

Architecture

billing/eu/ — relational EU billing system-of-record (ACC / Prisma-accounting)

billing/country-packs/

billing/catalog/ — platform-shared fee-schedule + diagnosis catalogs (CR-049)

insurance/claims-eu/ — insurer reimbursement chain (relational, ACC)

CatalogModule, EuBillingController, EuBillingService, CountryPackService, and TariffService are all wired into BillingModule (billing.module.ts). The FHIR facades and this relational path share the module but are independent write paths.

Tech Stack & Choices

Data Flow

Issue an EU invoice (tariff + VAT resolution)

POST /billing/eu/invoices/:id/... (ISSUE)
  → EuBillingService
      1. resolve active CountryPack by invoice.countryCode  ← CountryPackService
      2. for each line: net = TariffService(baseFee × factor) for (pack, codeSystem, code)
      3. per-line VAT resolution via the pack's VatRate rows
      4. enforce totalGross = totalNet + Σ vatAmount  (server-side invariant, AC-1/AC-3/AC-5)
      5. persist Invoice + InvoiceLineItem (prisma:acc), status DRAFT → ISSUED

Add a new country (data-only)

1. INSERT CountryPack (countryCode, currency, activeTariffCodeSystems, eInvoiceFormat, payerIdScheme)
2. INSERT TariffItem rows for that pack's code systems
3. INSERT VatRate rows tied to that pack
→ no schema migration, no code change. Runbook: ddx-api/docs/country-packs.md

Implicated Code

• ddx-api/src/financial/billing/eu/eu-billing.service.ts:196 — EuBillingService; relational Coverage/ChargeItem/Invoice CRUD + lifecycle in prisma:acc; tariff/VAT resolved via CountryPackService; enforces totalGross = totalNet + Σ vatAmount.
• ddx-api/src/financial/billing/eu/eu-billing.controller.ts:106 — EuBillingController @Controller('billing/eu'); coverages, charge-items (+ transition), invoices endpoints.
• ddx-api/src/financial/billing/eu/tariff.service.ts:26 — TariffService; CRUD over pack-keyed TariffItem rows; net unit price = baseFee × factor.
• ddx-api/src/financial/billing/country-packs/country-pack.service.ts:123 — CountryPackService; the pluggable jurisdiction seam; resolves tariff/VAT/payer scheme by country code.
• ddx-api/src/financial/billing/catalog/catalog.service.ts:141 — CatalogService (CR-049); GOÄ/EBM/CCAM/NGAP/TARMED platform-shared catalog (organizationId = NULL).
• ddx-api/src/financial/billing/catalog/icd10.service.ts:47 — Icd10Service; ICD-10-GM diagnosis catalog.
• ddx-api/src/financial/billing/catalog/catalog.controller.ts:85 — CatalogController; GET/POST billing/catalog(/search/:id), GET/POST billing/icd10(/search/:id).
• ddx-api/src/financial/billing/dto/eu-billing.types.ts — shared EU billing DTO types (also consumed by claims-eu).

Operational Notes

• Never branch on a literal country — all jurisdiction behaviour flows through CountryPackService. A if (country === 'DE') anywhere in the billing services is a regression against the seam design.
• Catalog rows are platform-shared — organizationId = NULL catalog rows are visible to every tenant (CR-049, migration 20260522150000_catalog_platform_shared). Do not scope catalog reads to a single org unless resolving a per-org override row.
• Money is Prisma.Decimal — never convert tariff/VAT amounts through JS number; rounding drift breaks the totalGross = totalNet + Σ vatAmount invariant.
• Two billing write paths coexist — the FHIR facades (Billing) are the interoperability projection; this relational path is the reimbursement system-of-record. They share BillingModule but write to different stores (HAPI FHIR vs ddx_api_acc). The composition wiring of the FHIR catalog onto the relational EuBillingService write path is noted as future work in billing.module.ts.
• AR clearing — settled EU billing / claims-eu PaymentReconciliation rows clear ArOpenItems via the accounting ReconciliationService, which posts the matching double-entry JournalEntry (see Accounting).

Related Topics

• Billing — Invoices, Charge Items and Pricing — the FHIR facade billing path this relational path runs parallel to.
• Accounting — Journal Entries, Budgets and Financial Reports — ReconciliationService clears AR open items from settled EU billing / claims-eu payments and posts the double-entry.
• Insurance and Coverage — Claims Management — the claims-eu submodule (Claim → ClaimResponse → PaymentReconciliation) shares this relational EU billing model.
• Prisma 7 Schemas — ddx_api_acc / PrismaAccountingService is the store for all EU billing + catalog rows.