smpp-connector — Domain Model

Status: populated | Last updated: 2026-04-18

1. Aggregates & Entities

1.1 SmppSession (Aggregate Root)

Represents a single persistent SMPP 3.4 TCP connection to one MNO operator.

Attribute	Type	Description
operatorId	uuid	Links to operator in operator-management-service
bindMode	BindMode	TRANSCEIVER / TRANSMITTER / RECEIVER
state	SessionState	DISCONNECTED / CONNECTING / BOUND / UNBOUND / FAILBACK
host	string	MNO SMPP server hostname
port	number	MNO SMPP server port
systemId	string	SMPP bind credential (username)
tpsLimit	number	Operator-assigned TPS cap
isPrimary	boolean	True = primary operator; False = backup
reconnectAttempts	number	Count of consecutive failed reconnect attempts
nextReconnectAt	Date	Scheduled next reconnect attempt
lastBoundAt	Date | null	Timestamp of last successful bind
lastUnboundAt	Date | null	Timestamp of last unbind

1.2 MessageCorrelation (Entity)

Maps the MNO-assigned message_id (from submit_sm_resp) back to the internal messageId used by sms-orchestrator and dlr-processor.

Attribute	Type	Description
id	uuid	Internal primary key
messageId	uuid	Internal message ID from sms-orchestrator
operatorMessageId	varchar(64)	MNO-assigned ID from submit_sm_resp
operatorId	uuid	Which operator was used
to	varchar(20)	Destination E.164 (masked in logs)
submittedAt	timestamp	When submit_sm was sent
expiresAt	timestamp	TTL for DLR correlation (default: 72 h)

1.3 DispatchCommand (Value Object — from NATS)

The inbound instruction to transmit an SMS, consumed from smpp.operator.{operatorId}.

Field	Type	Description
messageId	uuid	Internal message identifier
to	string	Destination E.164 number
from	string	Source address (sender ID)
text	string	Message text (UTF-8)
encoding	SmsEncoding	GSM7 / UCS2
operatorId	uuid	Target operator (resolved by routing-engine)
accountId	uuid	Account sending the message
messageType	MessageType	SMS / FLASH
longMessageStrategy	LongMessageStrategy	CSMS / TLV

---

2. Value Objects

Value Object	Fields	Description
SubmitSmPdu	serviceType, sourceAddr, destAddr, dataEncoding, shortMessage, messageParts[]	Immutable representation of a PDU to be sent
DeliverSmPdu	messageId, sourceAddr, destAddr, shortMessage, receiptedMessageId, messageState	Received DLR PDU from MNO
TpsWindow	operatorId, windowStart, count	Sliding-window TPS state (Redis-backed)

---

3. Enumerations

enum SessionState {
  DISCONNECTED = 'DISCONNECTED',
  CONNECTING   = 'CONNECTING',
  BOUND        = 'BOUND',
  UNBINDING    = 'UNBINDING',
  UNBOUND      = 'UNBOUND',
  FAILBACK     = 'FAILBACK',
}

enum BindMode {
  TRANSCEIVER = 'TRANSCEIVER',  // bind_transceiver (preferred)
  TRANSMITTER = 'TRANSMITTER',  // bind_transmitter (TX-only fallback)
  RECEIVER    = 'RECEIVER',     // bind_receiver (RX-only, used with TRANSMITTER pair)
}

enum SmsEncoding {
  GSM7 = 0x00,  // GSM 7-bit default alphabet
  UCS2 = 0x08,  // Unicode (UCS-2)
}

enum LongMessageStrategy {
  CSMS = 'CSMS',  // Concatenated SMS headers (SAR UDH)
  TLV  = 'TLV',   // message_payload optional parameter
}

enum DlrMessageState {
  ENROUTE    = 'ENROUTE',
  DELIVERED  = 'DELIVERED',
  EXPIRED    = 'EXPIRED',
  DELETED    = 'DELETED',
  UNDELIVERABLE = 'UNDELIVERABLE',
  ACCEPTED   = 'ACCEPTED',
  UNKNOWN    = 'UNKNOWN',
  REJECTED   = 'REJECTED',
}

---

4. Session State Machine

DISCONNECTED
     │
     │ connect()
     ▼
CONNECTING ──── TCP error / timeout ──────────────────────┐
     │                                                     │
     │ TCP connected → send bind_transceiver               │
     ▼                                                     │
[awaiting bind_resp]                                       │
     │                                                     ▼
     │ bind_resp OK          bind_resp error      DISCONNECTED
     ▼                                (increment reconnectAttempts,
   BOUND ◄───── FAILBACK               schedule backoff)
     │               ▲
     │ enquire_link   │ MNO reconnects
     │ timeout / TCP  │ successfully
     │ disconnect     │
     ▼               │
  UNBOUND ───────────┘
     │
     │ schedule reconnect (exponential backoff)
     └──► CONNECTING

---

5. Reconnection Backoff Schedule

Attempt	Delay
1	5 s
2	10 s
3	20 s
4	40 s
5+	60 s (capped)

On successful bind, reconnectAttempts is reset to 0 and state transitions to BOUND.