Data Flow Strategy

The system utilizes a Store-and-Forward strategy with a distinct Transformation Phase. This ensures that no data is lost even if downstream components (HSM or SMSC) are temporarily unavailable.

Phase 1: Ingestion & Validation

• Input: The Client App sends a high-level business object.

• Authentication: The API Gateway validates the Authorization: Bearer <token> header.

• Schema Validation:

  • msisdn: Must match country code regex (e.g., ^234\d{10}$).

  • transaction-id: Must be unique within a 24-hour rolling window.

• Rate Limiting: Checks Redis to ensure the partner has not exceeded their TPS (Transactions Per Second) quota.

• Buffering: Valid requests are persisted to the Queue. The Client receives an HTTP 200 OK indicating the request is safe, not complete.

Phase 2: Transformation (OTA Loop)

• Consumption: A Background Worker pulls the message.

• HSM Interaction: The Worker acts as a client to the HSM. It constructs an XML request containing the msisdn and the content-id (scenario).

• Cryptographic Generation: The HSM calculates the necessary keys (Ki, OTA keys) and returns a binary string (often hex-encoded) that instructs the SIM card to perform an action (e.g., "Display Menu" or "Send SMS").

Phase 3: Delivery (SMPP Protocol)

• PDU Construction: The Worker constructs an SMPP submit_sm PDU.

  • esm_class: Set to 0x40 (UDHI Indicator) or 0x04 (Binary) depending on carrier requirements.

  • data_coding: 0xF6 (Binary 8-bit data).

  • short_message: The hex-decoded binary payload from the HSM.

• Transmission: The PDU is sent over a persistent TCP connection to the SMSC.

• State: The system captures the message_id returned by the SMSC in the submit_sm_resp for later correlation.

Phase 4: Transformation

• Delivery Receipt (DLR): The SMSC asynchronously pushes a deliver_sm PDU back to the Worker when the handset acknowledges receipt.

• Reconciliation: The Worker extracts the message_id from the DLR, looks up the original transaction in the DB, and updates the status to DELIVERED.

• Callback: The PSM fires a POST request to the Client's registered Webhook URL with the final outcome.