Wishlist System Overview

Description

The Wishlist System is a comprehensive product tracking and analysis platform that enables users to monitor e-commerce products, analyze market trends, and generate AI-powered insights. The system operates through a two-stage workflow: temporary wishlist preparation and official wishlist monitoring, integrated with external services including OpenAI for AI-powered viewpoint generation, TV Python API for dataset analysis, and real-time notifications through Pusher.

Database Architecture:

• Primary Database: gb_console - Stores all user data, wishlist data, subscription data, and business logic
• Analysis Database: gb_analyzer - Read-only access to processed analysis data, products, reviews, and rankings

The system serves as the core functionality for the Trend Viewer platform, allowing users to:

• Create and manage product collections across multiple e-commerce platforms (Amazon, Rakuten)
• Generate AI-powered category descriptions and specific viewpoints using OpenAI
• Perform comprehensive market analysis through TV Python API integration
• Track price changes, rankings, and trends in real-time
• Collaborate on wishlists within user groups with subscription-based quota management
• Import/export data via CSV for bulk operations

Architecture Overview

The Wishlist System follows a structured architecture with clear separation of concerns:

• API Controllers: Handle HTTP requests, validate inputs, and coordinate responses
• Service Layer: Implement business logic, data transformations, and external service integration
• Repository Layer: Manage data access with the repository pattern implementation
• Models: Define data structures and relationships between system entities
• External Services: Integrate with OpenAI, TV Python API, Pusher, and Stripe

The system implements Laravel's repository pattern using the custom haldata/laravel-repository package, ensuring clean separation between business logic and data access concerns. Authentication is handled via Laravel Sanctum with comprehensive middleware protection for all endpoints.

System Overview Diagram

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: basis
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TB
    %% Main components with clearer hierarchy
    Client[Frontend Application] 
    
    %% External Services with distinctive styling
    subgraph ExternalServices["External Services"]
        OpenAI((OpenAI API))
        TVPythonAPI((TV Python API))
        StripeAPI((Stripe API))
        PusherAPI((Pusher API))
    end
    
    %% Controllers with clear grouping
    subgraph APILayer["API Controllers Layer"]
        subgraph TempControllers["Temporary Wishlist Controllers"]
            TempWishlistController[TempWishlistToGroupController]
            TempViewpointController[TempViewpointController]
        end
        
        subgraph OfficialControllers["Official Wishlist Controllers"]
            WishlistController[WishlistToGroupController]
            WishlistViewpointController[WishlistViewpointController]
            AnalysisController[AnalysisController]
        end
    end
    
    %% Services with logical grouping
    subgraph ServiceLayer["Business Logic Services"]
        subgraph TempServices["Temporary Wishlist Services"]
            TempWishlistService(TempWishlistToGroupService)
            TempViewpointService(TempViewpointService)
        end
        
        subgraph OfficialServices["Official Wishlist Services"]
            WishlistService(WishlistToGroupService)
            DatasetService(DatasetService)
        end
        
        subgraph IntegrationServices["Integration Services"]
            OpenAIService(OpenAIService)
            AnalyzerAPIService(AnalyzerAPIService)
            SubscriptionService(SubscriptionService)
        end
    end
    
    %% Repositories with clear grouping
    subgraph DatabaseLayer["Data Access Layer"]
        subgraph TempRepositories["Temporary Wishlist Repositories"]
            TempWishlistRepo[(TempWishlistToGroupRepository)]
        end
        
        subgraph OfficialRepositories["Official Wishlist Repositories"]
            WishlistRepo[(WishlistToGroupRepository)]
            ViewpointRepo[(WishlistViewpointRepository)]
            SummaryRepo[(SummaryWishlistRepository)]
        end
        
        subgraph AnalyzerRepositories["Analyzer Repositories"]
            AnalyzerRepo[(AnalyzerRepository)]
        end
    end
    
    %% Database structure with clearer separation
    subgraph Databases["Database Layer"]
        subgraph gb_console["gb_console (Primary Business Database)"]
            TempWishlistDB[(temp_wishlist_to_groups)]
            WishlistDB[(wishlist_to_groups)]
            TempViewpointDB[(temp_wl_cat_vps)]
            ViewpointDB[(wl_cat_vps)]
            SummaryDB[(summary_wishlist_*)]
        end
        
        subgraph gb_analyzer["gb_analyzer (Analysis Database - Read Only)"]
            ProductsDB[(products)]
            ReviewsDB[(reviews)]
            RankingsDB[(rankings)]
            AnalysisDB[(analysis_data)]
        end
    end
    
    %% User flow with numbered steps
    Client --- Step1[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>1</span>
            <p style='margin-top: 8px'>Create Temporary Wishlist</p>
        </div>
    ]
    Step1 --> TempWishlistController
    
    Client --- Step2[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>2</span>
            <p style='margin-top: 8px'>Generate AI Viewpoints</p>
        </div>
    ]
    Step2 --> TempViewpointController
    
    Client --- Step3[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3</span>
            <p style='margin-top: 8px'>Convert to Official Wishlist</p>
        </div>
    ]
    Step3 --> TempWishlistController
    TempWishlistController -.-> WishlistController
    
    Client --- Step4[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4</span>
            <p style='margin-top: 8px'>Create Analysis Dataset</p>
        </div>
    ]
    Step4 --> WishlistController
    WishlistController -.-> AnalysisController
    
    Client --- Step5[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>5</span>
            <p style='margin-top: 8px'>Manage Subscription</p>
        </div>
    ]
    Step5 --> WishlistController
    WishlistController -.-> SubscriptionService
    
    %% Key controller-to-service connections
    TempWishlistController ==> TempWishlistService
    TempViewpointController ==> TempViewpointService
    WishlistController ==> WishlistService
    AnalysisController ==> DatasetService
    
    %% Key service integrations
    TempViewpointService --> OpenAIService
    OpenAIService --> OpenAI
    DatasetService --> AnalyzerAPIService
    AnalyzerAPIService --> TVPythonAPI
    SubscriptionService --> StripeAPI
    WishlistService --> PusherAPI
    
    %% Repository connections
    TempWishlistService --> TempWishlistRepo
    TempViewpointService --> TempWishlistRepo
    WishlistService --> WishlistRepo
    WishlistService --> ViewpointRepo
    WishlistService --> SummaryRepo
    DatasetService --> AnalyzerRepo
    
    %% Database connections
    TempWishlistRepo --> TempWishlistDB
    TempWishlistRepo --> TempViewpointDB
    WishlistRepo --> WishlistDB
    ViewpointRepo --> ViewpointDB
    SummaryRepo --> SummaryDB
    AnalyzerRepo --> ProductsDB
    AnalyzerRepo --> ReviewsDB
    AnalyzerRepo --> RankingsDB
    AnalyzerRepo --> AnalysisDB
    
    %% Style definitions
    classDef clientStyle fill:#e6f7ff,stroke:#1890ff,stroke-width:2px
    classDef apiStyle fill:#f6ffed,stroke:#52c41a,stroke-width:2px
    classDef serviceStyle fill:#fff7e6,stroke:#fa8c16,stroke-width:2px
    classDef repoStyle fill:#f9f0ff,stroke:#722ed1,stroke-width:2px
    classDef externalStyle fill:#fff1f0,stroke:#f5222d,stroke-width:2px
    classDef dbStyle fill:#fcffe6,stroke:#7cb305,stroke-width:2px
    
    class Client clientStyle
    class TempControllers,OfficialControllers apiStyle
    class TempServices,OfficialServices,IntegrationServices serviceStyle
    class TempRepositories,OfficialRepositories,AnalyzerRepositories repoStyle
    class ExternalServices externalStyle
    class gb_console,gb_analyzer dbStyle
    
    %% Transparent step nodes
    style Step1 fill:transparent,stroke:transparent,stroke-width:0px
    style Step2 fill:transparent,stroke:transparent,stroke-width:0px
    style Step3 fill:transparent,stroke:transparent,stroke-width:0px
    style Step4 fill:transparent,stroke:transparent,stroke-width:0px
    style Step5 fill:transparent,stroke:transparent,stroke-width:0px

