What is Mobile Billing System

In telecom platforms, large subscription businesses (like Rakuten), systems are usually split into:
1. OSS (Operational Support Systems) → network operations, provisioning, monitoring
2. Mobile Billing System/BSS (Business Support Systems) → customers, products, billing, payments, revenue.

Requirements

Functional

1. Monthly data pack subscriptions: Support states(Active, Expired, Suspended, Cancelled)
2. Pack Expiry Handling: When a pack reaches its expiry: Service usage must be blocked, Customer is notified (SMS / Email / App), Account state updated.
  Billing system does NOT directly stop network service → It notifies OSS / Network Control
3. Accept Payments & Renew: System shall accept customer payments & renew
4. Failed Payments: Do not renew pack, Retry payment based on policy, Notify customer
5. Refund & Adjustment: Full, Partial, Manual(policy based)
6. Overlimit Usage: Prevent usage beyond allowed quota. Soft limit (throttle), Hard limit (block)
7. Billing history: Store to show to customer

Non Functional Requirements

1. Scalable: if new customer come in, system should scale
2. High Availability: 99.9%+ availability. Multi AZ deployment
3. Consistency: No duplicate billing
4. Reliable: if billed once, it should not tell not billed recharge
5. Latency: Low, pack activation instant

BOE

OSS(See HLD Diagram) will send CDR(Call Detial Records) in Batch to BSS.
CDRs are send in BATCHES using Kafka from OSS to BSS

CDR ~= 300-500 bytes

| Field           | Reason              |
| --------------- | ------------------- |
| IMSI            | Subscriber identity |
| MSISDN          | Caller number       |
| Called number   | Receiver            |
| Call start time |                     |
| Call end time   |                     |
| Call duration   |                     |
| Cell ID         | Location            |
| MSC ID          | Network element     |
| Call type       | MO/MT               |
| Service type    | Voice/SMS/Data      |
| Cause code      | Call drop, reject   |
| Charging ID     | Correlation         |
| Roaming info    | Tariff impact       |
| Bearer type     | LTE/VoLTE           |
| Sequence number | Dedup               |
      

Storage estimates

Total users = 1M
Total calls/day/user = 30.
Outgoing calls = 15
1M users × 30 calls = 30M CDRs/day
30M x 300 = 9GB/day
9 GB × 365 ≈ 3.2 TB/year
3.2 x 5 ≈ 16 TB / 5 years

Traffic Estimates (Incoming bytes/sec)

5 calls/user/hour
1M × 5 / 3600 ≈ 1389 calls/sec
Incoming data = 1389 × 300 bytes ≈ 416,700 bytes/sec ≈ 407 KB/sec

Peak factor (3x or 5x)
- Telecom traffic is bursty
- Peak ≈ 407KB x 5 = 2 MB/sec
But we will design ingestion for ≥5 MB/sec to be safe.

Network Architecture

Database Schema/Tables

subscriber_id (primary Key)
name
dob
IMSI(UNIQUE)
MSISDN
status (active/inactive/suspended)
activation_date
deactivation_date
created_at

5 | ram | 25/2 | xxx | yy | active | 9jan | -
            

plan_id (PK)
plan_code
plan_name
validity_days
price
currency
is_prepaid
status

10 | 279_PLAN | 279 Combo Plan | 30 days | ₹279 | INR | y
15 | 999_PLAN | 999 Combo Plan | 90 days | ₹999 | INR | y
            

product_id (PK)
product_code
product_name
product_type (DATA / OTT / VOICE / SMS)
description

1 | Netflix | OTT | Unlimited ad-free movies, TV shows
2 | Amazon | OTT | Unlimited ad-free movies, TV shows
3 | Zee5 | OTT | Unlimited ad-free movies, TV shows
4 | 1GBD| 1 GB data | DATA | 1GB Data Pack
            

id
plan_id (FK)
product_id (FK)
quantity
unit

id|plan_id|product_id
1 | 10 | 1 //279_PLAN has Netflix
1 | 10 | 2 //279_PLAN has Amazon
1 | 10 | 3 //279_PLAN has Zee5
            

id
subscriber_id (FK)
plan_id (FK)
start_date
end_date
renew_date

5 | 10 | ...
            

HLD

Flows

New Subscriber / Subscriber Purchases a SIM card

Person goes to shop and purchases SIM card, makes 1st recharge. This message flows to BSS

