Viewpoint Analysis

Description

The Viewpoint Analysis feature provides comprehensive production viewpoint analysis capabilities within the official wishlist context, enabling users to view and manage category viewpoints and specific viewpoint details. This system operates on finalized viewpoint data that has been converted from temporary wishlists and is integrated with DS Analyzer for advanced analytics.

Key characteristics of the production viewpoint system:

• Read-only viewpoint analysis (no AI generation)
• Data converted from temporary wishlist viewpoints via ViewpointService
• Integration with DS Analyzer for trend analysis
• Ordinal number support for structured analysis
• Production tables: wl_cat_vps, wl_cat_vp_details, wl_spec_vps
• Real-time viewpoint data access and management
• Hierarchical viewpoint structure (Category → Detail → Specific)

Note: This documentation covers production wishlist viewpoints only. For AI-powered temporary viewpoint generation, see AI Viewpoint Generation.

Activity Diagram

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: linear
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TB
    %% Main components
    UserRequest[User Request]
    Database[(Database)]
    
    subgraph Controllers
        ViewpointController[WishlistViewpointController]
    end
    
    subgraph Repositories
        ViewpointRepo[[WishlistCategoryViewpointRepository]]
        WishlistRepo[[WishlistToGroupRepository]]
    end
    
    subgraph Middleware
        AuthMiddleware{AuthMiddleware}
    end
    
    UserRequest --- 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'>Authentication & Wishlist Validation</p>
        </div>
    ]
    Step1 --> AuthMiddleware
    AuthMiddleware --> ViewpointController

    ViewpointController --- 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'>Viewpoint Data Retrieval & Processing</p>
        </div>
    ]
    Step2 --> WishlistRepo
    WishlistRepo --> ViewpointRepo

    ViewpointRepo --- 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'>Relationship Loading & Data Processing</p>
        </div>
    ]
    Step3 --> Database

    Database --- 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'>Response Formatting & Resource Generation</p>
        </div>
    ]
    Step4 --> ViewpointController

    %% Styling
    style UserRequest fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style Database fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style Controllers fill:#e6f3ff
    style Repositories fill:#fff0f5
    style Middleware fill:#f5f0ff
    style Step1 fill:transparent,stroke:transparent,stroke-width:1px
    style Step2 fill:transparent,stroke:transparent,stroke-width:1px
    style Step3 fill:transparent,stroke:transparent,stroke-width:1px
    style Step4 fill:transparent,stroke:transparent,stroke-width:1px

Detail Dataflow Dependency

Step-by-Step Process

Step 1: Authentication & Wishlist Validation

• Description: Validates user authentication and wishlist access for viewpoint operations
• Action: Authenticate user session, validate wishlist slug, check wishlist existence
• Input: User credentials, wishlist slug
• Output: Validated user context with wishlist access confirmation
• Dependencies: User authentication service, wishlist repository
• External Services: Authentication provider

Step 2: Viewpoint Data Retrieval & Processing

• Description: Retrieves wishlist information and associated category viewpoint data
• Action: Find wishlist by slug, load category viewpoint by wishlist ID, validate data existence
• Input: Wishlist slug, wishlist ID
• Output: Wishlist data with associated category viewpoint information
• Dependencies: Wishlist repository, viewpoint repository
• External Services: Database cluster

Step 3: Relationship Loading & Data Processing

• Description: Loads related viewpoint details and specific viewpoints with proper relationships
• Action: Load viewpoint details, load specific viewpoints, process hierarchical relationships
• Input: Category viewpoint data, relationship parameters
• Output: Complete viewpoint hierarchy with details and specific viewpoints
• Dependencies: Eloquent relationship loading, data processing
• External Services: Database relationship queries

Step 4: Response Formatting & Resource Generation

• Description: Formats viewpoint data for API response with proper resource transformation
• Action: Transform data to API resource format, apply proper structure, generate response
• Input: Complete viewpoint data, resource transformation requirements
• Output: Formatted API response with viewpoint resources
• Dependencies: Resource transformation, response formatting
• External Services: API response services

Database Related Tables & Fields

Database: gb_console

