Copy page

USSD Internals

USSD Request Pipeline Architecture

This document provides a comprehensive analysis of the end-to-end request flow from incoming USSD requests through to the execution of DSL-defined applications on the Tech231 Platform.

Overview

The USSD execution engine follows a stateful session model built on Microsoft Orleans, where each user session is managed by a dedicated grain that maintains navigation history, session data, and execution state.

The platform provides two primary entry points for USSD traffic:

1. Telco Gateway (Tech231.Platform.Ussd.App) - Direct integration with mobile network operators
2. Management API (Tech231.Platform.Ussd.Api) - Provider-agnostic REST API for session management

Code
┌─────────────────────────────────────────────────────────────────────────────────┐
│                           External Traffic Sources                              │
├──────────────────────────────────┬──────────────────────────────────────────────┤
│        Mobile Network Operators  │           Internal Services / Partners       │
│        (Orange, MTN, Airtel)     │           (CRM, Web Apps, Integration)       │
└────────────────┬─────────────────┴────────────────────┬─────────────────────────┘
                 │                                       │
                 ▼                                       ▼
┌────────────────────────────────────┐   ┌────────────────────────────────────────┐
│     Tech231.Platform.Ussd.App      │   │     Tech231.Platform.Ussd.Api          │
│                                    │   │                                        │
│  /gateway/{country}/{network}      │   │  /api/v1/ussd/session (Management)     │
│  - GET/POST (telco callbacks)      │   │  /api/v1/ussd/inbound (Normalized)     │
│  - Rate limited (Redis)            │   │  - JWT Authentication                  │
│  - Telco-specific adapters         │   │  - Multi-tenant isolation              │
└────────────────┬───────────────────┘   └───────────────────┬────────────────────┘
                 │                                           │
                 └─────────────────────┬─────────────────────┘
                                       ▼
              ┌──────────────────────────────────────────────────┐
              │              Orleans Cluster Client              │
              │  - Connection pooling                            │
              │  - Load balancing across silos                   │
              └──────────────────────────┬───────────────────────┘
                                         ▼
┌────────────────────────────────────────────────────────────────────────────────┐
│                        Orleans Grain Layer (Stateful)                          │
├────────────────────────┬─────────────────────────┬─────────────────────────────┤
│ IUSSDSessionGrain      │ IApplicationGrain       │ ITenantUssdApplication...   │
│ - Session state machine│ - DSL deployment        │ - Shortcode routing         │
│ - Input processing     │ - Definition storage    │ - Application directory     │
│ - Navigation history   │ - Validation            │                             │
└────────────────────────┴─────────────────────────┴─────────────────────────────┘
                                         │
                                         ▼
              ┌──────────────────────────────────────────────────┐
              │              DSL Execution Engine                │
              │  - Menu rendering with templates                 │
              │  - Option matching and navigation                │
              │  - Action execution (HTTP, set, validate)        │
              │  - Global actions (Back, Home)                   │
              └──────────────────────────────────────────────────┘

Request Flow Stages

Stage 1: HTTP Ingress

The platform supports two ingress paths with different authentication and binding models:

1a. Telco Gateway Entry Point (Ussd.App)

The Telco Gateway (/gateway/{country}/{network}) is designed for direct integration with mobile network operators. It accepts requests via query parameters, body, or headers for maximum telco compatibility:

Code
GET /gateway/lr/orange?msisdn=231881234567&session=abc123&shortcode=*123%23&input=1

Request Binding Model:

Code
// Flexible binding from multiple sources for telco compatibility
public class GatewayRequestInput : RequestInput
{
    [FromRoute] public string Country { get; set; }
    [FromRoute] public string TelcoNetwork { get; set; }
}

public class RequestInput
{
    [FromQuery(Name = "msisdn"), FromBody, FromHeader(Name = "x-msisdn")]
    public string? Msisdn { get; set; }

    [FromQuery(Name = "session"), FromBody, FromHeader(Name = "x-session-id")]
    public string? DialogId { get; set; }  // Session ID

