Architecture

The Suggested Products feature follows a modular architecture with clear separation of concerns, designed for scalability, maintainability, and performance.

System Overview

graph TB
    subgraph "Data Layer"
        A[Orders Database] --> B[Customer Data]
        A --> C[Product Data]
        B --> D[Historical Orders]
        C --> D
    end
    
    subgraph "Processing Layer"
        D --> E[Data Processor]
        E --> F[Customer Segmentation]
        F --> G[Apriori Algorithm]
        F --> H[Recent Orders Analysis]
    end
    
    subgraph "Service Layer"
        G --> I[Generation Service]
        H --> J[Recent Orders Service]
        I --> K[Report Service]
    end
    
    subgraph "API Layer"
        K --> L[REST Endpoints]
        J --> L
        L --> M[Authentication]
    end
    
    subgraph "Presentation Layer"
        L --> N[Vue.js Dashboard]
        L --> O[Excel Export]
        L --> P[Real-time API]
    end

Core Components

1. Controllers

The controller layer handles HTTP requests and orchestrates business logic:

SuggestedProductsController

• Purpose: Main controller for the suggested products report interface
• Responsibilities:
  • Request validation and parameter processing
  • Service orchestration
  • Response formatting
  • Error handling

Key Methods:

// Retrieve paginated suggested products data
public function index(Request $request)

// Handle Excel report downloads
public function download(Request $request)

// Render the dashboard view
public function dashboard()

SuggestedProductsFromRecentOrdersController

• Purpose: Handles real-time product suggestions based on recent orders
• Responsibilities:
  • Customer-specific suggestion retrieval
  • Real-time data processing
  • Price list integration

Key Methods:

// Returns suggested products for a specific customer
public function index(Request $request)

2. Services

The service layer contains the core business logic and machine learning implementations:

GenerateSuggestedProductsService

• Purpose: Core service implementing the Apriori algorithm
• Key Features:
  • Historical order data processing
  • Market basket analysis implementation
  • Frequent product set generation
  • Dual data model support (Orders v1 and v2)

Process Flow:

1. Data Collection    → getOrders($dates)
2. Customer Analysis  → customers($orders)  
3. Segmentation      → chunk(30)->each()
4. Algorithm Apply   → apply_apriori()
5. Results Storage   → save($product_sets)

GetSuggestedProductsReportService

• Purpose: Handles retrieval and formatting of suggestion reports
• Key Features:
  • Advanced filtering capabilities
  • Paginated data retrieval
  • Export functionality
  • Statistical calculations

GetSuggestedProductsFromRecentOrdersService

• Purpose: Provides real-time suggestions based on recent customer orders
• Key Features:
  • Configurable order cycles
  • Day-based filtering options
  • Price list integration
  • UOM (Unit of Measure) support

3. Models

The model layer defines the data structure and relationships:

SuggestedProduct

• Purpose: Main model representing generated product suggestions
• Relationships:
  • Belongs to Customer
  • Has many FrequentProductSets
  • Links to Product entities

FrequentProductSets

• Purpose: Stores individual products within a suggested product set
• Features:
  • UUID-based product set identification
  • Priority and status management
  • Source tracking for data lineage

GeneratingSuggestedProductsErrorLog

• Purpose: Comprehensive error logging and monitoring
• Features:
  • Detailed error message storage
  • Timestamp tracking
  • Integration with Laravel logging

4. Commands

GenerateSuggestedProductsCommand

• Purpose: Artisan command for batch processing
• Features:
  • Configurable date range processing
  • Memory optimization
  • Progress tracking
  • Error handling and recovery

Data Flow Architecture

sequenceDiagram
    participant C as Command/Controller
    participant S as Service Layer
    participant ML as ML Engine
    participant DB as Database
    participant Cache as Cache Layer
    
    C->>S: Request suggestions generation
    S->>DB: Fetch historical orders
    S->>S: Process and segment customers
    S->>ML: Apply Apriori algorithm
    ML->>ML: Generate frequent itemsets
    ML->>S: Return product associations
    S->>DB: Store suggested products
    S->>Cache: Cache frequent patterns
    S->>C: Return processing results

Component Interactions

1. Data Processing Pipeline

graph LR
    A[Raw Orders] --> B[Data Validation]
    B --> C[Customer Grouping]
    C --> D[Product Extraction]
    D --> E[Algorithm Input]
    E --> F[Apriori Processing]
    F --> G[Result Validation]
    G --> H[Storage]

2. Real-time Suggestion Flow

graph LR
    A[Customer Request] --> B[Recent Orders Query]
    B --> C[Pattern Analysis]
    C --> D[Price Integration]
    D --> E[Availability Check]
    E --> F[Response Formation]
    F --> G[Client Response]

Scalability Considerations

Horizontal Scaling

• Customer Segmentation: Processing in chunks allows parallel execution
• Database Sharding: Customer-based data distribution
• Cache Distribution: Redis cluster for frequently accessed patterns

Vertical Scaling

• Memory Management: Chunked processing prevents memory overflow
• CPU Optimization: Efficient algorithm implementation
• Database Indexing: Optimized queries for large datasets

Performance Optimizations

1. Database Level:

   • Indexed customer_id and product_set_id fields
   • Optimized JOIN operations
   • Proper pagination strategies

2. Application Level:

   • Chunked customer processing
   • Cached configuration values
   • Lazy loading for related models

3. Algorithm Level:

   • Configurable support/confidence thresholds
   • Early termination for sparse datasets
   • Memory-efficient data structures

Error Handling Strategy

Graceful Degradation

• Fallback to simpler algorithms if Apriori fails
• Default suggestions based on popular products
• Cached results for system availability

Monitoring and Logging

• Comprehensive error logging
• Performance metrics collection
• Algorithm accuracy tracking
• System health monitoring

Security Considerations

Data Protection

• Customer data anonymization where possible
• Secure API endpoints with authentication
• Role-based access control

Privacy Compliance

• GDPR-compliant data processing
• Customer consent management
• Data retention policies

Integration Points

External Systems

• ERP Integration: Product and customer data synchronization
• Price List Management: Real-time pricing updates
• Inventory Systems: Stock availability checking

Internal Modules

• Orders Management: Historical data source
• Customer Management: Customer segmentation
• Product Catalog: Product information and relationships

This architecture ensures the Suggested Products feature is robust, scalable, and maintainable while providing accurate and timely product recommendations.