Architecture

SMS Gateway Proxy System — Architecture Documentation

Overview

This document describes the architecture of an SMS Gateway Proxy System designed to process, control, and route SMS traffic through SMPP v3.4 connections to telecom operators.

The system acts as a messaging middleware layer between external client systems and telecom SMS infrastructure.
It provides routing, delivery tracking, contact policy enforcement, rate limiting, journaling, and observability.

The architecture separates traffic processing, policy control, and state persistence, allowing the system to scale horizontally while maintaining strict operational control over message flow.

Architecture Overview

The system consists of four logical layers:

1. Client Layer — external systems that generate SMS traffic
2. Application Layer — core services running in Docker
3. Storage Layer — persistent storage and log export
4. Telecom Layer — external SMSC infrastructure

Logical Flow

Client systems send SMS messages to the SMPP Proxy, which acts as the main messaging gateway.
Before messages are transmitted to telecom operators, they pass through the Message Control Platform (MCP) for contact policy validation and filtering.

Traffic is controlled by a distributed L2 rate limiter implemented in Redis to protect telecom links from overload.
Message lifecycle states are stored in Aerospike, while journals and operational logs are exported to S3 object storage.

System Components

1. Client Layer

External systems interact with the gateway by submitting SMS messages.

Client Types

• Client scripts — automation tools or internal integrations
• Agents — automated messaging services
• SaaS platforms — business applications generating high-volume SMS traffic

All client traffic is directed to the SMPP Proxy, which acts as the single entry point to the messaging infrastructure.

Application Layer

All application services run inside Docker containers on the main server.

The application layer contains the core services responsible for message routing, traffic control, and policy enforcement.

2. SMPP Proxy (Core Gateway)

The SMPP Proxy is the central component responsible for message transmission and lifecycle management.

It serves as the data plane of the system, responsible for handling high-throughput messaging traffic.

Responsibilities

• Accept SMS requests from client applications
• Route messages to telecom operators through SMPP connections
• Maintain multiple SMPP sessions (ESME connections)
• Process delivery receipts (DLR)
• Track message lifecycle states
• Integrate with rate limiting and policy control systems
• Record message activity for statistics and journaling

Internal Capabilities

• SMPP v3.4 protocol support
• Multiple ESME client connections
• Automatic message segmentation for long SMS
• Support for payload mode (TLV transmission)
• Encoding support (GSM 7-bit, Latin-1, UCS-2)
• Transaction correlation via UUID
• Delivery receipt processing

The SMPP Proxy is optimized for high concurrency and high message throughput.

3. MCP — Message Control Platform

The Message Control Platform (MCP) is responsible for contact policy enforcement and message filtering.

This component evaluates messages before they are allowed to be transmitted through the SMPP Proxy.

MCP acts as the control plane of the messaging infrastructure.

Responsibilities

• Contact policy validation
• Blacklist checks
• Registration verification
• Message filtering rules
• Business rule enforcement
• Authorization of message submission

Policy Execution Pipeline

Each message passes through a policy pipeline before transmission.

Example validation pipeline:

1. Contact registration verification
2. Blacklist validation
3. Business rule filtering
4. Message authorization

Only messages that pass all policy checks are allowed to proceed to the transmission stage.

4. Redis — Distributed L2 Rate Limiter

Redis is used to implement a distributed Layer-2 rate limiting system.

This Redis instance is dedicated to the rate limiting subsystem of the SMPP Proxy.

Purpose

The L2 limiter protects the messaging infrastructure and telecom links from traffic overload.

It ensures that rate limits are enforced consistently across multiple proxy instances.

Responsibilities

• Global rate limiting across proxy instances
• Distributed token bucket storage
• Request counters and burst control
• Fair traffic distribution across the cluster
• Protection of telecom SMPP links

Rate Limiting Model

Traffic control occurs in two stages:

L1 — Local Rate Limiter

Local limiter inside the proxy instance controlling immediate request throughput.

L2 — Distributed Rate Limiter

Cluster-wide limiter implemented using Redis.

Flow:

Client → L1 limiter → L2 Redis limiter → SMPP Proxy → SMSC

This architecture allows cluster-wide throughput enforcement.

5. Aerospike — Message State Storage

Aerospike is used as the persistent datastore for message lifecycle tracking.

It stores message state transitions and operational statistics.

Responsibilities

• Store message submission records
• Track message lifecycle states
• Persist delivery receipt updates
• Maintain operational statistics

Stored Data Examples

• Message ID
• Transaction ID
• Submission timestamp
• Destination address
• Routing information
• Delivery status
• Failure reason

Aerospike is chosen because it supports very high write throughput with low latency.

Storage Layer

6. S3 Object Storage

Operational logs and message journals are exported to S3-compatible object storage.

Storage Buckets

Exported Data

The system periodically exports:

• message journals
• operational logs
• statistics snapshots
• monitoring artifacts

This enables long-term archival and external analytics.

Telecom Layer

7. SMSC (Short Message Service Center)

The SMSC is the telecom operator infrastructure responsible for delivering SMS messages to mobile subscribers.

The SMPP Proxy maintains persistent SMPP client connections to SMSC systems.

SMSC Responsibilities

• Accept submit_sm messages
• Route SMS messages through telecom networks
• Return submission acknowledgments (submit_sm_resp)
• Send delivery receipts (deliver_sm)

The SMSC represents the final stage of the SMS delivery pipeline.

Message Flow

SMS Submission Flow

1. Client submits an SMS message to the gateway.
2. The request reaches the SMPP Proxy.
3. The message is forwarded to MCP for contact policy validation.
4. MCP executes the policy pipeline.
5. If approved, the request proceeds to rate limiting.
6. The Redis L2 limiter validates cluster-wide throughput limits.
7. Message state is stored in Aerospike.
8. The SMPP Proxy sends the message to the SMSC via submit_sm.
9. SMSC returns submit_sm_resp.
10. Later, the SMSC sends a delivery receipt using deliver_sm.
11. Delivery status is stored and exported to logs.

Data Flow Summary

Deployment Model

The system is designed for containerized deployment using Docker.

Runtime Environment

This architecture allows horizontal scaling and operational flexibility.

Architecture Characteristics

High Throughput Messaging

The system is optimized for processing very large volumes of SMS traffic with minimal latency.

Policy-Driven Messaging Control

All messages are validated through the Message Control Platform before transmission.

This ensures compliance with business rules and regulatory policies.

Distributed Traffic Control

The L2 Redis rate limiter provides cluster-wide traffic control and protects telecom infrastructure.

Reliable Message Tracking

Message lifecycle states are persisted in Aerospike and exported for monitoring and analytics.

Observability and Logging

Operational data is exported to S3 storage, enabling auditing, monitoring, and offline analysis.

Architecture Summary

The SMS Gateway Proxy architecture provides a scalable and reliable messaging infrastructure with:

• SMPP v3.4 telecom integration
• policy-based message filtering via MCP
• distributed rate limiting using Redis
• high-performance state storage with Aerospike
• delivery tracking via DLR
• containerized deployment
• external journaling and log export

The system acts as a high-throughput messaging backbone, connecting business applications with telecom infrastructure while enforcing strict message policies and traffic limits.