    [FromQuery(Name = "shortcode"), FromBody]
    public string? ShortCode { get; set; }

    [FromQuery(Name = "input"), FromBody]
    public string? Input { get; set; }
}

Key Features:

• Rate Limiting: Redis-backed request throttling per MSISDN
• Gateway Adapter Resolution: Looks up telco-specific adapter for response formatting
• Tenant Resolution: Extracts tenant ID from gateway adapter metadata

1b. Management API Entry Point (Ussd.Api)

1b. Management API Entry Point (Ussd.Api)

Inbound USSD requests arrive at the normalized /api/v1/ussd/inbound endpoint:

Code
POST /api/v1/ussd/inbound
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "sessionId": "abc123-session-id",
  "msisdn": "231881234567",
  "shortCode": "*231#",
  "provider": "Orange",
  "input": "",
  "isInitiation": true
}

Key Components:

• TenantContextEndpointFilter: Extracts tenant (organization) ID from JWT claims
• MSISDN Validation: Ensures phone number format (10-15 digits)
• Request Type Detection: isInitiation determines session start vs. continuation

Stage 2: Tenant Resolution & Authentication

Gateway Path (Telco Traffic)

For gateway requests, tenant is resolved via the gateway adapter registry:

Code
// Build country-telco identifier
var countryTelcoId = $"{request.Country}-{request.TelcoNetwork}";

// Lookup adapter from registry grain
var registryGrain = clusterClient.GetGrain<IGatewayRegistryGrain>(0);
var adapter = await registryGrain.GetAdapterAsync(countryTelcoId);

// Extract tenant from adapter metadata
var tenantId = adapter.TenantId;
Orleans.Runtime.RequestContext.Set("TenantId", tenantId);

API Path (Internal Traffic)

For API requests, tenant is extracted from JWT claims:

Code
// Extract tenant from JWT claims
var tenantId = user.GetOrgId();

// Validate tenant context
if (string.IsNullOrEmpty(tenantId))
{
    return Results.Json(OutboundResponseDto.WithError(...));
}

The system is multi-tenant by design. Every request must include a valid JWT with an organization ID claim (org_id). This tenant ID is used to:

1. Scope session grains to the tenant
2. Resolve applications from the tenant's application directory
3. Enforce data isolation between tenants

Shortcode Validation

Inbound USSD requests are validated before routing:

1. Format Validation: The shortcode must match *\d{3,4}# (base) or *\d{3,4}*\d{2,4}# (sub-coded)
2. Policy Enforcement: For sub-coded requests, the base shortcode's AllowSubcodes policy is checked

If validation fails, the request returns:

• 400 Bad Request with error code INVALID_SHORTCODE for format issues
• null application resolution for policy violations (no matching app found)

Stage 3: Session Grain Activation

For each unique {tenantId}:{sessionId} combination, an Orleans USSDSessionGrain is activated:

Code
// Build grain key
var sessionGrainKey = UssdGrainKey.ForSession(tenantId, request.SessionId);
// Format: "{tenantId}:{sessionId}"

// Get grain reference (Orleans activates if needed)
var sessionGrain = clusterClient.GetGrain<IUSSDSessionGrain>(sessionGrainKey);

Grain Key Format: {tenantId}:{sessionId} (e.g., org_abc123:session_xyz789)

Stage 4: Application Resolution

For initiation requests, the system resolves which application to execute:

Code
// Priority order for application resolution:
// 1. Explicit ServiceCode in request
// 2. Shortcode lookup via TenantUssdApplicationDirectoryGrain

if (!string.IsNullOrEmpty(request.ServiceCode))
{
    return request.ServiceCode;
}

var directoryGrain = clusterClient.GetGrain<ITenantUssdApplicationDirectoryGrain>(tenantId);
var app = await directoryGrain.GetApplicationByShortCodeAsync(request.ShortCode);

Sub-Code Policy Enforcement

When resolving applications by shortcode:

