7c929eb4dc
- Streamlined the README.md for clarity and conciseness. - Deleted outdated documentation files related to Freebit SIM management, SIM management API data flow, and various architectural guides to reduce clutter and improve maintainability. - Updated the last modified date in the README to reflect the latest changes.
510 lines
22 KiB
Markdown
510 lines
22 KiB
Markdown
# 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‑Up Payment Flow (WHMCS invoice + auto‑capture then Freebit AddSpec).
|
||
- 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
|
||
|
||
- Amount in JPY = ceil(quotaMb / 1000) × 500
|
||
- Example: 1000MB → ¥500, 3000MB → ¥1,500
|
||
|
||
Happy-path sequence
|
||
|
||
```
|
||
Frontend BFF WHMCS Freebit
|
||
────────── ──────────────── ──────────────── ────────────────
|
||
TopUpModal ───────▶ POST /sim/top-up ───────▶ createInvoice ─────▶
|
||
(quotaMb) (validate + map) (amount=ceil(MB/1000)*500)
|
||
│ │
|
||
│ invoiceId
|
||
▼ │
|
||
capturePayment ───────────────▶ │
|
||
│ paid (or failed)
|
||
├── on success ─────────────────────────────▶ /master/addSpec/
|
||
│ (quota in MB)
|
||
└── 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–100000)
|
||
- Price computation and invoice line creation (description includes quota)
|
||
- Attempt payment capture (stored method or SSO handoff)
|
||
- On success, call Freebit AddSpec with `quota` in MB (string) and optional `expire`
|
||
- Return success to UI and refresh SIM info
|
||
|
||
Freebit PA04-04 (Add Spec & Quota) request fields
|
||
|
||
- `account`: MSISDN (phone number)
|
||
- `quota`: integer MB (string) (100MB–51200MB)
|
||
- `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!
|