Orders Service — Local Dev Setup

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

1. Prerequisites

Tool	Version	Notes
Node.js	22 LTS	`nvm use 22`
pnpm	9.x	`npm i -g pnpm`
Docker Desktop	4.x	Required for dependencies
Docker Compose	2.x	Included in Docker Desktop
Keycloak CLI (`kcadm`)	Optional	For realm setup debugging

2. Repository Layout

services/orders-service/
├── src/
│   ├── domain/
│   ├── application/
│   ├── infrastructure/
│   └── presentation/
├── test/
│   ├── unit/
│   ├── integration/
│   │   ├── tenant-isolation.spec.ts   ← mandatory
│   │   ├── outbox.spec.ts             ← mandatory
│   │   └── cds-guard.integration.spec.ts
│   └── contract/
├── .env.example
├── docker-compose.dev.yml
└── drizzle.config.ts

3. Docker Compose Dev Stack

docker-compose.dev.yml brings up all service dependencies:

# docker-compose.dev.yml (abbreviated)
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: ghasi_ehealth_dev
      POSTGRES_USER: orders_dev
      POSTGRES_PASSWORD: dev_secret
    ports:
      - "5432:5432"
    volumes:
      - postgres_orders_data:/var/lib/postgresql/data

  nats:
    image: nats:2.10-alpine
    command: ["-js", "-sd", "/data"]
    ports:
      - "4222:4222"
      - "8222:8222"  # monitoring
    volumes:
      - nats_orders_data:/data

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

  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    command: start-dev --import-realm
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    ports:
      - "8080:8080"
    volumes:
      - ./dev/keycloak/realm-export.json:/opt/keycloak/data/import/realm-export.json

  # Mock CDS engine — returns pre-defined responses for dev
  cds-mock:
    image: mockserver/mockserver:5.15.0
    ports:
      - "1080:1080"
    volumes:
      - ./dev/cds-mock:/config

volumes:
  postgres_orders_data:
  nats_orders_data:

4. First-Time Setup

# 1. Clone and install
cd services/orders-service
pnpm install

# 2. Copy environment template
cp .env.example .env
# Edit .env — see Section 5

# 3. Start dependencies
docker compose -f docker-compose.dev.yml up -d

# 4. Wait for Postgres to be ready (~5s), then run migrations
pnpm db:migrate

# 5. Seed development data
pnpm db:seed

# 6. Start the service in watch mode
pnpm dev

Service available at http://localhost:3010.

5. Environment Variables (.env.example)

# Database
DATABASE_URL=postgres://orders_dev:dev_secret@localhost:5432/ghasi_ehealth_dev

# NATS
NATS_URL=nats://localhost:4222
NATS_STREAM_NAME=CLINICAL_ORDERS

# Redis
REDIS_URL=redis://localhost:6379

# Keycloak
KEYCLOAK_REALM_URL=http://localhost:8080/realms/ghasi-dev
KEYCLOAK_CLIENT_ID=orders-service
KEYCLOAK_CLIENT_SECRET=dev-secret-change-me

# Service URLs (local mocks / real dev services)
CDS_SERVICE_URL=http://localhost:1080/cds
TERMINOLOGY_SERVICE_URL=http://localhost:3020
REGISTRATION_SERVICE_URL=http://localhost:3002
MEDICATION_SERVICE_URL=http://localhost:3014

# Feature flags
ORDERS_TENANT_ISOLATE=true
CDS_ENABLED=true
CDS_DEGRADED_BLOCKS_MEDICATION=true

# Telemetry (local Grafana stack)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_SERVICE_NAME=orders-service

6. Common Development Commands

# Start in watch mode (ts-node-dev / nodemon)
pnpm dev

# Build production bundle
pnpm build

# Run all unit tests
pnpm test

# Run unit tests in watch mode
pnpm test:watch

# Run integration tests (requires Docker deps running)
pnpm test:integration

# Run contract tests
pnpm test:contract

# Run all tests with coverage
pnpm test:cov

# Database migrations
pnpm db:migrate          # apply pending migrations
pnpm db:migrate:rollback # rollback last migration
pnpm db:seed             # seed dev data (patients, encounters, order sets)

# Lint + format
pnpm lint
pnpm format

# Typecheck
pnpm typecheck

# k6 performance tests (requires k6 installed)
k6 run test/performance/order-create.k6.js

7. Seed Data

Running pnpm db:seed creates:

Seed item	Count	Notes
Tenants	2	`tenant_dev_01` (AFG Ministry), `tenant_dev_02` (test hospital)
Patients	10 per tenant	Includes 1 patient with known penicillin allergy
Encounters	5 per patient	Active encounters for order creation
Order sets	3	"AMI protocol", "Routine pre-op bloods", "Discharge meds"
Orders	20 per tenant	Mix of medication, lab, radiology, and referral orders

8. CDS Mock Configuration

Development uses MockServer (cds-mock) to simulate CDS engine responses. Configuration in dev/cds-mock/:

dev/cds-mock/
├── allergy-hard-stop.json   # Returns hard-stop for penicillin + patient ALLERGY_TEST_PT
├── ddi-warning.json         # Returns warning for metformin + warfarin combo
├── duplicate-warning.json   # Returns warning for repeat amoxicillin
└── default-pass.json        # Returns empty alerts for all other combinations

9. Running Against Real Dev Services

If you want to test against real downstream services (not mocks), set the corresponding *_SERVICE_URL env vars to point to the dev cluster. Ensure you are connected to the dev VPN.

10. FHIR Client Testing

The FHIR read surface (/fhir/R4/ServiceRequest, /fhir/R4/MedicationRequest) is served by interop-service, which must also be running locally. Use the provided Postman collection in docs/postman/orders-fhir.postman_collection.json.

11. Observability (Local)

Spin up the local Grafana/Jaeger stack from the platform-level infra/observability/docker-compose.observability.yml:

cd infra/observability
docker compose up -d
# Grafana: http://localhost:3000 (admin/admin)
# Jaeger: http://localhost:16686
# Prometheus: http://localhost:9090

12. Troubleshooting

Problem	Likely cause	Fix
`ECONNREFUSED` on startup	PostgreSQL not ready	`docker compose ps` — wait for `healthy` status
CDS hard-stop on all medication orders	MockServer not started	`docker compose up cds-mock -d`
JWT validation fails	Keycloak not started or realm not imported	Check `docker compose ps keycloak`; re-import realm
Migrations fail	Wrong DB user or DB does not exist	Check `DATABASE_URL`; run `docker compose exec postgres psql -U postgres -c 'CREATE DATABASE ghasi_ehealth_dev;'`
NATS consumer not receiving events	Stream not created	Run `pnpm nats:setup` to create JetStream streams

1. Prerequisites​

2. Repository Layout​

3. Docker Compose Dev Stack​

4. First-Time Setup​

5. Environment Variables (.env.example)​

6. Common Development Commands​

7. Seed Data​

8. CDS Mock Configuration​

9. Running Against Real Dev Services​

10. FHIR Client Testing​

11. Observability (Local)​

12. Troubleshooting​