Message Push System: Defining Architecture, Core Modules, and Design Implementation

A messaging push system serves as the foundational infrastructure enabling servers to proactively deliver notifications

A messaging push system serves as the foundational infrastructure enabling servers to proactively deliver notifications to clients. By eliminating the need for clients to continuously poll for updates, it powers real-time notifications, instant messaging, business alerts, marketing campaigns, and IoT command dispatches.

The core objectives of a robust push system include:

  • Real-time Performance: Messages reach online clients within seconds or even milliseconds.
  • Reliability: Ensuring messages are neither lost nor duplicated (or gracefully handled via idempotency), with critical messages remaining traceable.
  • Low Power Consumption: Mobile clients should rely on system-level persistent connections to minimize background battery drain.
  • Scalability: Supporting millions to hundreds of millions of concurrent connections, multi-region deployments, multi-device syncing, and broadcast scenarios.
  • Operational Capabilities: Supporting frequency controls, "Do Not Disturb" modes, templates, statistics, delivery receipts, and grayscale releases.
    A typical push system adopts a layered architecture:
Business Services -> Push APIs -> Message Queue -> Push Processing Service -> Channel Adaptation Layer -> Clients
                                        |                   |
                                 Offline Storage     Online State / Routing Table

The primary tiers consist of:

  • Access Tier: Exposes HTTP/gRPC push APIs, handling authentication, rate limiting, and parameter validation.
  • Logic Tier: Manages message orchestration, template rendering, deduplication, frequency control, and routing decisions.
  • Routing Tier: Maintains mapping relationships among users, devices, active connections, and gateways.
  • Storage Tier: Persists offline messages, device tokens, conversation sessions, delivery receipts, and unread counts.
  • Channel Tier: Integrates self-hosted persistent connections with third-party channels such as APNs, FCM, and major domestic vendor push services.
  • Monitoring Tier: Collects metrics including connection counts, QPS, latency, success rates, queue backlogs, and error logs.

Core Modules

Connection Access Gateway

The gateway maintains persistent connections with clients using protocols such as WebSocket, MQTT, custom TCP protocols, or Server-Sent Events (SSE). Key responsibilities include:

  • Token authentication during connection establishment.
  • Heartbeat keep-alives, timeout disconnections, and anomaly detection.
  • Binding connections with user IDs, devices, and sessions.
  • Message dispatching, ACK collection, and post-reconnection state recovery.

Gateways are typically deployed statelessly, with connection metadata tracked via a registry center or Redis to facilitate horizontal scaling.

Online State and Routing

Online states determine whether a user is currently reachable via a persistent connection. A common approach is storing routing metadata in Redis:

uid -> { gateway_id, conn_id, device_id, expire_at }

When pushing a message, the system queries the routing table first. If the user is online, the message is dispatched to the corresponding gateway; if offline, it is written to offline storage or routed to a vendor channel. Routing entries require a TTL and are periodically renewed through heartbeats to prevent dead connections from causing misrouting.

Push Service and Message Queue

Upon receiving business requests, the push service generates a globally unique msg_id and publishes the payload into a message queue like Kafka, Pulsar, or RabbitMQ. The message queue provides traffic smoothing, decoupling, and asynchronous retries. For chat-based messaging, partitioning by session_id ensures strict ordering within the same conversation.

Offline Storage and Channel Adaptation

Offline messages are typically written to inbox tables or message logs, allowing clients to pull missed content via cursors upon reconnecting. The vendor channel adaptation layer uniformly wraps APNs, FCM, and domestic vendor SDKs, handling token expirations, delivery receipts, retries, and notification collapsing. For marketing campaigns, systems must support collapse_key parameters to prevent users from receiving redundant alerts.

Observability

Critical monitoring metrics include active connection counts, push QPS, P99 latency, delivery success rates, ACK latency, offline queue backlogs, vendor channel failure rates, and retry frequencies. Logs should consistently incorporate msg_id, uid, device_id, and trace_id to streamline end-to-end troubleshooting.

Key Design Considerations for Implementation

  1. Protocol Selection: Prioritize vendor push channels for mobile devices; use WebSocket or SSE for web clients; leverage gRPC for internal service-to-service communication.
  2. Heartbeats and Reconnection: Set heartbeat intervals between 30 to 60 seconds, utilizing exponential backoff with jitter on the client side for reconnections.
  3. Message Model: Must incorporate fields such as msg_id, target, payload, ttl, priority, seq, and collapse_key.
  4. Reliability: Implement "at-least-once delivery combined with client-side idempotent deduplication." Critical messages require explicit ACKs, retries, and dead-letter queues.
  5. Ordering: Order messages sequentially within the same session using an incrementing seq number, allowing clients to render them correctly and drop duplicates.
  6. Multi-Device Synchronization: Route messages at the device granularity, broadcasting state updates (such as "read" or "deleted" flags) to other active endpoints.
  7. Rate Limiting and Degradation: Implement throttling at user, device, and application levels; gracefully degrade to vendor channels or pull-mode when persistent connections fail.

Example: A Targeted Push Workflow

  1. A business service invokes the push API with the following payload structure:
{
  "target": "user_1001",
  "title": "Order Update",
  "body": "Your order has been shipped",
  "msg_id": "msg_20250101_001",
  "ttl": 3600,
  "priority": "high"
}
  1. The push service validates authentication, checks rate limits and templates, and generates the final message.
  2. The system queries the online status and device routing for user_1001.
  3. If online, the message is delivered to the target gateway, which pushes it over the persistent connection and awaits an ACK.
  4. If offline, the message is written to the offline storage table, and APNs or vendor channels are invoked based on the device type.
  5. Upon receiving a client ACK or vendor delivery receipt, the message status is updated; failures trigger retry policies.

Conclusion

The design of a messaging push system hinges on connection management, routing decisions, message reliability, and channel adaptation. During implementation, prioritize building observable, retryable, and degradable core pipelines before expanding into frequency controls, multi-device synchronization, and advanced operational features. Through a layered architecture and asynchronous queuing, systems can achieve both high real-time performance and robust stability under high-concurrency workloads.