Claims Service — Deployment Topology
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: SERVICE_OVERVIEW · Service Template · 02 DDD
Runtime
| Property | Value |
|---|---|
| Runtime | Node.js 22 LTS |
| Framework | NestJS 11 |
| Language | TypeScript 5.x |
| ORM | Drizzle ORM |
| Container | Docker (distroless Node 22) |
| Kubernetes | Deployment (not StatefulSet) |
Replicas
| Environment | Min Replicas | Max Replicas | HPA Trigger |
|---|---|---|---|
| Production | 3 | 10 | CPU > 60% or RPS > 200/instance |
| Staging | 2 | 4 | CPU > 70% |
| Development | 1 | 1 | — |
Runtime Dependencies
| Dependency | Type | Notes |
|---|---|---|
| PostgreSQL 16 | External | Primary store; claims DB; RLS enabled |
| NATS JetStream | External | Event streaming; outbox relay |
| Redis | External (optional) | Rate limiting; idempotency window cache for dedup |
| Keycloak | External | JWT issuer; tenant realm |
| terminology-service | Internal | ICD-10/CPT code validation |
| audit-service | Internal | PHI audit pipeline |
| HashiCorp Vault | External | Payer credentials, EDI sender IDs |
| EDI Clearinghouse | External | X12 837 submission, 999/835 receive |
| Payer REST APIs | External | Direct payer eligibility and claim APIs (per tenant config) |
Resource Limits
resources:
requests:
cpu: 200m
memory: 256Mi
limits:
cpu: 1000m
memory: 1Gi
ERA processing workers (separate Deployment):
resources:
requests:
cpu: 500m
memory: 512Mi
limits:
cpu: 2000m
memory: 2Gi
Kong Routes
| Route | Upstream | Notes |
|---|---|---|
/api/v1/claims-service/* | claims-service:3000 | Staff and service-to-service |
/fhir/R4/Coverage/* | claims-service:3000 | FHIR read surface |
/fhir/R4/Claim/* | claims-service:3000 | FHIR read surface |
/fhir/R4/ExplanationOfBenefit/* | claims-service:3000 | FHIR read; patient-portal-service consumer |
/fhir/R4/CoverageEligibilityRequest/* | claims-service:3000 | FHIR read surface |
/fhir/R4/CoverageEligibilityResponse/* | claims-service:3000 | FHIR read surface |
Environment Variables
| Variable | Description | Required |
|---|---|---|
DATABASE_URL | Postgres connection string | Yes |
DATABASE_POOL_SIZE | Connection pool size (default 20) | No |
NATS_URL | NATS JetStream URL | Yes |
REDIS_URL | Redis URL for rate-limit/dedup cache | No (optional) |
VAULT_ADDR | HashiCorp Vault address | Yes |
VAULT_ROLE | Vault Kubernetes auth role | Yes |
KEYCLOAK_URL | Keycloak base URL | Yes |
KEYCLOAK_REALM | Default realm name | Yes |
TERMINOLOGY_SERVICE_URL | terminology-service base URL | Yes |
AUDIT_SERVICE_URL | audit-service base URL | Yes |
EDI_SUBMISSION_MODE | x12_837 / payer_rest / stub | Yes |
EDI_CLEARINGHOUSE_URL | Clearinghouse SFTP/REST endpoint | If EDI_SUBMISSION_MODE=x12_837 |
CLAIM_DEDUP_WINDOW_HOURS | Hours within which duplicate claims are blocked (default 24) | No |
LOG_LEVEL | debug / info / warn / error (default info) | No |
PORT | HTTP listen port (default 3000) | No |
Data Residency
Claims data (financial PHI) must remain within the tenant's designated region. Multi-region deployment requires per-region Postgres clusters. NATS JetStream replicas must also be co-located within the region. Cross-region replication of claim data requires explicit legal and compliance approval.
ERA Ingest Worker
A separate Kubernetes Deployment (claims-era-worker) handles ERA ingestion:
- Polls the ingest queue (NATS subject
claims.era.ingest) - Parses X12 835 or payer REST ERA
- Calls
ProcessRemittanceUseCase - Scales independently of the main API service (1-3 replicas)