Claims Service — Domain Model

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: SERVICE_OVERVIEW · Service Template · 02 DDD

Aggregates

1. ClaimRecord (Root Aggregate)

Represents the full lifecycle of a single payer claim from assembly through final adjudication. Merges the ADMIN-CLAIMS aggregate family.

ID prefix: clm_

State Machine:

Fields:

Field	Type	Description
id	ClaimId (clm_)	ULID with prefix
tenantId	TenantId	RLS partition key
patientId	PatientId	From registration-service
encounterId	EncounterId	From scheduling-service
coverageId	CoverageId	Primary coverage reference
billProviderId	ProviderId	Billing provider NPI
renderingProviderId	ProviderId	Rendering provider NPI
serviceDate	DateRange	Service from/to dates
diagnosisCodes	ICD10Code[]	Ordered diagnosis list (max 12)
procedureCodes	ProcedureCode[]	CPT/HCPCS with modifiers
lineItems	ClaimLineItem[]	Charge items from billing-service
totalBilled	Money	Sum of line item billed amounts
status	ClaimStatus	Enum (see state machine)
submissionChannel	SubmissionChannel	X12_837 / PAYER_REST / XML / FILE
clearinghouseRef	string?	External tracking ID
payerClaimNumber	string?	Assigned by payer on acceptance
version	number	Optimistic concurrency counter
fhirClaimId	string?	FHIR Claim resource ID
createdAt	Timestamp
updatedAt	Timestamp

FHIR Mapping: Claim (canonical), ClaimResponse (on acknowledgement/remittance)

---

2. Coverage (Aggregate)

Represents a patient's insurance coverage record. Source: ADMIN-INS aggregate family.

ID prefix: cov_

Fields:

Field	Type	Description
id	CoverageId (cov_)	ULID with prefix
tenantId	TenantId	RLS partition key
patientId	PatientId	Patient this coverage belongs to
payerId	PayerId	Payer organization reference
subscriberId	string	Member/subscriber ID
groupNumber	string?	Group/plan number
planName	string	Human-readable plan name
priority	CoveragePriority	PRIMARY / SECONDARY / TERTIARY
relationship	SubscriberRelationship	SELF / SPOUSE / CHILD / OTHER
effectiveFrom	Date	Coverage start date
effectiveTo	Date?	Coverage end date (null = active)
copay	Money?	Fixed copay amount
deductible	Money?	Annual deductible
outOfPocketMax	Money?	Out-of-pocket maximum
status	CoverageStatus	ACTIVE / INACTIVE / CANCELLED
fhirCoverageId	string?	FHIR Coverage resource ID
createdAt	Timestamp
updatedAt	Timestamp

FHIR Mapping: Coverage

---

3. EligibilityTransaction (Aggregate)

Represents a real-time eligibility inquiry and the stored payer response. Source: ADMIN-INS FR-INS-003..005.

ID prefix: elig_

Fields:

Field	Type	Description
id	EligibilityId (elig_)	ULID with prefix
tenantId	TenantId	RLS partition key
coverageId	CoverageId	Coverage being verified
patientId	PatientId
requestedAt	Timestamp	Inquiry time
channel	EligibilityChannel	X12_270 / PAYER_REST
requestPayload	JsonB	Raw request (X12 or JSON)
responsePayload	JsonB	Raw payer response
status	EligibilityStatus	ACTIVE / INACTIVE / ERROR
deductibleMet	Money?	YTD deductible met
oopMet	Money?	YTD out-of-pocket met
coinsurance	Percentage?
expiresAt	Timestamp	Cache TTL for this response
fhirEligibilityRequestId	string?	FHIR CoverageEligibilityRequest ID
fhirEligibilityResponseId	string?	FHIR CoverageEligibilityResponse ID

FHIR Mapping: CoverageEligibilityRequest, CoverageEligibilityResponse

---

4. PriorAuthorization (Aggregate)

Tracks prior authorization requests and decisions for covered services.

ID prefix: auth_

Fields:

Field	Type	Description
id	AuthorizationId (auth_)	ULID with prefix
tenantId	TenantId
coverageId	CoverageId
patientId	PatientId
procedureCode	ProcedureCode	Requested procedure
diagnosisCodes	ICD10Code[]	Supporting diagnoses
requestedAt	Timestamp
status	AuthorizationStatus	PENDING / APPROVED / DENIED / EXPIRED
authorizationNumber	string?	Payer-assigned auth number
approvedUnits	number?	Approved service units
validFrom	Date?	Auth validity start
validTo	Date?	Auth validity end
denialReason	string?

---

5. RemittanceRecord (Aggregate)