erDiagram
    wl_cat_vps {
        bigint id PK
        bigint group_id "Group ownership for access control"
        bigint wishlist_to_group_id FK "Reference to production wishlist"
        string name "Category name from conversion process"
        timestamp created_at
        timestamp updated_at
    }
    
    wl_cat_vp_details {
        bigint id PK
        bigint wl_cat_vp_id FK "Reference to wl_cat_vps"
        text detail "Category detail from temp conversion"
        timestamp created_at
        timestamp updated_at
    }
    
    wl_spec_vps {
        bigint id PK
        bigint wl_cat_vp_detail_id FK "Reference to wl_cat_vp_details"
        integer viewpoint_ordinal_number "Analysis ordering number (Added 2025-07-30)"
        string name "Specific viewpoint name from conversion"
        text description "Specific viewpoint description"
        timestamp created_at
        timestamp updated_at
    }
    
    wishlist_to_groups {
        bigint id PK
        string name "Production wishlist name"
        string slug "Unique slug for API access"
        integer status "0: Inactive, 1: Active, 3: Canceled"
        timestamp created_at
        timestamp updated_at
    }

    wl_cat_vps ||--o{ wl_cat_vp_details : has
    wl_cat_vp_details ||--o{ wl_spec_vps : has
    wl_cat_vps }|--|| wishlist_to_groups : belongs_to

Case Documentation

Case 1: Category Viewpoint Analysis

API: Category Viewpoints

Sequence Diagram

sequenceDiagram
    participant Client
    participant Controller as WishlistViewpointController
    participant WishlistRepo as WishlistToGroupRepository
    participant ViewpointRepo as WishlistCategoryViewpointRepository
    participant Database
    
    Note over Client,Database: Category Viewpoint Analysis Flow
    
    rect rgb(255, 255, 200)
    Note right of Client: Authentication Phase
    Client->>Controller: GET /api/v1/wishlist-to-group/{slug}/category-viewpoint
    Controller->>Controller: Authenticate User
    end
    
    rect rgb(200, 230, 255)
    Note right of Controller: Wishlist Validation
    Controller->>WishlistRepo: findBySlug(slug)
    WishlistRepo->>Database: SELECT from wishlist_to_groups
    Database-->>WishlistRepo: Wishlist Record
    WishlistRepo-->>Controller: Wishlist or null
    end
    
    rect rgb(200, 255, 255)
    Note right of Controller: Viewpoint Retrieval
    alt Wishlist Found
        Controller->>ViewpointRepo: getByWishlistToGroupId(wishlistId)
        ViewpointRepo->>Database: SELECT from wl_cat_vps
        Database-->>ViewpointRepo: Category Viewpoint
        ViewpointRepo-->>Controller: Viewpoint Data
    else Wishlist Not Found
        Controller-->>Client: Error Response
    end
    end
    
    rect rgb(200, 255, 200)
    Note right of Controller: Success Response
    alt Viewpoint Found
        Controller->>Controller: Transform to Resource
        Controller-->>Client: JSON Response with Viewpoint
    else Viewpoint Not Found
        Controller-->>Client: Success Response with Message
    end
    end

Steps

1. Authentication: Validate user session
2. Wishlist Validation: Find wishlist by slug and validate existence
3. Viewpoint Retrieval: Load category viewpoint data for the wishlist
4. Response Generation: Transform to resource and return formatted response

Error Handling

• 401 Unauthorized: Invalid authentication
• 404 Not Found: Wishlist not found
• 500 Internal Server Error: Database or system errors

Case 2: Detailed Viewpoint Analysis

API: Category Viewpoint Detail & Specific Viewpoints

Sequence Diagram

sequenceDiagram
    participant Client
    participant Controller as WishlistViewpointController
    participant WishlistRepo as WishlistToGroupRepository
    participant ViewpointRepo as WishlistCategoryViewpointRepository
    participant Database
    
    Note over Client,Database: Detailed Viewpoint Analysis Flow
    
    rect rgb(255, 255, 200)
    Note right of Client: Authentication Phase
    Client->>Controller: GET /api/v1/wishlist-to-group/{slug}/category-viewpoint-detail
    Controller->>Controller: Authenticate User
    end
    
    rect rgb(200, 230, 255)
    Note right of Controller: Wishlist Validation
    Controller->>WishlistRepo: findBySlug(slug)
    WishlistRepo->>Database: SELECT from wishlist_to_groups
    Database-->>WishlistRepo: Wishlist Record
    WishlistRepo-->>Controller: Wishlist or null
    end
    
    rect rgb(200, 255, 255)
    Note right of Controller: Viewpoint Retrieval
    alt Wishlist Found
        Controller->>ViewpointRepo: getByWishlistToGroupId(wishlistId)
        ViewpointRepo->>Database: SELECT from wl_cat_vps
        Database-->>ViewpointRepo: Category Viewpoint
        ViewpointRepo-->>Controller: Viewpoint Data
    else Wishlist Not Found
        Controller-->>Client: Error Response
    end
    end
    
    rect rgb(230, 200, 255)
    Note right of Controller: Relationship Loading
    alt Viewpoint Found
        Controller->>Controller: Load Relationships
        Controller->>Database: Load wl_cat_vp_details
        Controller->>Database: Load wl_spec_vps
        Database-->>Controller: Complete Viewpoint Hierarchy
    else Viewpoint Not Found
        Controller-->>Client: Success Response with Message
    end
    end
    
    rect rgb(200, 255, 200)
    Note right of Controller: Success Response
    Controller->>Controller: Transform to Detailed Resource
    Controller-->>Client: JSON Response with Complete Details
    end

Steps

1. Authentication: Validate user session
2. Wishlist Validation: Find wishlist by slug and validate existence
3. Viewpoint Retrieval: Load category viewpoint data for the wishlist
4. Relationship Loading: Load viewpoint details and specific viewpoints
5. Response Generation: Transform to detailed resource and return formatted response

Error Handling

• 401 Unauthorized: Invalid authentication
• 404 Not Found: Wishlist not found
• 500 Internal Server Error: Database or system errors

Case 3: DS Analyzer Data Push (During Wishlist Submission)

Description

When wishlists are submitted/converted to production, viewpoint data is automatically pushed to DS Analyzer database for advanced analytics and trend analysis.

Sequence Diagram

sequenceDiagram
    participant ConversionProcess as Wishlist Conversion
    participant ViewpointService
    participant ProdDB as Production Database
    participant DSAnalyzer as DS Analyzer Database
    participant TempWishlist as Temp Wishlist Data
    
    Note over ConversionProcess,DSAnalyzer: Wishlist Submission with DS Analyzer Push
    
    ConversionProcess->>ViewpointService: create(viewpointData, group, wishlistToGroup, tempWishlistToGroup)
    
    rect rgb(200, 255, 255)
    Note right of ViewpointService: Production Viewpoint Creation
    ViewpointService->>ProdDB: CREATE wl_cat_vps
    ViewpointService->>ProdDB: CREATE wl_cat_vp_details  
    ViewpointService->>ProdDB: CREATE wl_spec_vps (with ordinal numbers)
    end
    
    rect rgb(255, 230, 200)
    Note right of ViewpointService: DS Analyzer Push - Category Data
    ViewpointService->>ViewpointService: createViewpointCategory(wishlistCategoryViewpoint, tempWishlistToGroup)
    
    alt Has temp wishlist with short_detail
        ViewpointService->>TempWishlist: Extract short_detail from temp_wl_cat_vp_details
        TempWishlist-->>ViewpointService: short_detail value
    else No temp data or missing short_detail
        ViewpointService->>ViewpointService: generateCategoryDetailUsingChatGPT(categoryName)
        ViewpointService-->>ViewpointService: Generated short_detail via OpenAI
    end
    
    ViewpointService->>DSAnalyzer: INSERT INTO viewpoint_categories
    Note over ViewpointService,DSAnalyzer: {viewpoint_category_id, name, short_detail}
    end
    
    rect rgb(230, 200, 255)
    Note right of ViewpointService: DS Analyzer Push - Specific Viewpoints
    ViewpointService->>ViewpointService: createSpecificViewpoint(wishlistCategoryViewpoint, wishlistCategoryViewpointDetail)
    
    loop For each wl_spec_vps record
        ViewpointService->>ViewpointService: Map to analyzer format with ordinal number
    end
    
    ViewpointService->>DSAnalyzer: BATCH INSERT INTO specific_viewpoints
    Note over ViewpointService,DSAnalyzer: {viewpoint_ordinal_number, spvp_name, spvp_description, viewpoint_category_id}
    end
    
    ViewpointService-->>ConversionProcess: Production viewpoints + DS push completed

Steps

Step 1: Production Viewpoint Creation

• Description: Create production viewpoint records in main database
• Action: Insert into wl_cat_vps, wl_cat_vp_details, wl_spec_vps tables
• Key Feature: Assign viewpoint_ordinal_number (1, 2, 3...) for analysis ordering

Step 2: Category Data Push to DS Analyzer

• Description: Push category information with short detail to analyzer database
• Action: Call ViewpointService::createViewpointCategory()
• Data Source Priority:
  1. Primary: Extract short_detail from temp wishlist data if available
  2. Fallback: Generate short_detail via OpenAI if temp data missing
• Target Table: analyzer.viewpoint_categories

Step 3: Specific Viewpoints Push to DS Analyzer

• Description: Push all specific viewpoints with ordinal numbers for structured analysis
• Action: Call ViewpointService::createSpecificViewpoint()
• Data Mapping: Production viewpoints → Analyzer format with ordinal sequences
• Target Table: analyzer.specific_viewpoints

Step 4: Data Validation & Integrity

• Description: Ensure data consistency between production and analyzer databases
• Validation: Verify all viewpoints have ordinal numbers and proper relationships
• Error Handling: Transaction rollback if DS push fails

ViewpointService Implementation Details

// Category push with short_detail fallback
private function createViewpointCategory(
    WishlistCategoryViewpoint $wishlistCategoryViewpoint,
    ?TempWishlistToGroup $tempWishlistToGroup = null
): void {
    $tempWishlistCategoryViewpointDetail = $tempWishlistToGroup?->tempWishlistCategoryViewpoint?->tempWishlistCategoryViewpointDetail;
    $categoryName = $wishlistCategoryViewpoint->name;

    if ($tempWishlistCategoryViewpointDetail) {
        // Use existing short_detail from temp data
        $categoryShortDetail = $tempWishlistCategoryViewpointDetail->short_detail;
    } else {
        // Generate new short_detail via OpenAI
        $categoryShortDetail = $this->tempViewpointService->generateCategoryDetailUsingChatGPT($categoryName)->short_detail;
    }

    // Push to DS Analyzer
    $this->viewpointCategoryRepository->create([
        'viewpoint_category_id' => $wishlistCategoryViewpoint->id,
        'name' => $categoryName,
        'short_detail' => $categoryShortDetail,
    ]);
}

// Specific viewpoints push with ordinal mapping
private function createSpecificViewpoint(
    WishlistCategoryViewpoint $wishlistCategoryViewpoint,
    WishlistCategoryViewpointDetail $wishlistCategoryViewpointDetail
): void {
    $specificViewpointData = [];

    foreach ($wishlistCategoryViewpointDetail->wishlistSpecificViewpoints as $viewpoint) {
        $specificViewpointData[] = [
            'viewpoint_ordinal_number' => $viewpoint->viewpoint_ordinal_number, // Maintains order
            'spvp_name' => $viewpoint->name,
            'spvp_description' => $viewpoint->description,
            'viewpoint_category_id' => $wishlistCategoryViewpoint->id,
        ];
    }

    if (!empty($specificViewpointData)) {
        $this->specificViewpointRepository->insert($specificViewpointData);
    }
}

Error Handling

• Database Transaction: Full rollback if DS push fails
• OpenAI Fallback: Handles cases where temp data lacks short_detail
• Batch Insert: Efficient handling of multiple specific viewpoints
• Data Validation: Ensures all required fields are present

DS Analyzer Target Tables

Database: gb_analyzer

erDiagram
    viewpoint_categories {
        bigint id PK
        bigint viewpoint_category_id "References wl_cat_vps.id from main DB"
        string name "Category name for analysis dashboards"
        text short_detail "Brief category summary for quick insights"
        timestamp created_at
        timestamp updated_at
    }
    
    specific_viewpoints {
        bigint id PK
        integer viewpoint_ordinal_number "Analysis ordering (1, 2, 3, etc.)"
        string spvp_name "Specific viewpoint name for analysis"
        text spvp_description "Specific viewpoint description"
        bigint viewpoint_category_id "References wl_cat_vps.id from main DB"
        timestamp created_at
        timestamp updated_at
    }

    viewpoint_categories ||--o{ specific_viewpoints : has

Data Flow Summary

flowchart LR
    TempData[Temp Wishlist Data<br/>temp_wl_cat_vp_details.short_detail] 
    ProdData[Production Data<br/>wl_cat_vps, wl_cat_vp_details, wl_spec_vps]
    DSData[DS Analyzer Data<br/>viewpoint_categories, specific_viewpoints]
    OpenAI((OpenAI<br/>Fallback Generation))
    
    TempData -->|Conversion| ProdData
    TempData -.->|Extract short_detail| DSData
    ProdData -->|Push with ordinals| DSData
    OpenAI -.->|Generate if missing| DSData
    
    style TempData fill:#e1f5fe
    style ProdData fill:#f3e5f5
    style DSData fill:#fff3e0
    style OpenAI fill:#fce4ec

Production Viewpoint Creation & DS Analyzer Integration

Data Source: Conversion from Temporary Viewpoints

Production viewpoints are not generated directly but are created through conversion from temporary wishlist viewpoints via the ViewpointService::create() method during the wishlist conversion process.

Key Differences from Temporary Viewpoints

Additional Notes

Data Flow Characteristics

• Read-Only Nature: Production viewpoints cannot be modified through API endpoints
• Conversion Dependency: All data originates from temporary viewpoint conversion
• DS Integration: Automatic push to analyzer for advanced analytics
• Ordinal Sequencing: Viewpoints maintain order for structured analysis

Performance Considerations

• Optimized for Reads: Database indexes optimized for query performance
• Relationship Loading: Efficient eager loading of viewpoint hierarchies
• Caching Strategy: Consider implementing caching for frequently accessed viewpoints
• DS Sync: Real-time synchronization with analyzer database