DLR Processor — Service Overview

Status: populated Owner: Platform Engineering Last updated: 2026-04-18 Companion: DOMAIN_MODEL · API_CONTRACTS · EVENT_SCHEMAS

1. Purpose

The DLR Processor is the authoritative handler for inbound delivery receipts (DLRs) within the Ghasi SMS Gateway. It consumes raw DLR events published by operator connectors (primarily smpp-connector), normalises carrier-specific status codes into canonical DlrStatus values, correlates each receipt back to the originating SmsMessage, updates persistent state, and fans the outcome out to downstream consumers (billing pipeline, webhook dispatcher).

The service is event-driven only — it exposes no customer-facing HTTP API, only infrastructure probes.

2. Responsibilities

Responsibility	Description
DLR consumption	Durable NATS JetStream consumer on sms.dlr.inbound
Status normalisation	Maps SMPP stat values → canonical DlrStatus
Message correlation	Resolves operatorMessageId → internal messageId + accountId
Persistence	Writes to dlr.delivery_receipts; idempotent on operatorMessageId
Orchestrator state sync	Updates orch.sms_messages.status and dlr_status columns
Orphan handling	Unknown operatorMessageId → dlr.orphaned_receipts; publishes sms.dlr.unmatched
Billing trigger	Publishes billing.events for each terminal DLR
Webhook trigger	Publishes webhook.dispatch for each correlated receipt
Observability	Exposes Prometheus /metrics; structured JSON logs; OTLP traces

3. Position in the Platform

smpp-connector ──► sms.dlr.inbound ──► dlr-processor ──► orch.sms_messages (PG)
                                              │               dlr.delivery_receipts (PG)
                                              ├──► billing.events ──► billing-service
                                              ├──► webhook.dispatch ──► webhook-dispatcher
                                              └──► sms.dlr.unmatched ──► reconciliation-job

4. Technology Stack

Concern	Technology
Runtime	Node.js 20 LTS
Framework	NestJS 10
Language	TypeScript 5
Message broker	NATS JetStream
Database	PostgreSQL 15 (schemas: dlr, orch read/write)
Migrations	Flyway
Containerisation	Docker / Kubernetes
Observability	Pino (logs), OpenTelemetry (traces), Prometheus (metrics)

5. Non-Goals

• Does not accept inbound HTTP traffic from external callers.
• Does not own operator SMPP sessions (delegated to smpp-connector).
• Does not compute billing charges (delegated to billing-service).
• Does not deliver webhooks (delegated to webhook-dispatcher).

6. SLOs

Metric	Target
DLR processing latency (p99)	< 500 ms end-to-end
DLR processing latency (p50)	< 100 ms
Correlation success rate	≥ 99.5%
Orphan rate	< 0.5% of inbound DLRs
Error rate	< 0.1% unhandled failures