Solutech Engineering
Innovations/SAT Usage Reports

Architecture & Components

System architecture, core components, and data models for SAT Usage Reports

Architecture & Components

This document details the system architecture, core components, and data models that power the SAT Usage Reports feature.

High-Level System Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                           SAT Usage Reports Ecosystem                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐          │
│  │   Client Apps   │    │   Portal API    │    │   Database      │          │
│  │                 │    │                 │    │                 │          │
│  │ ┌─────────────┐ │    │ - Sync Service  │    │ - Hourly Data   │          │
│  │ │SAT Usage    │ │◄──►│ - Controllers   │◄──►│ - Daily Data    │          │
│  │ │Radar        │ │    │ - Jobs/Commands │    │ - Aggregations  │          │
│  │ │             │ │    │ - Callbacks     │    │ - License Data  │          │
│  │ └─────────────┘ │    │                 │    │                 │          │
│  │                 │    │                 │    │                 │          │
│  │ - Data Collection    │ - Data Processing    │ - Storage &      │          │
│  │ - Aggregation        │ - Validation         │   Retrieval      │          │
│  │ - Transmission       │ - Analysis           │ - Reporting      │          │
│  └─────────────────┘    └─────────────────┘    └─────────────────┘          │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Client-Side Architecture (SAT Usage Radar)

┌─────────────────────────────────────────────────────────────────┐
│                    Client SAT System                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   Orders    │  │   Visits    │  │   Users     │              │
│  │   System    │  │   Tracking  │  │   Activity  │              │
│  │             │  │             │  │             │              │
│  │ - Orders V1 │  │ - Regular   │  │ - Backend   │              │
│  │ - Orders V2 │  │ - Off-route │  │ - Field     │              │
│  │ - Sales     │  │ - Duration  │  │ - Supervisor│              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │  Licenses   │  │ Deliveries  │  │   System    │              │
│  │  Management │  │   Tracking  │  │  Metadata   │              │
│  │             │  │             │  │             │              │
│  │ - Total     │  │ - Count     │  │ - Branch    │              │
│  │ - Allocated │  │ - Status    │  │ - Leave     │              │
│  │ - Expiry    │  │             │  │ - Config    │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│                                                                 │
│                    ┌─────────────────┐                         │
│                    │ SAT Usage Radar │                         │
│                    │   Service       │                         │
│                    │                 │                         │
│                    │ - Data Collect  │                         │
│                    │ - Aggregation   │                         │
│                    │ - Transmission  │                         │
│                    │ - Error Handle  │                         │
│                    └─────────────────┘                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Component Interaction Flow

  1. Client Data Collection: SAT Usage Radar collects metrics from various client modules
  2. Data Aggregation: Client system aggregates hourly performance data
  3. Secure Transmission: Data sent to Portal via authenticated HTTP requests
  4. Portal Processing: Portal validates, processes, and stores received data
  5. Callback Confirmation: Portal confirms successful processing to client
  6. Reporting Layer: Portal provides comprehensive analytics and reporting

Core Components

Portal System Components

1. Controllers

  • SatUsageReportsController: Main API controller handling all report endpoints
    • Data retrieval and filtering
    • Aggregations and analytics
    • Export functionality
    • Mismatch detection

2. Models

  • SatUsageHourlyReport: Stores raw hourly sync data
  • SatUsageDailyReport: Aggregated daily reports
  • Client: Client information and authentication
  • ClientLicense: License allocation and status

3. Services

  • TriggerSatUsageReportsSync: Core synchronization service
    • Client data fetching
    • Response processing
    • Error handling

4. Jobs & Commands

  • TriggerSatUsageReportsSyncCommand: Scheduled hourly execution
  • TriggerSatUsageReportsSyncJob: Queued processing

5. Traits

  • LogSatUsageReportsSyncTrait: Centralized logging and status management

Client System Components (SAT Usage Radar)

1. Service Architecture

  • Namespace: App\Services\Reports\SatUsageReports
  • Main Class: GenerateHourlySatUsageReportsService
  • Location: app/Services/Reports/SatUsageReports/GenerateHourlySatUsageReportsService.php

2. Data Collection Services

  • GetOrdersQueryService: Order and sales data aggregation
  • GetVisitsQueryService: Visit analytics and tracking
  • GetWorkingTimeQueryService: User activity monitoring
  • Database Queries: License, delivery, and leave management

3. Integration Dependencies

  • Order Management: Both Orders V1 and V2 systems
  • Visit Tracking: On-route and off-route visit monitoring
  • User Management: Active user tracking and leave management
  • Licensing System: License allocation and usage monitoring
  • Delivery Management: Delivery tracking and metrics
  • Git Integration: Branch tracking for deployment monitoring

4. Configuration Management

  • Environment Variables: Portal URLs and endpoints
  • Settings Management: System behavior configuration
  • Authentication: Token-based security for portal communication

Data Models

Portal System Models

SatUsageHourlyReport

