Claims Service — Local Dev Setup

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

Prerequisites

• Docker Desktop (or Docker Engine + Compose v2)
• Node.js 22 LTS + pnpm 9
• ghasi-e-documentation repo cloned

docker-compose.yml

version: "3.9"
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: claims_dev
      POSTGRES_USER: claims_app
      POSTGRES_PASSWORD: dev_password
    ports:
      - "5442:5432"
    volumes:
      - claims_pg_data:/var/lib/postgresql/data

  nats:
    image: nats:2.10-alpine
    command: ["-js", "-m", "8222"]
    ports:
      - "4222:4222"
      - "8222:8222"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    command: start-dev
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    ports:
      - "8080:8080"

volumes:
  claims_pg_data:

.env.example

DATABASE_URL=postgresql://claims_app:dev_password@localhost:5442/claims_dev
NATS_URL=nats://localhost:4222
REDIS_URL=redis://localhost:6379
KEYCLOAK_URL=http://localhost:8080
KEYCLOAK_REALM=ghasi-dev
TERMINOLOGY_SERVICE_URL=http://localhost:3010
AUDIT_SERVICE_URL=http://localhost:3020
EDI_SUBMISSION_MODE=stub
CLAIM_DEDUP_WINDOW_HOURS=24
LOG_LEVEL=debug
PORT=3007

Setup Commands

# 1. Start infrastructure
docker compose up -d

# 2. Install dependencies
pnpm install

# 3. Copy and configure environment
cp .env.example .env

# 4. Run database migrations
pnpm run db:migrate

# 5. Seed reference data (payers, tenant, test coverage records)
pnpm run db:seed

# 6. Start service in development mode
pnpm run start:dev

Seed Data

pnpm run db:seed creates:

• Tenant: tenant_dev_01 (with ehr.claims entitlement)
• Payers: 3 sample payer records (BlueCross stub, Medicaid stub, Private stub)
• Patient coverage: 2 coverage records for test patient pat_dev_01 (primary + secondary)
• Terminology stubs: Local claim-relevant ICD-10/CPT codes for offline dev

Common Development Commands

# Run unit tests
pnpm run test

# Run integration tests (requires Docker infrastructure up)
pnpm run test:integration

# Run all tests with coverage
pnpm run test:coverage

# Type check
pnpm run type-check

# Lint
pnpm run lint

# Run DB migrations (after schema changes)
pnpm run db:migrate

# Generate new migration
pnpm run db:generate -- --name <migration_name>

Verify Service

# Health check
curl http://localhost:3007/health/ready

# List claims (should return empty array initially)
curl -H "Authorization: Bearer <dev-jwt>" \
     -H "X-Tenant-ID: tenant_dev_01" \
     http://localhost:3007/api/v1/claims

# List coverages for test patient
curl -H "Authorization: Bearer <dev-jwt>" \
     -H "X-Tenant-ID: tenant_dev_01" \
     "http://localhost:3007/api/v1/coverages?patientId=pat_dev_01"

# Trigger eligibility check for seeded coverage
curl -X POST \
     -H "Authorization: Bearer <dev-jwt>" \
     -H "X-Tenant-ID: tenant_dev_01" \
     http://localhost:3007/api/v1/coverages/cov_dev_01/eligibility-checks

Dev JWT

A development JWT with tenant_id: tenant_dev_01 and roles: [billing-staff] can be obtained from the dev Keycloak instance:

curl -X POST http://localhost:8080/realms/ghasi-dev/protocol/openid-connect/token \
  -d "client_id=claims-dev-client" \
  -d "username=billing_staff_dev" \
  -d "password=dev_password" \
  -d "grant_type=password"

EDI Stub Mode

With EDI_SUBMISSION_MODE=stub, the stub adapter:

• Accepts all claim submissions and returns a synthetic clearinghouseRef
• Simulates a 999 acknowledgement (accepted) after 500ms
• Returns a synthetic ERA for manual testing via POST /api/v1/remittances/ingest with a sample 835 payload from test/fixtures/sample_835.edi