Skip to main content

Billing Service — Local Dev Setup

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

1. docker-compose​

docker compose -f docker-compose.dev.yml up -d postgres redis nats

Relevant services:

  • postgres:16 with billing schema auto-created
  • redis:7-alpine
  • nats:2.10-alpine JetStream enabled (stream BILLING_EVENTS auto-created by seed)

For REST API testing: also start kong to get proper JWT injection.

2. Environment​

Copy .env.example → .env:

PORT=3020
DATABASE_URL=postgresql://billing:billing@localhost:5432/ghasi_sms?schema=billing
REDIS_URL=redis://localhost:6379/2
NATS_URL=nats://localhost:4222
S3_ENDPOINT=http://localhost:9000
S3_BUCKET=ghasi-invoices
S3_ACCESS_KEY=minio
S3_SECRET_KEY=minio123
PRICING_CACHE_TTL_SECONDS=60
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
LOG_LEVEL=debug

Local S3: start MinIO via docker compose up -d minio.

3. Install + migrate​

pnpm install
pnpm --filter @ghasi/service-billing prisma migrate dev
pnpm --filter @ghasi/service-billing prisma db seed
pnpm --filter @ghasi/service-billing dev

4. Smoke test — Event ingestion​

Publish a test billing event to NATS (requires NATS CLI):

nats pub billing.events '{
  "schemaVersion":"1",
  "messageId":"018e7c3a-0000-0000-0000-000000000001",
  "tenantId":"550e8400-e29b-41d4-a716-446655440000",
  "accountId":"660e8400-e29b-41d4-a716-446655440001",
  "accountTier":"GROWTH",
  "operatorId":"op-uk-001",
  "direction":"MT",
  "segmentCount":1,
  "currency":"USD",
  "chargedAt":"2026-04-18T09:00:00.000Z",
  "dlrStatus":"DELIVERED"
}'

Check PG: SELECT * FROM billing.billing_events LIMIT 1;

5. Smoke test — Invoice API​

curl -H "Authorization: Bearer $(./scripts/dev/mint-jwt.sh billing:read)" \
  http://localhost:8000/v1/billing/usage?from=2026-04-01&to=2026-04-18

6. Seed data​

prisma/seed.ts creates:

  • 1 tenant, 1 account (accountTier=GROWTH)
  • Pricing rule: GROWTH × op-uk-001 × MT → PER_SEGMENT $0.02
  • Operator cost: op-uk-001 × MT → $0.01/segment
  • 50 sample billing_events and pre-populated usage_summaries
  • NATS stream BILLING_EVENTS with durable consumer billing-consumer

7. Common commands​

pnpm lint
pnpm typecheck
pnpm test            # unit
pnpm test:int        # testcontainers
pnpm test:e2e        # requires Kong + MinIO up
pnpm prisma studio
# Manual invoice generation:
pnpm --filter @ghasi/service-billing cmd:generate-invoices