Claims Service — Application Logic
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: SERVICE_OVERVIEW · Service Template · 02 DDD
Command Use Cases
| ID | Use Case | Actor | FR References |
|---|---|---|---|
| UC-CLM-C01 | AssembleClaim | billing-service (system) | FR-CLAIMS-001, FR-CLM-001 |
| UC-CLM-C02 | ScrubAndValidateClaim | system (pre-submit) | FR-CLAIMS-002, FR-CLM-002 |
| UC-CLM-C03 | SubmitClaim | billing-staff, system | FR-CLAIMS-003, FR-CLM-003 |
| UC-CLM-C04 | ProcessAcknowledgement | system (adapter) | FR-CLAIMS-004, FR-CLM-004 |
| UC-CLM-C05 | ProcessRemittance | system (adapter) | FR-CLAIMS-005, FR-CLM-005 |
| UC-CLM-C06 | FileDenialAppeal | billing-staff | FR-CLAIMS-006, FR-CLM-006 |
| UC-CLM-C07 | ResubmitClaim | billing-staff | FR-CLAIMS-007, FR-CLM-007 |
| UC-CLM-C08 | CreateCoverage | registration-staff, system | FR-CLAIMS-008, FR-INS-001 |
| UC-CLM-C09 | UpdateCoverage | registration-staff | FR-CLAIMS-009, FR-INS-002 |
| UC-CLM-C10 | VerifyEligibility | system (pre-visit), billing-staff | FR-CLAIMS-010, FR-INS-003 |
| UC-CLM-C11 | RequestPriorAuthorization | clinician, billing-staff | FR-CLAIMS-011, FR-INS-006 |
| UC-CLM-C12 | RecordAuthorizationDecision | system (adapter) | FR-CLAIMS-012, FR-INS-007 |
Query Use Cases
| ID | Use Case | Actor | Description |
|---|---|---|---|
| UC-CLM-Q01 | GetClaim | billing-staff, billing-service | Full claim detail with line items and status |
| UC-CLM-Q02 | ListClaims | billing-staff | Filtered/paginated list; filter by status, date, patient |
| UC-CLM-Q03 | GetCoverage | billing-staff, patient-portal | Coverage record with priority and benefit details |
| UC-CLM-Q04 | ListPatientCoverages | billing-staff, patient-portal | All coverages for a patient, ordered by priority |
| UC-CLM-Q05 | GetEligibilityResult | billing-staff | Most recent eligibility response for a coverage |
| UC-CLM-Q06 | GetRemittance | billing-staff | ERA summary with per-claim allocations |
| UC-CLM-Q07 | GetExplanationOfBenefit | patient-portal, billing-staff | FHIR EOB for a specific claim |
| UC-CLM-Q08 | GetClaimsByEncounter | billing-service | All claims for a given encounter |
Ports (Interfaces)
| Port | Direction | Description |
|---|---|---|
IClaimRepository | Outbound | Persist/load ClaimRecord aggregates |
ICoverageRepository | Outbound | Persist/load Coverage aggregates |
IEligibilityRepository | Outbound | Persist/load EligibilityTransaction records |
IRemittanceRepository | Outbound | Persist/load RemittanceRecord aggregates |
IClaimSubmissionAdapter | Outbound | Pluggable: submit claim to payer/clearinghouse |
IEligibilityAdapter | Outbound | Pluggable: real-time eligibility inquiry |
IAuthorizationAdapter | Outbound | Pluggable: prior auth request/response |
ITerminologyPort | Outbound | ICD-10/CPT code validation via terminology-service |
IOutboxRepository | Outbound | Write domain events to transactional outbox |
IAuditPort | Outbound | Emit audit records for PHI mutations |
IFhirMapper | Internal | Translate internal models ↔ FHIR R4 resources |
Key Sequence Diagrams
Claim Assembly and Submission
Remittance Processing
Eligibility Verification
Outbox Pattern
All domain events are written in the same Postgres transaction as the aggregate mutation. A relay worker polls claims_outbox and publishes to NATS JetStream with at-least-once delivery. Consumer idempotency is enforced via the outboxId as CloudEvents id.
claims_outbox table:
id ULID PK
event_type TEXT (e.g. claims.claim.submitted.v1)
payload JSONB
published BOOL DEFAULT false
created_at TIMESTAMPTZ
tenant_id TEXT (for multi-tenant relay filtering)
Error Codes
| Code | HTTP | Meaning |
|---|---|---|
CLAIM_NOT_FOUND | 404 | Claim ID does not exist for tenant |
CLAIM_INVALID_STATE | 409 | Operation not valid in current claim state |
CLAIM_VALIDATION_FAILED | 422 | Scrubbing found required field or coding errors |
COVERAGE_NOT_FOUND | 404 | Coverage ID does not exist for tenant |
COVERAGE_INACTIVE | 422 | Coverage is expired or cancelled |
ELIGIBILITY_EXPIRED | 422 | Eligibility result is stale; re-verify required |
AUTH_NOT_FOUND | 404 | Prior authorization not found |
SUBMISSION_FAILED | 502 | Clearinghouse/payer submission error |
CODING_INVALID | 422 | ICD-10 or CPT code failed terminology validation |
MODULE_NOT_LICENSED | 403 | Tenant does not have ehr.claims entitlement |
DUPLICATE_CLAIM | 409 | Identical claim already submitted within dedup window |
REMITTANCE_ALREADY_APPLIED | 409 | ERA has already been processed |