2025-09-05 18:22:55 +09:00
# SIM Management Page - API Data Flow & System Architecture
*Technical documentation explaining the API integration and data flow for the SIM Management interface*
**Purpose**: This document provides a detailed explanation of how the SIM Management page retrieves, processes, and displays data through various API integrations.
**Audience**: Management, Technical Teams, System Architects
**Last Updated**: September 2025
---
## 📋 Executive Summary
Change Log (2025-09-05)
- Adopted official Freebit API names across all callouts (e.g., "Add Specs & Quota", "MVNO Plan Change").
- Added Freebit API Quick Reference (Portal Operations) table.
- Documented Top‑ ‑
- Listed additional Freebit APIs not used by the portal today.
The SIM Management page integrates with multiple backend systems to provide real-time SIM data, usage statistics, and management capabilities. The system uses a **Backend-for-Frontend (BFF)** architecture that aggregates data from Freebit APIs and WHMCS, providing a unified interface for SIM management operations.
### Key Systems Integration:
- **WHMCS**: Subscription and billing data
- **Freebit API**: SIM details, usage, and management operations
- **Customer Portal BFF**: Data aggregation and API orchestration
---
## 🏗️ System Architecture Overview
```
┌─────────────────────────────────────────────────────────────────┐
│ Customer Portal Frontend │
│ (Next.js - Port 3000) │
├─────────────────────────────────────────────────────────────────┤
│ SIM Management Page Components: │
│ • SimManagementSection.tsx │
│ • SimDetailsCard.tsx │
│ • DataUsageChart.tsx │
│ • SimActions.tsx │
│ • SimFeatureToggles.tsx │
└─────────────────────────────────────────────────────────────────┘
│
│ HTTP Requests
▼
┌─────────────────────────────────────────────────────────────────┐
│ Backend-for-Frontend (BFF) │
│ (Port 4000) │
├─────────────────────────────────────────────────────────────────┤
│ API Endpoints: │
│ • /api/subscriptions/{id}/sim │
│ • /api/subscriptions/{id}/sim/details │
│ • /api/subscriptions/{id}/sim/usage │
│ • /api/subscriptions/{id}/sim/top-up │
│ • /api/subscriptions/{id}/sim/top-up-history │
│ • /api/subscriptions/{id}/sim/change-plan │
│ • /api/subscriptions/{id}/sim/features │
│ • /api/subscriptions/{id}/sim/cancel │
│ • /api/subscriptions/{id}/sim/reissue-esim │
└─────────────────────────────────────────────────────────────────┘
│
│ Data Aggregation
▼
┌─────────────────────────────────────────────────────────────────┐
│ External Systems │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ WHMCS │ │ Freebit API │ │
│ │ (Billing) │ │ (SIM Services) │ │
│ │ │ │ │ │
│ │ • Subscriptions │ │ • SIM Details │ │
│ │ • Customer Data │ │ • Usage Data │ │
│ │ • Billing Info │ │ • Management │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
---
## 📊 Data Flow by Section
### 1. **SIM Management Actions Section**
**Purpose**: Provides action buttons for SIM operations (Top Up, Reissue, Cancel, Change Plan)
**Data Sources**:
- **WHMCS**: Subscription status and customer permissions
- **Freebit API**: SIM type (physical/eSIM) and current status
**API Calls**:
```typescript
// Initial Load - Get SIM details for action availability
GET /api/subscriptions/{id}/sim/details
```
**Data Flow**:
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ BFF │ │ Freebit API │
│ │ │ │ │ │
│ SimActions.tsx │───▶│ /sim/details │───▶│ /mvno/getDetail/│
│ │ │ │ │ │
│ • Check SIM │ │ • Authenticate │ │ • Return SIM │
│ type & status │ │ • Map response │ │ details │
│ • Enable/disable│ │ • Handle errors │ │ • Status info │
│ buttons │ │ │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
**Action-Specific APIs**:
- **Top Up Data**: `POST /api/subscriptions/{id}/sim/top-up` → Freebit `/master/addSpec/`
- **Reissue eSIM**: `POST /api/subscriptions/{id}/sim/reissue-esim` → Freebit `/mvno/esim/addAcnt/`
- **Cancel SIM**: `POST /api/subscriptions/{id}/sim/cancel` → Freebit `/mvno/releasePlan/`
- **Change Plan**: `POST /api/subscriptions/{id}/sim/change-plan` → Freebit `/mvno/changePlan/`
---
### 2. **eSIM Details Card (Right Sidebar)**
**Purpose**: Displays essential SIM information in compact format
**Data Sources**:
- **WHMCS**: Subscription product name and billing info
- **Freebit API**: SIM technical details and status
**API Calls**:
```typescript
// Get comprehensive SIM information
GET /api/subscriptions/{id}/sim
```
**Data Flow**:
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ BFF │ │ External │
│ │ │ Systems │ │ Systems │
│ SimDetailsCard │───▶│ /sim │───▶│ ┌─────────────┐ │
│ │ │ │ │ │ WHMCS │ │
│ • Phone number │ │ • Aggregate │ │ │ • Product │ │
│ • Data remaining│ │ data from │ │ │ name │ │
│ • Service status│ │ multiple │ │ │ • Billing │ │
│ • Plan info │ │ sources │ │ └─────────────┘ │
│ │ │ • Transform │ │ ┌─────────────┐ │
│ │ │ responses │ │ │ Freebit │ │
│ │ │ • Handle errors │ │ │ • ICCID │ │
│ │ │ │ │ │ • MSISDN │ │
│ │ │ │ │ │ • Status │ │
│ │ │ │ │ │ • Plan code │ │
│ │ │ │ │ └─────────────┘ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
**Data Mapping**:
```typescript
// BFF Response Structure
{
"details": {
"iccid": "8944504101234567890", // From Freebit
"msisdn": "08077052946", // From Freebit
"planCode": "PASI_50G", // From Freebit
"status": "active", // From Freebit
"simType": "esim", // From Freebit
"productName": "SonixNet SIM Service", // From WHMCS
"remainingQuotaMb": 48256 // Calculated
}
}
```
---
### 3. **Data Usage Chart (Right Sidebar)**
**Purpose**: Visual representation of data consumption and remaining quota
**Data Sources**:
- **Freebit API**: Real-time usage statistics and quota information
**API Calls**:
```typescript
// Get usage data
GET /api/subscriptions/{id}/sim/usage
```
**Data Flow**:
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ BFF │ │ Freebit API │
│ │ │ │ │ │
│ DataUsageChart │───▶│ /sim/usage │───▶│ /mvno/getTraffic│
│ │ │ │ │ Info/ │
│ • Progress bar │ │ • Authenticate │ │ │
│ • Usage stats │ │ • Format data │ │ • Today's usage │
│ • History chart │ │ • Calculate │ │ • Total quota │
│ • Remaining GB │ │ percentages │ │ • Usage history │
│ │ │ • Handle errors │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
**Data Processing**:
```typescript
// Freebit API Response
{
"todayUsageMb": 748.47,
"totalQuotaMb": 51200,
"usageHistory": [
{ "date": "2025-01-04", "usageMb": 1228.8 },
{ "date": "2025-01-03", "usageMb": 595.2 },
{ "date": "2025-01-02", "usageMb": 448.0 }
]
}
// BFF Processing
const usagePercentage = (usedMb / totalQuotaMb) * 100;
const remainingMb = totalQuotaMb - usedMb;
const formattedRemaining = formatQuota(remainingMb); // "47.1 GB"
```
---
### 4. **Plan & Service Options**
**Purpose**: Manage SIM plan and optional features (Voice Mail, Call Waiting, International Roaming, 4G/5G).
**Data Sources**:
- **Freebit API**: Current service settings and options
- **WHMCS**: Plan catalog and billing context
**API Calls**:
```typescript
// Get current service settings
GET /api/subscriptions/{id}/sim/details
// Update optional features (flags)
POST /api/subscriptions/{id}/sim/features
// Change plan
POST /api/subscriptions/{id}/sim/change-plan
```
**Data Flow**:
```
┌─────────────────┐ ┌─────────────────┐ ┌──────────────────────────┐
│ Frontend │ │ BFF │ │ Freebit API │
│ │ │ │ │ │
│ SimFeatureToggles│───▶│ /sim/details │───▶│ /mvno/getDetail/ │
│ │ │ │ │ │
│ Apply Changes │───▶│ /sim/features │───▶│ /master/addSpec/ (flags) │
│ Change Plan │───▶│ /sim/change-plan│───▶│ /mvno/changePlan/ │
│ │ │ │ │ │
│ • Validate │ │ • Authenticate │ │ • Apply changes │
│ • Update UI │ │ • Transform │ │ • Return resultCode=100 │
│ • Refresh data │ │ • Handle errors │ │ │
└─────────────────┘ └─────────────────┘ └──────────────────────────┘
```
Allowed plans and mapping
- The portal currently supports the following SIM data plans from Salesforce:
- SIM Data-only 5GB → Freebit planCode `PASI_5G`
- SIM Data-only 10GB → `PASI_10G`
- SIM Data-only 25GB → `PASI_25G`
- SIM Data-only 50GB → `PASI_50G`
- UI behavior: The Change Plan action lives inside the “SIM Management Actions” card. Clicking it opens a modal listing only “other” plans. For example, if the current plan is `PASI_50G` , options will be 5GB, 10GB, 25GB. If the current plan is not 50GB, the 50GB option is included.
- Request payload sent to BFF:
```json
{
"newPlanCode": "PASI_25G"
}
```
- BFF calls MVNO Plan Change with fields per the API spec (account, planCode, optional globalIP, optional runTime).
---
### 5. **Top-Up Payment Flow (Invoice + Auto-Capture)**
When a user tops up data, the portal bills through WHMCS before applying the quota via Freebit. Unit price is fixed: 1 GB = ¥500.
Endpoints used
- Frontend → BFF: `POST /api/subscriptions/{id}/sim/top-up` with `{ quotaMb, campaignCode?, expiryDate? }`
- BFF → WHMCS: `createInvoice` then `capturePayment` (gateway-selected SSO or stored method)
- BFF → Freebit: `PA04-04 Add Spec & Quota` (`/master/addSpec/` ) if payment succeeds
Pricing
2025-09-06 17:02:20 +09:00
- Amount in JPY = ceil(quotaMb / 1000) ×
- Example: 1000MB → ¥500, 3000MB → ¥1,500
2025-09-05 18:22:55 +09:00
Happy-path sequence
```
Frontend BFF WHMCS Freebit
────────── ──────────────── ──────────────── ────────────────
TopUpModal ───────▶ POST /sim/top-up ───────▶ createInvoice ─────▶
2025-09-06 17:02:20 +09:00
(quotaMb) (validate + map) (amount=ceil(MB/1000)*500)
2025-09-05 18:22:55 +09:00
│ │
│ invoiceId
▼ │
capturePayment ───────────────▶ │
│ paid (or failed)
├── on success ─────────────────────────────▶ /master/addSpec/
2025-09-09 15:40:13 +09:00
│ (quota in MB)
2025-09-05 18:22:55 +09:00
└── on failure ──┐
└──── return error (no Freebit call)
```
Failure handling
- If `capturePayment` fails, BFF responds with 402/400 and does NOT call Freebit. UI shows error and invoice link for manual payment.
- If Freebit returns non-100 `resultCode` , BFF logs, returns 502/500, and may void/refund invoice in future enhancement.
BFF responsibilities
- Validate `quotaMb` (1–
- Price computation and invoice line creation (description includes quota)
- Attempt payment capture (stored method or SSO handoff)
2025-09-09 15:40:13 +09:00
- On success, call Freebit AddSpec with `quota` in MB (string) and optional `expire`
2025-09-05 18:22:55 +09:00
- Return success to UI and refresh SIM info
Freebit PA04-04 (Add Spec & Quota) request fields
- `account` : MSISDN (phone number)
2025-09-09 15:40:13 +09:00
- `quota` : integer MB (string) (100MB–
2025-09-05 18:22:55 +09:00
- `quotaCode` (optional): campaign code
- `expire` (optional): YYYYMMDD
Notes
- Scheduled top-ups use `/mvno/eachQuota/` with `runTime` ; immediate uses `/master/addSpec/` .
- For development, amounts and gateway can be simulated; production requires real WHMCS gateway configuration.
---
## 🔄 Real-Time Data Updates
### Automatic Refresh Mechanism
```typescript
// After any action (top-up, cancel, etc.)
const handleActionSuccess = () => {
// Refresh all data
refetchSimDetails();
refetchUsageData();
refetchSubscriptionData();
};
```
### Data Consistency
- **Immediate Updates**: UI updates optimistically
- **Background Sync**: Real data fetched after actions
- **Error Handling**: Rollback on API failures
- **Loading States**: Visual feedback during operations
---
## 📈 Performance Considerations
### Caching Strategy
```typescript
// BFF Level Caching
- SIM Details: 5 minutes TTL
- Usage Data: 1 minute TTL
- Subscription Info: 10 minutes TTL
// Frontend Caching
- React Query: 30 seconds stale time
- Background refetch: Every 2 minutes
```
### API Optimization
- **Batch Requests**: Single endpoint for comprehensive data
- **Selective Updates**: Only refresh changed sections
- **Error Recovery**: Retry failed requests with exponential backoff
---
## 🛡️ Security & Authentication
### Authentication Flow
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ BFF │ │ External │
│ │ │ │ │ Systems │
│ • JWT Token │───▶│ • Validate JWT │───▶│ • WHMCS API Key │
│ • User Context │ │ • Map to WHMCS │ │ • Freebit Auth │
│ • Permissions │ │ Client ID │ │ • Rate Limiting │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
### Data Protection
- **Input Validation**: All user inputs sanitized
- **Rate Limiting**: API calls throttled per user
- **Audit Logging**: All actions logged for compliance
- **Error Masking**: Sensitive data not exposed in errors
---
## 📊 Monitoring & Analytics
### Key Metrics Tracked
- **API Response Times**: < 500ms target
- **Error Rates**: < 1 % target
- **User Actions**: Top-up frequency, plan changes
- **Data Usage Patterns**: Peak usage times, quota consumption
### Health Checks
```typescript
// BFF Health Endpoints
GET /health/sim-management
GET /health/freebit-api
GET /health/whmcs-api
```
---
## 🚀 Future Enhancements
### Planned Improvements
1. **Real-time WebSocket Updates** : Live usage data without refresh
2. **Advanced Analytics** : Usage predictions and recommendations
3. **Bulk Operations** : Manage multiple SIMs simultaneously
4. **Mobile App Integration** : Native mobile SIM management
### Scalability Considerations
- **Microservices**: Split BFF into domain-specific services
- **CDN Integration**: Cache static SIM data globally
- **Database Optimization**: Implement read replicas for usage data
---
## 📞 Support & Troubleshooting
### Common Issues
1. **API Timeouts** : Check Freebit API status
2. **Data Inconsistency** : Verify WHMCS sync
3. **Authentication Errors** : Validate JWT tokens
4. **Rate Limiting** : Monitor API quotas
### Debug Endpoints
```typescript
// Development only
GET /api/subscriptions/{id}/sim/debug
GET /api/health/sim-management/detailed
```
---
## 📋 **Summary for Your Managers**
This comprehensive documentation explains:
### **🏗️ System Architecture**
- **3-Tier Architecture**: Frontend → BFF → External APIs (WHMCS + Freebit)
- **Data Aggregation**: BFF combines data from multiple sources
- **Real-time Updates**: Automatic refresh after user actions
### **📊 Key Data Flows**
1. **SIM Actions** : Button availability based on SIM type and status
2. **SIM Details** : Phone number, data remaining, service status
3. **Usage Chart** : Real-time consumption and quota visualization
4. **Service Options** : Voice mail, call waiting, roaming settings
### **🔧 Technical Benefits**
- **Performance**: Caching and optimized API calls
- **Security**: JWT authentication and input validation
- **Reliability**: Error handling and retry mechanisms
- **Monitoring**: Health checks and performance metrics
### **💼 Business Value**
- **User Experience**: Real-time data and intuitive interface
- **Operational Efficiency**: Automated SIM management operations
- **Data Accuracy**: Direct integration with Freebit and WHMCS
- **Scalability**: Architecture supports future enhancements
This documentation will help your managers understand the technical complexity and business value of the SIM Management system!