Sequence Diagram

The following sequence diagram illustrates the key flows in the Wishlist System:

sequenceDiagram
    participant User
    participant TempWishlist as Temporary Wishlist
    participant OfficialWishlist as Official Wishlist
    participant OpenAI
    participant TVPythonAPI
    participant PusherService
    participant StripeAPI
    
    Note over User,StripeAPI: Complete Wishlist Workflow
    
    rect rgb(230, 240, 255)
    Note right of User: Temporary Wishlist Stage
    User->>TempWishlist: Create Temporary Wishlist
    User->>TempWishlist: Add Products/Categories/Search Queries
    User->>TempWishlist: Request AI Viewpoint Generation
    TempWishlist->>OpenAI: Generate Viewpoints
    OpenAI-->>TempWishlist: Return AI-Generated Content
    TempWishlist-->>User: Display Viewpoints
    end
    
    rect rgb(240, 255, 240)
    Note right of User: Conversion to Official Wishlist
    User->>TempWishlist: Convert to Official Wishlist
    TempWishlist->>StripeAPI: Validate Subscription
    StripeAPI-->>TempWishlist: Confirm Subscription Status
    TempWishlist->>OfficialWishlist: Transfer Data
    OfficialWishlist-->>User: Confirm Official Status
    end
    
    rect rgb(255, 245, 230)
    Note right of User: Analysis Integration
    User->>OfficialWishlist: Request Dataset Creation
    OfficialWishlist->>TVPythonAPI: Create Analysis Dataset
    TVPythonAPI-->>OfficialWishlist: Confirm Dataset Creation
    TVPythonAPI->>PusherService: Send Status Updates
    PusherService-->>User: Real-time Status Notifications
    TVPythonAPI->>OfficialWishlist: Complete Analysis
    OfficialWishlist-->>User: Display Analysis Results
    end

Detail Dataflow Dependency

The Wishlist System operates through a sophisticated data flow that integrates multiple external services and maintains data consistency across temporary and official states:

1. Temporary Wishlist Stage

• Purpose: Preparation and experimentation without affecting subscription quotas
• Data Flow: User Input → Temporary Tables → AI Enhancement → Validation
• Key Features:
  • CSV import/export for bulk operations
  • AI-powered viewpoint generation with OpenAI integration
  • Comprehensive input validation and sanitization
  • Real-time collaboration with group members
  • Temporary storage without quota consumption

2. Official Wishlist Stage

• Purpose: Active monitoring and analysis with subscription quota enforcement
• Data Flow: Temporary Data → Official Tables → Summary Tables → TV Python API → Analysis Results
• Key Features:
  • Dataset creation with TV Python API integration
  • Subscription validation and quota management
  • Ranking analysis and competitive intelligence
  • Real-time notifications via Pusher
  • Stripe integration for billing and subscription management

3. AI Integration Flow

• Trigger: User requests category detail or specific viewpoint generation
• Process: Category Name → OpenAI API → Generated Content → Database Storage → User Action Logging
• Features:
  • Configurable AI prompts for different use cases
  • Retry mechanisms for API failures
  • Transaction-safe storage of generated content
  • Caching of common responses for performance

4. Analysis Integration Flow

• Trigger: User creates analysis dataset from official wishlist
• Process: Wishlist Data → TV Python API → Dataset Creation → Status Tracking → Results Delivery
• Features:
  • Asynchronous processing with status tracking
  • Real-time notifications via Pusher
  • Error handling and recovery mechanisms
  • Comprehensive logging for troubleshooting

5. Subscription Management Flow

• Trigger: User subscription events (creation, update, cancellation)
• Process: Subscription Action → Stripe API → Quota Update → Feature Access Control
• Features:
  • Seamless integration with Stripe billing
  • Automatic quota enforcement
  • Subscription level feature access control
  • Billing history and management

Core Components

API Controllers

• TempWishlistToGroupController: Manages temporary wishlist CRUD operations
• WishlistToGroupController: Handles official wishlist management
• TempViewpointController: Controls AI viewpoint generation for temporary wishlists
• WishlistViewpointController: Manages viewpoints for official wishlists
• AnalysisController: Coordinates dataset creation and analysis operations

Services

• TempWishlistToGroupService: Implements business logic for temporary wishlists
• WishlistToGroupService: Handles official wishlist business operations
• TempViewpointService: Coordinates AI viewpoint generation for temporary items
• OpenAIService: Integrates with OpenAI API for content generation
• AnalyzerAPIService: Communicates with TV Python API for analysis
• SubscriptionService: Manages user subscriptions and quota
• DatasetService: Handles dataset creation and status tracking

Repositories

• TempWishlistToGroupRepository: Data access for temporary wishlists
• WishlistToGroupRepository: Data access for official wishlists
• WishlistViewpointRepository: Manages viewpoint data access
• SummaryWishlistRepository: Handles summary data operations
• AnalyzerRepository: Provides access to analysis data

Key Database Tables

• gb_console: temp_wishlist_to_groups, wishlist_to_groups, temp_wl_cat_vps, wl_cat_vps
• gb_analyzer: products, reviews, rankings, analysis_data

Timeline of Operations

timeline
    title Wishlist System Operations
    section User Operations
        Create Temporary Wishlist : Add Products : Add Categories : Add Search Queries
        Generate AI Viewpoints : OpenAI Integration : Edit & Review
        Convert to Official : Subscription Validation : Data Transfer
        Analyze Data : Dataset Creation : Results Analysis
    section System Operations
        Authentication : User Authentication : Group Permission Validation
        Data Validation : Input Sanitization : Duplicate Detection
        External API Integration : OpenAI : TV Python API : Stripe
        Notifications : Pusher Integration : Status Updates
    section Background Processing
        Dataset Processing : Analysis Status Tracking
        Subscription Management : Quota Enforcement : Billing Updates
        Data Cleanup : Temporary Data Expiration : Cache Management

Expected Outcomes

When the Wishlist System operates successfully, it delivers:

• Efficient Product Management: Users can organize and track products across multiple e-commerce platforms with real-time updates
• AI-Enhanced Insights: OpenAI-powered category descriptions and specific viewpoints provide intelligent analysis and recommendations
• Comprehensive Market Analysis: TV Python API integration enables deep market trend analysis and ranking insights
• Collaborative Workflow: Group-based wishlist management with real-time notifications and subscription quota sharing
• Scalable Data Processing: Efficient handling of large product datasets with CSV import/export capabilities
• Subscription Integration: Seamless quota management and billing through Stripe integration
• Real-time User Experience: Pusher-powered live updates for collaborative features and status changes

Error Handling

The system implements comprehensive error handling:

• Input Validation: Form Request classes with detailed validation rules
• Transaction Safety: Database transactions for data consistency
• API Error Handling: Structured error responses for all API endpoints
• Logging: Comprehensive logging of system operations and errors
• Retry Mechanisms: Automatic retry for transient external API failures
• User Notifications: Clear error messages for user feedback

Module List