tema 425ef83dba Update SIM management service and UI components for Freebit API compliance

- Adjusted quota validation in SimManagementService to enforce limits of 100MB to 51200MB for Freebit API compatibility.
- Updated cost calculation to round up GB usage for billing, ensuring accurate invoice generation.
- Modified top-up modal and related UI components to reflect new limits of 1-50 GB, aligning with Freebit API constraints.
- Enhanced documentation to clarify pricing structure and API data flow adjustments.

2025-09-09 15:40:13 +09:00

22 KiB

Raw Blame History

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:

// 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:

// 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:

// 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:

// 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:

// 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:

// 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:

{
  "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

// 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

// 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

// BFF Health Endpoints
GET /health/sim-management
GET /health/freebit-api
GET /health/whmcs-api

🚀 Future Enhancements

Planned Improvements

Real-time WebSocket Updates: Live usage data without refresh
Advanced Analytics: Usage predictions and recommendations
Bulk Operations: Manage multiple SIMs simultaneously
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

API Timeouts: Check Freebit API status
Data Inconsistency: Verify WHMCS sync
Authentication Errors: Validate JWT tokens
Rate Limiting: Monitor API quotas

Debug Endpoints

// 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

SIM Actions: Button availability based on SIM type and status
SIM Details: Phone number, data remaining, service status
Usage Chart: Real-time consumption and quota visualization
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!

22 KiB Raw Blame History Unescape Escape

SIM Management Page - API Data Flow & System Architecture

📋 Executive Summary

Key Systems Integration:

🏗️ System Architecture Overview

📊 Data Flow by Section

1. SIM Management Actions Section

2. eSIM Details Card (Right Sidebar)

3. Data Usage Chart (Right Sidebar)

4. Plan & Service Options

5. Top-Up Payment Flow (Invoice + Auto-Capture)

🔄 Real-Time Data Updates

Automatic Refresh Mechanism

Data Consistency

📈 Performance Considerations

Caching Strategy

API Optimization

🛡️ Security & Authentication

Authentication Flow

Data Protection

📊 Monitoring & Analytics

Key Metrics Tracked

Health Checks

🚀 Future Enhancements

Planned Improvements

Scalability Considerations

📞 Support & Troubleshooting

Common Issues

Debug Endpoints

📋 Summary for Your Managers

🏗️ System Architecture

📊 Key Data Flows

🔧 Technical Benefits

💼 Business Value

22 KiB

Raw Blame History