Represents a processed ERA (Electronic Remittance Advice) — X12 835 or payer REST equivalent.

ID prefix: rem_

Fields:

Field	Type	Description
id	RemittanceId (rem_)	ULID with prefix
tenantId	TenantId
payerId	PayerId
checkNumber	string?	EFT/check reference
paymentDate	Date
totalPaid	Money
rawPayload	JsonB	Parsed X12 835 or REST payload
lineAllocations	RemittanceAllocation[]	Per-claim allocations
processedAt	Timestamp?	Time allocations applied
fhirEobIds	string[]	Generated ExplanationOfBenefit IDs

FHIR Mapping: ExplanationOfBenefit (generated per claim from remittance)

---

6. DenialCase (Entity — owned by ClaimRecord)

Tracks denial details and the appeal workflow for a denied claim line or claim.

ID prefix: dnl_

Fields:

Field	Type	Description
id	DenialId (dnl_)	ULID with prefix
claimId	ClaimId	Parent claim
denialCode	string	CARC / RARC denial reason code
denialReason	string	Human-readable reason
appealDeadline	Date	Deadline for appeal submission
appealStatus	AppealStatus	NONE / FILED / PENDING / APPROVED / DENIED
appealFiledAt	Timestamp?
appealNotes	string?
resubmitClaimId	ClaimId?	Replacement claim on resubmission

---

Domain Events

Event Type	Trigger	Payload Summary
claims.claim.created.v1	Claim assembled from encounter	claimId, patientId, encounterId, totalBilled
claims.claim.submitted.v1	Claim sent to payer/clearinghouse	claimId, channel, clearinghouseRef
claims.claim.accepted.v1	Positive acknowledgement received	claimId, payerClaimNumber
claims.claim.denied.v1	Denial received via remittance	claimId, denialCode, denialReason
claims.claim.paid.v1	Full payment applied	claimId, remittanceId, amountPaid
claims.claim.appealed.v1	Appeal filed	claimId, denialId, appealDeadline
claims.remittance.received.v1	ERA received and parsed	remittanceId, payerId, totalPaid
claims.remittance.applied.v1	ERA allocations posted to claims	remittanceId, claimsAffected[]
claims.coverage.created.v1	New coverage record added	coverageId, patientId, priority
claims.coverage.updated.v1	Coverage modified	coverageId, changes
claims.eligibility.verified.v1	Eligibility response received	eligibilityId, coverageId, status
claims.auth.approved.v1	Prior auth approved	authorizationId, authNumber, validTo

---

Value Objects

Value Object	Description
ClaimId	Branded ULID clm_*
CoverageId	Branded ULID cov_*
EligibilityId	Branded ULID elig_*
AuthorizationId	Branded ULID auth_*
RemittanceId	Branded ULID rem_*
DenialId	Branded ULID dnl_*
Money	{ amount: number; currency: string } — ISO 4217
ICD10Code	Validated ICD-10-CM code string
ProcedureCode	{ system: 'CPT' | 'HCPCS'; code: string; modifier?: string }
DateRange	{ from: Date; to: Date }
ClaimStatus	draft | ready | submitted | accepted | rejected | partial_paid | paid | denied | appealed | closed
CoverageStatus	active | inactive | cancelled
CoveragePriority	primary | secondary | tertiary
SubmissionChannel	x12_837 | payer_rest | xml | file
EligibilityChannel	x12_270 | payer_rest

---

Ubiquitous Language

Term	Definition
Claim	A request for payment submitted to a payer for services rendered
Coverage	An active insurance policy/plan for a patient
Eligibility	Real-time verification that a patient's coverage is active and what benefits apply
Prior Authorization	Advance payer approval required for certain services before they are rendered
Remittance	The payment and explanation advice returned by a payer after claim adjudication (ERA/835)
EOB	Explanation of Benefits — FHIR resource generated from remittance detailing payment and adjustments
Denial	Payer decision to not pay all or part of a claim
Appeal	Formal dispute of a denial requesting reconsideration
Clearinghouse	Third-party intermediary that translates and routes claims between providers and payers
CARC	Claim Adjustment Reason Code — standard denial/adjustment code on EOBs
RARC	Remittance Advice Remark Code — supplemental explanation code
Scrubbing	Pre-submission validation of claim required fields, coding rules, and payer-specific edits
Line Item	A single service/procedure entry within a claim
837	X12 837 EDI transaction — electronic claim submission format (837P professional, 837I institutional)
835	X12 835 EDI transaction — electronic remittance advice format
270/271	X12 270 (eligibility request) / 271 (eligibility response) EDI transactions