Communication Service — Deployment Topology
Status: populated Owner: TBD Last updated: 2026-04-17 Companion: Service Template · 17 Tech Stack
1. Runtime
- Language / runtime: TypeScript 5.x on Node 22 LTS
- Framework: NestJS 11
- Container: distroless Node image, non-root user
- Process types:
api(HTTP),worker-dispatch(notification dispatch),worker-dlr(DLR ingestion),outbox-relay(NATS publisher)
2. Replicas & scaling
| Process | Baseline | Min | Max | HPA signal |
|---|---|---|---|---|
| api | 3 | 2 | 30 | CPU + RPS |
| worker-dispatch | 2 | 1 | 20 | queue depth |
| worker-dlr | 2 | 1 | 10 | callback RPS |
| outbox-relay | 2 | 2 | 2 | (fixed leader-election) |
3. Dependencies
| Dependency | Purpose |
|---|---|
| PostgreSQL 16 | communication schema |
| NATS JetStream | streams COMMUNICATION, ENGAGE_MESSAGING (legacy) |
| Redis 7 | idempotency cache, rate limits |
| Object storage (S3/MinIO) | attachments, recording blobs |
| KMS | join-token signing, column encryption, DLR HMAC |
| Jitsi Meet | virtual room provider |
| Ghasi-SMS-Gateway | SMS in-country |
| FCM / APNs / WebPush | push |
| SES / SendGrid | |
| Kong | edge gateway |
| identity-service | JWKS |
| interop-service | FHIR Communication writes |
| config-service | templates, channel policies |
| ai-gateway-service | optional AI features |
4. Regions
- Primary: co-located with tenant's primary region
- SMS carrier path: Afghanistan tenants use Ghasi-SMS-Gateway (in-country); other tenants per policy
- Push / email: regional endpoints preferred
- DR: async replica in secondary region; RPO ≤ 15 min, RTO ≤ 60 min
5. Config (env)
| Var | Default | Purpose |
|---|---|---|
DATABASE_URL | required | Postgres |
NATS_URL | required | JetStream |
REDIS_URL | required | Cache |
KMS_KEY_ARN | required | Signing |
KEYCLOAK_JWKS_URL | required | JWT validation |
OBJECT_STORE_URL | required | S3 endpoint |
OBJECT_STORE_BUCKET | required | comms-<tenant-bucket-suffix> |
SMS_DEFAULT_PROVIDER | ghasi-sms-gateway | ghasi-sms-gateway | twilio | vonage |
GHASI_SMS_GATEWAY_URL | required | Base URL |
GHASI_SMS_GATEWAY_API_KEY | required | KMS-sealed |
EMAIL_DEFAULT_PROVIDER | ses | |
PUSH_FCM_KEY_REF | required | KMS ref |
JITSI_BASE_URL | required | Virtual care provider |
JITSI_APP_SECRET | required | Token signing |
OTEL_EXPORTER_OTLP_ENDPOINT | required | Telemetry |
6. Health checks
/healthz— process up/readyz— DB + NATS + Redis + adapter self-check- Per-adapter probe surfaces in
/v1/communication/notifications/health
7. Canary & rollout
- 5% traffic for 30 min with SLO gates (send latency, dispatch success).
- Automatic rollback on
failed/dispatched > 0.2sustained 5 min.