Skip to main content

Claims Service — Service Readiness

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

Readiness Checklist​

Documentation​

  • SERVICE_OVERVIEW.md — approved by Tech Lead
  • DOMAIN_MODEL.md — reviewed by domain expert
  • API_CONTRACTS.md — reviewed by consumer teams (billing-service, patient-portal-service)
  • DATA_MODEL.md — reviewed by DBA / infrastructure team
  • SECURITY_MODEL.md — reviewed by Security team
  • MIGRATION_PLAN.md — approved by Platform team

Code Quality​

  • Hexagonal architecture enforced: domain, application, infrastructure, presentation layers separated
  • No direct Postgres queries outside infrastructure/ layer
  • All payer adapters implement IClaimSubmissionAdapter interface
  • No hardcoded payer credentials or EDI sender IDs in source code
  • Vault integration wired for all external credentials

Testing​

  • Unit test coverage ≥ 90% (domain + application layers)
  • Integration test coverage ≥ 80% (branch)
  • Tenant isolation CI gate passing (adversarial cross-tenant test)
  • ERA idempotency integration test passing
  • Module entitlement gate test passing
  • Pact consumer contracts passing (billing-service, patient-portal-service)
  • FHIR golden fixtures passing (Claim, Coverage, ExplanationOfBenefit, CoverageEligibilityResponse)
  • E2E: full claim lifecycle scenario passing
  • E2E: denial + appeal scenario passing
  • EDI stub adapter used in all CI tests (no real payer calls in CI)

Security​

  • RLS policies verified on all tables (claims, coverages, eligibility_transactions, prior_authorizations, remittances, denial_cases)
  • Payer credentials stored in Vault (not in .env or DB)
  • RBAC matrix implemented and tested for all roles
  • Module entitlement gate (ehr.claims) enforced on all write operations
  • PHI audit events emitted for all claim and coverage mutations
  • Audit retention configured (7 years)
  • Security penetration test completed (cross-tenant, RBAC bypass, credential exposure)
  • Security sign-off obtained from Security team

Observability​

  • OpenTelemetry traces, metrics, logs wired
  • All SLI/SLO metrics registered in Prometheus
  • Dashboards deployed: Claims Pipeline, ERA Processing, Eligibility, Outbox Health, Payer Adapter
  • All alerts configured with runbook links
  • Health endpoints (/health/live, /health/ready, /health/startup) responding correctly

Operations​

  • Kubernetes Deployment manifests reviewed (including ERA worker Deployment)
  • HPA configured for main service and ERA worker
  • DB migration runbook documented
  • EDI clearinghouse credentials configured in Vault for production tenant(s)
  • Payer API credentials configured in Vault for production tenant(s)
  • SFTP/EDI connectivity tested for production clearinghouse
  • Runbooks written: high-denial-rate, adapter-failure, ERA-timeout, outbox-lag, payer-circuit-open
  • On-call rotation includes claims-service procedures

Sign-Off​

  • Tech Lead sign-off
  • Security team sign-off (security gate required before ehr.claims module activation)
  • QA sign-off
  • Product Owner sign-off