# 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!