DLR Processor — Local Dev Setup

Status: populated Owner: Platform Engineering Last updated: 2026-04-18 Companion: DEPLOYMENT_TOPOLOGY

1. Prerequisites

Tool	Minimum Version
Node.js	20 LTS
pnpm	8.x
Docker + Docker Compose	24.x
NATS CLI (nats)	0.1.x
Flyway CLI	10.x

2. Local Stack (Docker Compose)

# docker-compose.dev.yml (excerpt)
services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: ghasi
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: dev_password
    ports: ["5432:5432"]

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

  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    ports: ["4318:4318"]

Start: docker compose -f docker-compose.dev.yml up -d

3. Database Setup

# Apply migrations
flyway -url=jdbc:postgresql://localhost:5432/ghasi \
       -user=postgres -password=dev_password \
       -locations=filesystem:./migrations \
       migrate

# Seed test data (optional)
psql postgresql://postgres:dev_password@localhost:5432/ghasi \
     -f ./scripts/seed-dev.sql

4. NATS Stream Setup

# Create SMS_DLR stream
nats stream add SMS_DLR \
  --subjects="sms.dlr.inbound" \
  --retention=limits \
  --max-age=24h \
  --server=nats://localhost:4222

# Create durable consumer
nats consumer add SMS_DLR dlr-processor \
  --ack=explicit \
  --deliver=all \
  --max-pending=10 \
  --server=nats://localhost:4222

5. Environment Variables

Create .env.local:

NATS_URL=nats://localhost:4222
NATS_STREAM_DLR=SMS_DLR
DATABASE_URL=postgresql://postgres:dev_password@localhost:5432/ghasi
DB_POOL_MIN=2
DB_POOL_MAX=10
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
LOG_LEVEL=debug
PORT=3000

6. Run the Service

pnpm install
pnpm build
pnpm start:dev  # ts-node with watch mode

7. Send a Test DLR

nats pub sms.dlr.inbound '{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "schemaVersion": "1.0",
  "operatorMessageId": "TEST-OP-MSG-001",
  "operatorId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "stat": "DELIVRD",
  "deliveredAt": "2026-04-18T10:00:00Z"
}' --server=nats://localhost:4222

Then verify:

psql postgresql://postgres:dev_password@localhost:5432/ghasi \
  -c "SELECT * FROM dlr.delivery_receipts ORDER BY created_at DESC LIMIT 5;"

8. Run Tests

pnpm test           # unit tests
pnpm test:int       # integration tests (requires Docker)
pnpm test:cov       # coverage report