Operator Management Service — Domain Model

Status: populated Owner: Platform Engineering Last updated: 2026-04-18 Companion: SERVICE_OVERVIEW · DATA_MODEL · EVENT_SCHEMAS

1. Aggregates

Operator (root)

Represents a carrier SMPP connection endpoint with its full configuration.

Field	Type	Notes
operatorId	OperatorId (UUIDv4 branded)	Aggregate identity
name	OperatorName (VO)	Human-readable label, unique
host	Hostname (VO)	SMPP server hostname/IP
port	Port (VO)	SMPP port (1–65535)
systemId	SystemId (VO)	SMPP bind system_id
systemType	string	SMPP system_type (optional)
bindType	BindType enum	TRANSCEIVER, TRANSMITTER, RECEIVER
tpsLimit	TpsLimit (VO)	Max transactions/second
burstWindow	BurstWindow (VO)	Sliding window in ms
status	OperatorStatus enum	ACTIVE, INACTIVE, SUSPENDED
healthState	HealthState enum	HEALTHY, DEGRADED, UNHEALTHY, UNKNOWN
deletedAt	Instant | null	Soft-delete timestamp
createdBy	AdminId	Who created
updatedBy	AdminId	Who last updated

Note: SMPP password is not a field on this aggregate. It lives exclusively in Vault.

RoutingRule (root)

Maps a destination prefix to an operator with priority and cost.

Field	Type	Notes
ruleId	RuleId (UUIDv4)	—
prefix	DestinationPrefix (VO)	E.164 prefix
mcc / mnc	string	Optional PLMN codes
operatorId	OperatorId	FK to Operator
priority	number	Lower = higher priority
weight	number	Load-balance weight
costPerSegment	Money (VO)	Wholesale cost
active	boolean	—

2. Value Objects

VO	Invariant
OperatorName	1–128 chars, unique
Hostname	Valid hostname or IPv4; no scheme prefix
Port	Integer 1–65535
SystemId	1–16 chars
DestinationPrefix	Matches ^\+[0-9]{1,15}$
Money	Non-negative decimal(18,6); ISO 4217 currency

3. State Machines

Operator status

INACTIVE → ACTIVE
ACTIVE   → SUSPENDED
ACTIVE   → INACTIVE
SUSPENDED → ACTIVE
ANY      → soft-deleted (deleted_at set)

Operator health state

UNKNOWN  → HEALTHY      (first successful bind)
HEALTHY  → DEGRADED     (error rate > 5% for 60 s)
DEGRADED → UNHEALTHY    (error rate > 20% for 60 s or bind lost)
UNHEALTHY → HEALTHY     (bind restored, error rate < 1% for 30 s)
DEGRADED → HEALTHY      (error rate < 1% for 30 s)

4. Domain Events

See EVENT_SCHEMAS for full schemas.

Event	Trigger
operator.config.created.v1	New operator created
operator.config.updated.v1	Operator fields or rules changed
operator.config.deleted.v1	Soft-delete
operator.health.v1	Health state transition

5. Domain Services

Service	Purpose
OperatorCredentialsService	Read/write SMPP credentials in Vault exclusively
DuplicateOperatorGuard	Enforces unique (host, port, systemId) before INSERT
HealthStateReducer	Reduces smpp-connector health event to authoritative health state
RoutingRuleConflictChecker	Detects prefix overlap before rule INSERT

6. Domain Errors

Error	Cause	HTTP
DuplicateOperatorError	Same (host, port, systemId) exists	409
OperatorNotFoundError	Unknown or soft-deleted	404
VaultWriteError	Vault unavailable	503
PrefixConflictError	Prefix overlaps existing active rule	409
TpsLimitInvalidError	maxTps < 1 or burstMultiplier < 1.0	400