OSS                        telcoBSS(Onboarding service)
  -- POST /v1/customers -->  REST_EndPoint
      json {                          --------INSERT INTO ------> Subscriber Table
        "imsi": "xxx",                     status=inactive     5 | ram | 25/2 | xxx | yy | inactive | 9jan | 
        "msisdn": "yyy",
        "name": "ram",
        "dob": "1995-11-23",
        "kyc_status": "VERIFIED"
      }

    <------- Registered ---------------

  Connect Plan                  telcoBSS(Order Service)
  ---- POST /subscription/activate -->
      json {
        "imsi": "xxx",
        "plan_code": "279_PLAN",
        "payment_ref": "txn_123"
      }
                                      telcoBSS(Order Service)
                                      // Verify req is not duplicate? (idempotency key)
                                      
                                        -----------payment_ref: "txn_123" ---------> Payment_GW
                                        <------------Pending------------------------
                                        retry for 5 times
                                        <------------ success ----------------------

                                        BSS
                                        -- INSERT INTO ------> Subscription table
      

Verify Payment Status

Why Payment status need to be verified?

User → Payment Gateway / Wallet
            ↓
        Payment System
            ↓
          BSS
        

User will send money to payment gateway and this information will not come to OSS. When recharge is successful Payment Gateway will send this information to OSS asynchronously.

Update Plan from 299_PLAN to 999_PLAN

Only subscription table need to be changed

OSS                      BSS
  -- update_plan --<  REST_EndPoint
                         ----- UPDATE ROW ------< Subscription table
      

Kafka Communication from OSS to BSS

Overall Flow

@startuml

actor "Customer Portal\nAdmin UI" as UI

box Microservices
participant "External\nAPIs" as API
participant "Onboarding\nservice(Go)" as ONB
participant "order\nservice(Go)" as ORD
participant "billing\nservice(Go)" as BILL
participant "Rating\nengine(C++)" as RATE
participant "Admin\nservice(Go)-Optional" as ADMIN
end box

queue "Kafka Topics" as KAFKA

box Databases
database "Couchbase" as CB
database "MySQL" as SQL
end box

box Observibility
participant "Prometheus" as PROM
participant "Grafana" as GF
participant "Kibana" as KB
end box

participant "Elasticsearch" as ELK

== Onboarding Flow ==

UI -> ONB : POST /v1/customers\n(subscriber data)
ONB -> CB : Store Subscriber (subscriber_id, name, dob, IMSI, MSISDN, status, etc.)
ONB -> KAFKA : Produce CustomerOnboarded (customer_events)
KAFKA -> BILL : Consume CustomerOnboarded
BILL -> SQL : Initialize Billing Account (Subscription table)

== Order Flow ==

UI -> ORD : POST /v1/orders (order data)
note over ORD
Mapping of 
subscriber to
plan
end note

ORD -> SQL : Validate & Store Subscription(id, subscriber_id, plan_id, dates)
ORD -> CB : Store Order Details (orders collection)
ORD -> KAFKA : Produce OrderPlaced (order_events)
KAFKA -> RATE : Consume OrderPlaced
RATE -> RATE : Simulate Provisioning

== Admin Flow (Optional) ==

UI -> ADMIN : Manage Master Data\n(Plans, Products, Plan_to_Product)
ADMIN -> SQL : Fill Plans, Products,\nPlan_to_Product tables

== Data Usage Rating Flow ==

API -> KAFKA : Inject Usage Events\n(usage_events)
KAFKA -> RATE : Consume Usage Events
RATE -> RATE : Apply Rating Logic\n(bytes * rate)
RATE -> KAFKA : Produce Rated Events\n(rated_events)
KAFKA -> BILL : Consume Rated Events
BILL -> SQL : Create/Update Invoices\n(invoices, invoice_items)
BILL -> CB : Store Invoice Metadata\n(usage_records)
BILL -> KAFKA : Produce Billing Events\n(billing_events)

== Billing Query ==

UI -> BILL : GET /v1/invoices
BILL -> SQL : Fetch Invoice Data
BILL --> UI : Return Invoice

== Observability ==

ONB -> PROM : Send Metrics
ORD -> PROM : Send Metrics
BILL -> PROM : Send Metrics
RATE -> PROM : Send Metrics
PROM -> GF : Visualize Dashboards
ELK -> KB : Index Logs

@enduml
      

Terms

IMSI(International Mobile Subscriber Identity)

An IMSI number is a unique, 15-digit code that identifies a specific mobile phone subscriber in a cellular network, stored on the SIM card and used for network authentication, distinct from your public phone number.
IMSI = {Mobile Country Code (MCC) + Mobile Network Code (MNC) + and Mobile Subscription Identification Number (MSIN)}

MSISDN