Skip to main content

Interop Service — Local Dev Setup

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

1. Prerequisites​

  • Docker Desktop ≥ 4.x, Node 22, pnpm 9
  • All clinical service containers running (interop-service proxies to them)
  • HAPI FHIR validator JAR (for profile validation integration tests)

2. docker-compose recipe​

services:
  interop-db:
    image: postgres:16
    environment:
      POSTGRES_DB: interop
      POSTGRES_USER: interop_user
      POSTGRES_PASSWORD: interop_pass
    ports:
      - "5440:5432"

  interop-service:
    build:
      context: .
      dockerfile: services/interop-service/Dockerfile.dev
    environment:
      DATABASE_URL: postgresql://interop_user:interop_pass@interop-db:5432/interop
      NATS_URL: nats://nats:4222
      KEYCLOAK_JWKS_URI: http://keycloak:8080/realms/ghasi/protocol/openid-connect/certs
      ABAC_SERVICE_URL: http://access-policy-service:3000
      MINIO_ENDPOINT: http://minio:9000
      MINIO_BUCKET_EXPORTS: ghasi-exports
      TERMINOLOGY_SERVICE_URL: http://terminology-service:3000
      MLLP_PORT: 2575
      # Service routing URLs (all local)
      FHIR_ROUTE_PATIENT: http://registration-service:3000
      FHIR_ROUTE_OBSERVATION_LAB: http://laboratory-service:3000
      FHIR_ROUTE_DIAGNOSTIC_LAB: http://laboratory-service:3000
      FHIR_ROUTE_IMAGING_STUDY: http://radiology-service:3000
    ports:
      - "3010:3000"
      - "2575:2575"     # MLLP

3. Initial Setup​

pnpm install
pnpm --filter @ghasi/interop-service drizzle-kit migrate
pnpm --filter @ghasi/interop-service seed:routing-rules  # loads default FHIR routing table
pnpm --filter @ghasi/interop-service dev

4. Test HL7 v2 Inbound​

Send a test ADT^A01 message using an MLLP client:

# Using hl7tools (npm i -g hl7tools)
hl7-mllp-send \
  --host localhost \
  --port 2575 \
  --file test/fixtures/adt-a01-sample.hl7

5. Test FHIR Gateway​

# Get CapabilityStatement
curl http://localhost:3010/fhir/R4/metadata \
  -H "Authorization: Bearer $DEV_TOKEN"

# Search observations (routes to laboratory-service)
curl "http://localhost:3010/fhir/R4/Observation?patient=PAT_01J...&category=laboratory" \
  -H "Authorization: Bearer $DEV_TOKEN"

6. Common Commands​

CommandDescription
pnpm devStart with hot reload
pnpm test:unitUnit tests
pnpm test:integrationIntegration tests
pnpm seed:routing-rulesLoad default FHIR routing rules
pnpm drizzle-kit migrateApply migrations