System Architecture Overview

The Add-on Services system follows a modular, service-oriented architecture designed for scalability and maintainability.

Core System Components

┌─────────────────────────────────────────────────────────────┐
│                    Add-on Services Architecture              │
├─────────────────────────────────────────────────────────────┤
│  Frontend Layer (Vue.js)                                   │
│  ├── addon-services.vue (Service Overview)                 │
│  └── addon-services-pricing-plans.vue (Purchase Interface) │
├─────────────────────────────────────────────────────────────┤
│  API Layer (Laravel Controllers)                           │
│  ├── BillingAddOnsPlanController (Plan Management)         │
│  ├── BillingAddOnsPaymentController (Payment Processing)   │
│  ├── AddOnServicesPaymentController (Purchase Flow)        │
│  └── Credits Controllers (Usage/Issuance/Notifications)    │
├─────────────────────────────────────────────────────────────┤
│  Service Layer                                              │
│  ├── Credit Management Services                            │
│  ├── Payment Processing Services                           │
│  ├── Threshold Monitoring Services                         │
│  └── Invoice Generation Services                           │
├────────────────────────────────────────────────────────────-|
│  Data Layer                                                 │
│  ├── Billing Tables (Plans, Payments, Subscriptions)        │
│  ├── Credit Tables (Usage, Issuance, Thresholds)            │
│  └── Audit Tables (Histories, Notifications)                │
└─────────────────────────────────────────────────────────────┘

Key Architecture Principles

1. Separation of Concerns

Clear boundaries between credit management, payment processing, and service consumption ensure maintainable and testable code.

2. Service Abstraction

Generic credit system that can be extended to any service type without core system changes.

3. Event-Driven Design

Real-time updates and notifications through WebSocket events provide immediate user feedback.

4. Audit Trail

Comprehensive logging of all credit transactions and changes for compliance and debugging.

Directory Structure

app/
├── Http/Controllers/V2/Controllers/AddonServices/
│   ├── BillingAddOnsPlanController.php          # Plan CRUD operations
│   ├── BillingAddOnsPaymentController.php       # Payment history & invoicing
│   ├── BillingCreditsUsageController.php        # Credit consumption tracking
│   ├── BillingCreditsIssuanceController.php     # Credit allocation tracking
│   └── BillingCreditsThresholdNotificationController.php # Threshold alerts
├── Http/Controllers/V2/Controllers/Services/
│   └── AddOnServicesPaymentController.php       # Purchase workflow
├── Models/Billing/
│   ├── BillingAddOnsPlan.php                    # Pricing plans model
│   ├── BillingAddOnsPayment.php                 # Payment transactions
│   ├── BillingCreditsUsage.php                  # Credit consumption log
│   ├── BillingCreditsIssuance.php              # Credit allocation log
│   ├── BillingSubscription.php                  # Service definitions
│   └── BillingSubscriptionThresholdSettings.php # Threshold config
├── Services/AddOnServices/
│   ├── AddOnPlans/AddonPlansQueryService.php    # Plan management
│   ├── Credits/
│   │   ├── AddCreditsToAddOnServiceService.php  # Credit allocation
│   │   ├── RemoveCreditsFromAddOnServiceService.php # Credit consumption
│   │   └── CheckCreditsAddOnServiceService.php  # Credit validation
│   ├── Payments/
│   │   ├── StoreAddOnServicesPaymentTransactionService.php # Payment processing
│   │   └── GenerateAddOnInvoiceService.php      # Invoice generation
│   └── ThresholdSettings/
│       └── SubscriptionThresholdNotificationsService.php # Threshold monitoring
└── Traits/AddOnServices/
    ├── AddOnPlans/DashboardTrait.php            # Dashboard functionality
    ├── Credits/Helpers/SmsCreditsUsageHelpersTrait.php # SMS integration
    └── Payments/PaymentsHelperMethodTrait.php   # Payment utilities

Component Interactions

Credit Purchase Flow

sequenceDiagram
    participant User as User
    participant Frontend as Vue Component
    participant API as Payment Controller
    participant Service as Payment Service
    participant Gateway as Payment Gateway
    participant Credits as Credit Service

    User->>Frontend: Select plan & payment method
    Frontend->>API: POST /purchase-service-plan
    API->>Service: handle(request, user)
    
    alt MPesa Payment
        Service->>Gateway: initiateSTKPush()
        Gateway-->>Service: payment_reference
        Service-->>API: payment_initiated
        API-->>Frontend: payment_reference
        
        Frontend->>API: POST /verify-purchase-service-plan
        API->>Service: verify(payment_reference)
        Service->>Gateway: queryTransaction(reference)
        Gateway-->>Service: payment_status
    end
    
    alt Payment Successful
        Service->>Credits: addCreditsToAccount()
        Credits-->>Service: credits_added
        Service-->>API: payment_completed
        API-->>Frontend: success_response
    end

Credit Consumption Flow

sequenceDiagram
    participant App as Application
    participant Check as CheckCreditsService
    participant Remove as RemoveCreditsService
    participant Threshold as ThresholdService
    participant Notify as NotificationService

    App->>Check: checkCredits(service_key, credits_needed)
    Check-->>App: credits_available

    App->>Remove: removeCredits(service_key, credits_needed)
    Remove->>Remove: decrementAvailableQuantity()
    Remove->>Remove: logUsage()
    Remove->>Threshold: alertThresholdBreach()
    
    alt Credits Below Threshold
        Threshold->>Notify: sendThresholdNotification()
        Notify-->>App: notification_sent
    end
    
    Remove-->>App: credits_removed

External Dependencies

Payment Gateways

Solutech Pay: Handles all Mpesa and Bank payments. For Addon Services, it handles its Mpesa payments

Notification Systems

Email/SMS: Threshold alerts and payment confirmations
WebSocket Service: Real-time frontend updates

Third-party Services

SMS Gateway: For SMS service integration
OCR Service: For LPO document processing

Security Architecture

Authentication & Authorization

Role-based access control: Granular permissions for different user types
API authentication: Bearer token authentication for API access across SAT, Portal and Solutech Pay
Session management: Secure session handling

Audit & Compliance

Complete audit trail: All transactions logged with user attribution
KRA compliance: Automatic tax reporting and invoice synchronization
Data retention: Configurable data retention policies

This architecture provides a solid foundation for the Add-on Services system, ensuring scalability, maintainability, and reliability while supporting current and future service types.

System Architecture

On this page