protected $fillable = [
    'client_id',            // Client identifier
    'client_account_id',    // Client account identifier
    'client_code',          // Client code
    'start_date',           // Report period start
    'end_date',             // Report period end
    'total_licences',       // Total available licenses
    'assigned_licences',    // Licenses assigned to users
    'active_users_in_field',// Active field users
    'active_users_in_backend', // Active backend users
    'total_users',          // Total active users
    'users_on_leave',       // Users currently on leave
    'visits',               // Customer visits
    'offroute_visits',      // Off-route visits
    'total_visits',         // Total visits
    'number_of_orders',     // Number of orders
    'orders_value',         // Total order value
    'number_of_sales',      // Number of sales
    'sales_value',          // Total sales value
    'no_deliveries',        // Number of deliveries
    'current_branch',       // Current software branch
    'request_json',         // Original request data
    'response_json',        // Client response data
    'callback_json',        // Callback confirmation data
    'message',              // Status message
    'status'                // Sync status (pending/success/confirmed/failed)
];

SatUsageDailyReport

Aggregated daily view of hourly data with same metrics structure but date-based aggregation.

Client System Data Structure

The SAT Usage Radar on the client side collects and transmits data in the following comprehensive structure:

Complete Data Package Format

{
  "orders": {
    "total_sales": 0,           // Aggregate sales value from orders
    "successful_calls": 0       // Number of successful order interactions
  },
  "sales": {
    "total_sales": 0,           // Aggregate sales value from direct sales
    "successful_calls": 0       // Number of successful sales interactions
  },
  "visits": {
    "total_visits": 0,          // Overall number of customer visits
    "total_unique_visits": 0,   // Number of distinct customer locations
    "total_visits_duration": 0  // Total time spent on visits
  },
  "off_route_visits": {
    "total_visits": 0,          // Visits outside planned routes
    "total_unique_visits": 0,   // Distinct off-route customer locations
    "total_visits_duration": 0  // Time spent on unplanned visits
  },
  "active_users": {
    "total_active_users": 0,    // All users with activity in period
    "backend_users": 0,         // Administrative and support staff (Type 1)
    "field_users": 0,           // Sales representatives (Type 2)
    "supervisors": 0,           // Management and supervisory roles (Type 3)
    "other_users": 0            // Miscellaneous user types (Type 4)
  },
  "licenses": {
    "total_licenses": 0,        // Overall license count in system
    "allocated_licenses": 0,    // Licenses currently assigned to users
    "allocated_with_expiry": 0, // Time-limited license assignments
    "allocated_without_expiry": 0 // Permanent license assignments
  },
  "deliveries": {
    "no_deliveries": 0          // Total deliveries completed
  },
  "current_branch": "BRANCH-NAME", // Git branch for deployment tracking
  "users_on_leave": 0         // Count of approved leave requests
}

Data Collection Categories

1. Orders and Sales Metrics

  • Dual System Support: Handles both Orders V1 and V2 systems
  • Automatic Detection: Determines which system to use based on configuration
  • Separate Aggregation: Distinct tracking for orders vs direct sales
  • Entry Type Grouping: Groups data by transaction type for V1 systems

2. Visit Analytics

  • Regular Visits: Planned customer interactions
  • Off-Route Visits: Unplanned or emergency customer visits
  • Duration Tracking: Time spent on each visit type
  • Unique Location Tracking: Distinct customer location counts

3. User Activity Monitoring

  • Role-Based Categorization: Users grouped by functional roles
  • Activity Detection: Only active users within reporting period counted
  • Leave Integration: Automatic adjustment for users on approved leave

4. License Management

  • Allocation Tracking: Real-time license assignment monitoring
  • Expiry Management: Separate tracking for temporary vs permanent licenses
  • Utilization Metrics: License usage efficiency calculations

5. System Metadata

  • Branch Tracking: Git branch information for deployment monitoring
  • JIRA Integration: Automatic ticket pattern recognition (e.g., ABC-123)
  • Leave Management: Working days configuration for accurate impact assessment

Business Logic

License Utilization Calculation

$sat_usage_percentage = $assigned_licences > 0 
    ? round(($total_users / $assigned_licences) * 100, 2) 
    : 0;

Daily Aggregation Logic

  • Single Date: Direct data from daily report
  • Date Range: Averages for licenses/users, sums for transactions

Mismatch Detection

Identifies clients where:

  • Assigned licenses > Portal licenses
  • Calculates difference for reporting

Portal License Calculation

$portal_licence_no = ClientLicense::query()
    ->where('status_id', 1)
    ->whereNotIn('license_id', [2, 3]) // Exclude specific license types
    ->sum('quantity');

API & Synchronization

API endpoints, synchronization processes, and data flow for SAT Usage Reports

Configuration & Deployment

Configuration options, database schema, and deployment guidelines for SAT Usage Reports

On this page

Architecture & ComponentsHigh-Level System ArchitectureClient-Side Architecture (SAT Usage Radar)Component Interaction FlowCore ComponentsPortal System Components1. Controllers2. Models3. Services4. Jobs & Commands5. TraitsClient System Components (SAT Usage Radar)1. Service Architecture2. Data Collection Services3. Integration Dependencies4. Configuration ManagementData ModelsPortal System ModelsSatUsageHourlyReportSatUsageDailyReportClient System Data StructureComplete Data Package FormatData Collection Categories1. Orders and Sales Metrics2. Visit Analytics3. User Activity Monitoring4. License Management5. System MetadataBusiness LogicLicense Utilization CalculationDaily Aggregation LogicMismatch DetectionPortal License CalculationRelated Documentation