Claims Service — Service Overview
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD
Purpose
The claims-service is the bounded context responsible for the full payer claims and insurance coverage lifecycle. It merges two legacy modules — claims (ADMIN-CLAIMS) and insurance (ADMIN-INS) — into a single cohesive service. It owns: Coverage management, eligibility verification, prior authorization, claim assembly from encounter charges, claim scrubbing, electronic submission, remittance processing, and denial/appeal workflow.
It is an optional licensed add-on (ehr.claims). Unlicensed tenants receive 403 MODULE_NOT_LICENSED on write operations.
Bounded Context Responsibilities
| In scope | Out of scope |
|---|---|
| Coverage (insurance) CRUD and priority management | Charge capture (billing-service) |
| Eligibility inquiry and response storage (X12 270/271 + payer APIs) | Patient payment processing and PCI-scoped flows |
| Prior authorization tracking | Encounter documentation (scheduling-service) |
| Claim assembly from encounter charges | Clinical coding (ICD-10, CPT) entry (EHR layer) |
| Claim scrubbing and required-field validation | General ledger and financial accounting |
| Electronic submission via X12 837 and payer-specific adapters | Population health reporting (population-health-service) |
| Remittance processing (X12 835 and API equivalents) | |
| Denial tracking, appeal workflow, resubmission | |
| ExplanationOfBenefit generation | |
| FHIR R4 financial resources (Coverage, Claim, ClaimResponse, EOB, CoverageEligibilityRequest/Response) | |
| Multi-country adapter support (AFG/UAE payer formats) |
Upstream Dependencies
| Service | Why |
|---|---|
| registration-service | Patient identity (patientId) |
| scheduling-service | Encounter data (encounterId) for claim assembly |
| billing-service | Charge items and fee codes |
| identity-service | JWT claims, RBAC roles |
| terminology-service | ICD-10, CPT, DRG coding validation |
| audit-service | Audit pipeline for PHI mutations |
Downstream Dependents
| Service | Dependency |
|---|---|
| billing-service | Receives claim status and payment allocation events |
| patient-portal-service | Read-only view of EOBs and coverage status |
| population-health-service | Aggregate payer mix and denial rate metrics |
Key Architectural Decisions
- Merged claims + insurance. Legacy
ADMIN-CLAIMSandADMIN-INSmodules are consolidated into one service. One aggregate model, one API surface, one event namespace. - FHIR R4 canonical model.
Claim,ClaimResponse,Coverage,CoverageEligibilityRequest/Response,ExplanationOfBenefitare the canonical internal models; X12 and payer-specific formats are produced/consumed via pluggable adapters. - Pluggable submission adapter. A
ClaimSubmissionAdapterinterface allows X12 EDI, REST payer APIs, XML, and flat-file formats without changing core claim logic. - Transactional outbox. All domain events are published via outbox pattern.
- Tenant isolation via RLS. All tables contain
tenant_id; Postgres RLS enforces isolation.
Architecture Diagram
Slice Involvement
| Slice | Role |
|---|---|
| S2 — Revenue cycle | Core responsibility |
| S3 — Multi-country payer integration | AFG/UAE adapter configuration |
| S4 — Patient engagement | Portal EOB read projection |
Source Reconciliation
Sources: _sources/claims/ (ADMIN-CLAIMS v1.0) and _sources/insurance/ (ADMIN-INS v1.0). Merged into single service. Legacy FRs: FR-CLM-* (claims) and FR-INS-* (insurance) preserved alongside new FR-CLAIMS-* mapping. Single data model merges both aggregate families with common tenant_id isolation and outbox.