1. Parse the shortcode using ShortCodePolicy
2. For sub-coded shortcodes (*base*sub#):
   • Check if the base shortcode's owner allows sub-codes
   • If the base is owned by a different tenant with AllowSubcodes=false, resolution fails
3. Look up the application in the tenant's directory

Grain Interactions:

1. TenantUssdApplicationDirectoryGrain: Maps shortcodes to applications for a tenant
2. ShortCodeRegistryGrain: Global shortcode registry (ensures uniqueness across tenants)
3. ApplicationGrain: Stores the parsed DSL application definition

Stage 5: Session Initialization (Initiation Only)

When starting a new session:

Code
var startRequest = new SessionStartRequest(
    ApplicationName: applicationName,
    Msisdn: request.Msisdn,
    ShortCode: request.ShortCode,
    NetworkId: request.Provider,
    InitialInput: request.Input
);

var response = await sessionGrain.StartSessionAsync(startRequest);

Inside USSDSessionGrain.StartSessionAsync():

1. Load Application Definition: Fetches parsed DSL from ApplicationGrain
2. Initialize Session State: Sets MSISDN, shortcode, network ID, session variables
3. Execute Start Action: Runs the configured start action (e.g., Bootstrap.Account)
4. Navigate to First Menu: Displays the initial menu to the user

Stage 6: Input Processing (Continuation)

For subsequent user inputs:

Code
var response = await sessionGrain.ProcessInputAsync(input);

Inside USSDSessionGrain.ProcessInputAsync():

Code
// 1. Check global navigation actions first
if (_state.State.GlobalActions.BackKey == input)
{
    return await HandleBackNavigation();
}
if (_state.State.GlobalActions.HomeKey == input)
{
    return await HandleHomeNavigation();
}

// 2. Match input against current menu options
var matchedOption = currentMenu.Options
    .FirstOrDefault(o => o.Key == input || o.Key == "*");

// 3. Execute option actions (if any)
foreach (var action in matchedOption.Actions)
{
    await _actionExecutor.ExecuteAsync(action, templateContext);
}

// 4. Navigate to target menu
return await NavigateToMenu(targetMenu);

Stage 7: Template Rendering

Menu text is dynamically rendered using a template engine:

Code
menu "Greeting" {
  text = "Welcome {{session.data.name}}! Your balance is {{response.balance}}"
}

Available Template Variables:

• {{session.input}} - Current user input
• {{session.data.*}} - Session-scoped variables
• {{response.*}} - HTTP action response data
• {{env.*}} - Environment variables

Stage 8: Response Generation

The session grain returns a UssdResponse:

Code
public record UssdResponse(
    UssdResponseType ResponseType,  // Continue, End, Error
    string Text,                     // Rendered menu text
    string SessionId,
    string? CurrentMenu,
    UssdError? Error
);

Response Types:

• Continue: Session remains active, user input expected
• End: Terminal menu reached, session closes
• Error: Processing error occurred

Stage 9: HTTP Response

The handler maps the grain response to HTTP:

Code
private static IResult MapToResult(string sessionId, UssdResponse response, string? traceId)
{
    if (response.Error != null)
    {
        return Results.Json(OutboundResponseDto.WithError(...));
    }

    if (response.ResponseType == UssdResponseType.End)
    {
        return Results.Ok(OutboundResponseDto.End(sessionId, response.Text, ...));
    }

    return Results.Ok(OutboundResponseDto.Continue(sessionId, response.Text, ...));
}

Grain Architecture

Code
┌─────────────────────────────────────────────────────────────────┐
│                        Orleans Cluster                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────────┐    ┌─────────────────────────────┐     │
│  │ USSDSessionGrain    │───▶│ ApplicationGrain            │     │
│  │ Key: tenant:session │    │ Key: tenant:appName         │     │
│  │                     │    │                             │     │
│  │ - Session state     │    │ - Parsed DSL definition     │     │
│  │ - Navigation history│    │ - Menus, Actions, Variables │     │
│  │ - Session variables │    │ - Global action config      │     │
│  │ - Template context  │    │                             │     │
│  └─────────────────────┘    └─────────────────────────────┘     │
│            │                                                    │
│            │                                                    │
│            ▼                                                    │
│  ┌─────────────────────────────────────────────┐                │
│  │ TenantUssdApplicationDirectoryGrain         │                │
│  │ Key: tenantId                               │                │
│  │                                             │                │
│  │ - Maps shortcodes to applications           │                │
│  │ - Tenant-scoped application registry        │                │
│  └─────────────────────────────────────────────┘                │
│            │                                                    │
│            ▼                                                    │
│  ┌─────────────────────────────────────────────┐                │
│  │ ShortCodeRegistryGrain                      │                │
│  │ Key: shortcode (e.g., "*231#")              │                │
│  │                                             │                │
│  │ - Global shortcode uniqueness               │                │
│  │ - Cross-tenant shortcode registry           │                │
│  └─────────────────────────────────────────────┘                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Session State Management

Each USSDSessionGrain maintains persistent state:

Code
public class SessionState
{
    public bool IsInitialized { get; set; }
    public SessionStatus Status { get; set; }
    public string? ApplicationName { get; set; }
    public string? Msisdn { get; set; }
    public string? ShortCode { get; set; }
    public string? NetworkId { get; set; }
    public string? CurrentMenu { get; set; }
    public List<string> NavigationHistory { get; set; } = [];
    public Dictionary<string, object> SessionData { get; set; } = [];
    public GlobalActionsConfig GlobalActions { get; set; }
    public DateTimeOffset CreatedAt { get; set; }
    public DateTimeOffset LastActivityAt { get; set; }
}

Navigation Features

Back Navigation (FR-005)

Code
private async Task<UssdResponse> HandleBackNavigation()
{
    if (_state.State.NavigationHistory.Count <= 1)
    {
        // Already at start, stay at current menu
        return await NavigateToMenu(currentMenu);
    }
    
    // Pop current menu, navigate to previous
    _state.State.NavigationHistory.RemoveAt(_state.State.NavigationHistory.Count - 1);
    var previousMenuName = _state.State.NavigationHistory.Last();
    return await NavigateToMenu(GetMenu(previousMenuName));
}

Home Navigation (FR-006)

Code
private async Task<UssdResponse> HandleHomeNavigation()
{
    // Clear history and return to start menu
    _state.State.NavigationHistory.Clear();
    var startMenu = GetMenu(_application.Start);
    return await NavigateToMenu(startMenu);
}

Terminal Menus (FR-003, FR-007)

Code
private async Task<UssdResponse> NavigateToMenu(MenuBlock menu)
{
    // Menu is terminal if: no options OR explicit terminal=true flag
    if (menu.IsTerminal)
    {
        _state.State.Status = SessionStatus.Completed;
        return UssdResponse.End(renderedText, _sessionId, menu.Name);
    }
    return UssdResponse.Continue(renderedText, _sessionId, menu.Name);
}

Observability

Metrics (OpenTelemetry)

• ussd.session.started - Counter for new sessions
• ussd.session.completed - Counter for completed sessions
• ussd.session.error - Counter for session errors
• ussd.input.processed - Counter for input processing

Tracing

Each request includes a trace ID in the response for correlation:

Code
{
  "sessionId": "abc123",
  "text": "Welcome!",
  "traceId": "0af7651916cd43dd8448eb211c80319c"
}

Logging

Structured logging at key decision points:

• Session start/end
• Menu navigation
• Action execution
• Error conditions

Error Handling

Error Code	HTTP Status	Description
UNAUTHORIZED	403	Missing or invalid tenant context
INVALID_MSISDN	400	MSISDN format validation failed
APP_NOT_FOUND	404	No application for shortcode
SESSION_NOT_FOUND	404	Session expired or doesn't exist
MENU_NOT_FOUND	500	Invalid navigation target
INTERNAL_ERROR	500	Unexpected processing error

See Also

• USSD DSL Guide - DSL syntax reference
• API Catalogue - OpenAPI documentation
• Quickstart - Quick examples