01.wishlist-group-management

Wishlist Group Management

Description

The Wishlist Group Management feature provides comprehensive CRUD operations for official wishlist groups with advanced subscription validation, quota enforcement, and group-based access control. This system serves as the core foundation for production wishlist management, ensuring proper subscription billing integration and collaborative team access.

Unlike temporary wishlist management, this feature enforces strict subscription quotas, validates group membership, and maintains permanent records with full audit trails. The system integrates with subscription billing services to track usage and enforce limits based on subscription tiers.

Key capabilities include:

  • Creating official wishlist groups with subscription validation
  • Converting temporary wishlists to official status with data migration
  • Managing group-based access control and collaboration
  • Enforcing subscription quotas and usage tracking
  • Providing comprehensive listing with pagination and filtering
  • Maintaining audit trails and status management

Activity Diagram

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: linear
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TB
    %% Main components
    UserRequest[User Request]
    Database[(Database)]
    StripeAPI((Stripe API))
    
    subgraph Controllers
        WishlistController[WishlistToGroupController]
    end
    
    subgraph Services
        WishlistService(WishlistToGroupService)
        SubscriptionService(SubscriptionService)
        TempWishlistService(TempWishlistService)
    end
    
    subgraph Middleware
        AuthMiddleware{AuthMiddleware}
        GroupMiddleware{GroupMiddleware}
    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 & Authorization</p>
        </div>
    ]
    Step1 --> AuthMiddleware
    Step1 --> GroupMiddleware

    AuthMiddleware --- 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'>Subscription Validation & Quota Check</p>
        </div>
    ]
    Step2 --> WishlistController
    WishlistController --> SubscriptionService
    SubscriptionService -.-> StripeAPI

    SubscriptionService --- 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'>Data Processing & Validation</p>
        </div>
    ]
    Step3 --> WishlistService
    WishlistService -.-> TempWishlistService

    WishlistService --- 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'>Database Operations & Response</p>
        </div>
    ]
    Step4 --> Database

    %% Styling
    style UserRequest fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style Database fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style StripeAPI fill:#fcd9d9,stroke:#cc3333,stroke-width:2px
    style Controllers fill:#e6f3ff
    style Services fill:#f0f8e6
    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 & Authorization

  • Description: Validates user authentication and group membership for wishlist operations
  • Action: Authenticate user session, validate group membership, check access permissions
  • Input: User credentials, group membership data, requested operation type
  • Output: Authenticated user context with group access validation
  • Dependencies: User authentication service, group membership validation
  • External Services: Authentication provider, group management service

Step 2: Subscription Validation & Quota Enforcement

  • Description: Validates subscription status and enforces quota limits for wishlist creation
  • Action: Check subscription validity, calculate current usage, validate quota limits
  • Input: Subscription details, current usage data, requested resource counts
  • Output: Subscription validation result with quota availability
  • Dependencies: Subscription service, quota calculation service
  • External Services: Subscription billing system, usage tracking service

Step 3: Data Processing & Validation

  • Description: Processes and validates wishlist data from temporary conversion or manual input
  • Action: Validate data structure, convert temporary data, process manual input, check data integrity
  • Input: Temporary wishlist data or manual input, validation rules, data constraints
  • Output: Validated and structured wishlist data ready for creation
  • Dependencies: Data validation service, temporary wishlist service, summary table services
  • External Services: Data validation APIs, product validation services

Step 4: Wishlist Creation & Database Operations

  • Description: Creates official wishlist with transaction safety and relationship management
  • Action: Create wishlist record, establish relationships, update summary tables, manage schedules
  • Input: Validated wishlist data, group context, subscription binding
  • Output: Created wishlist with all relationships and metadata
  • Dependencies: Database transaction service, relationship management, schedule service
  • External Services: Database cluster, backup services, audit logging

Database Related Tables & Fields

Database: gb_console

erDiagram
    wishlist_to_groups {
        bigint id PK
        bigint group_id FK
        bigint created_by FK
        bigint subscription_id FK
        string name "Name of the wishlist"
        string slug "Slug of the wishlist"
        integer status "0: Inactive, 1: Active, 3: Canceled"
    }
    
    groups {
        bigint id PK
        string name
    }
    
    users {
        bigint id PK
        string name
    }
    
    subscriptions {
        bigint id PK
        string name
    }
    
    wishlist_to_groups }|--|| groups : "belongs to"
    wishlist_to_groups }|--|| users : "created by"
    wishlist_to_groups }|--|| subscriptions : "belongs to"

Case Documentation

Case 1: List Wishlist Groups

API: List Wishlist Groups

Sequence Diagram

sequenceDiagram
    participant Client
    participant Controller as WishlistToGroupController
    participant Service as WishlistToGroupService
    participant Repository as WishlistToGroupRepository
    participant Database
    
    Note over Client,Database: List Wishlist Groups Flow
    
    rect rgb(255, 255, 200)
    Note right of Client: Authentication Phase
    Client->>Controller: GET /api/v1/wishlist-to-group
    Controller->>Controller: Authenticate User
    Controller->>Controller: Validate Group Membership
    end
    
    rect rgb(200, 230, 255)
    Note right of Controller: Validation Phase
    Controller->>Service: list(params)
    Service->>Service: Validate Query Parameters
    Service->>Service: Apply Default Filters
    end
    
    rect rgb(200, 255, 255)
    Note right of Service: Business Logic Phase
    Service->>Repository: findWhere(conditions)
    Service->>Service: Apply Group Filter
    Service->>Service: Apply Status Filter
    Service->>Service: Apply Pagination
    end
    
    rect rgb(230, 200, 255)
    Note right of Repository: Database Phase
    Repository->>Database: SELECT with JOIN
    Database-->>Repository: Wishlist Records
    Repository-->>Service: Paginated Collection
    end
    
    rect rgb(200, 255, 200)
    Note right of Service: Success Response
    Service-->>Controller: LengthAwarePaginator
    Controller->>Controller: Transform to Resource
    Controller-->>Client: JSON Response with Pagination
    end

Steps

  1. Authentication: Validate user session and group membership
  2. Parameter Validation: Validate query parameters (page, per_page, status)
  3. Filter Application: Apply group-based filtering and status filtering
  4. Database Query: Execute paginated query with proper joins
  5. Response Formatting: Transform results to API resources with pagination metadata

Error Handling

  • 401 Unauthorized: Invalid or missing authentication
  • 403 Forbidden: User not member of any group
  • 400 Bad Request: Invalid query parameters
  • 500 Internal Server Error: Database or system errors

Case 2: Create Wishlist Group

API: Create Wishlist Group

Sequence Diagram

sequenceDiagram
    participant Client
    participant Controller as WishlistToGroupController
    participant Service as WishlistToGroupService
    participant SubService as SubscriptionService
    participant TempService as TempWishlistService
    participant Repository as WishlistToGroupRepository
    participant Database
    
    Note over Client,Database: Create Wishlist Group Flow
    
    rect rgb(255, 255, 200)
    Note right of Client: Authentication Phase
    Client->>Controller: POST /api/v1/wishlist-to-group
    Controller->>Controller: Authenticate User
    Controller->>Controller: Validate Group Membership
    end
    
    rect rgb(200, 230, 255)
    Note right of Controller: Validation Phase
    Controller->>Controller: Validate Request Data
    Controller->>Service: create(validatedData)
    Service->>Service: Prepare Data from Request
    end
    
    rect rgb(255, 230, 200)
    Note right of Service: Subscription Validation
    Service->>SubService: validateSubscription(group)
    SubService->>SubService: Check Subscription Status
    SubService->>SubService: Check Quota Limits
    SubService-->>Service: Validation Result
    end
    
    rect rgb(200, 255, 255)
    Note right of Service: Data Processing
    alt Temp Wishlist Conversion
        Service->>TempService: loadTempWishlist(id)
        TempService-->>Service: Temp Wishlist Data
        Service->>Service: convertTempToOfficial(data)
    else Manual Creation
        Service->>Service: processManualData(data)
    end
    end
    
    rect rgb(230, 200, 255)
    Note right of Service: Database Transaction
    Service->>Repository: beginTransaction()
    Service->>Repository: create(wishlistData)
    Repository->>Database: INSERT wishlist_to_groups
    Service->>Service: createRelatedData(products, categories, queries)
    Service->>SubService: updateUsageQuota(subscription)
    Service->>Repository: commit()
    end
    
    rect rgb(200, 255, 200)
    Note right of Repository: Success Response
    Repository-->>Service: Created Wishlist
    Service-->>Controller: Success Result
    Controller->>Controller: Transform to Resource
    Controller-->>Client: JSON Response with Created Data
    end
    
    rect rgb(255, 200, 200)
    Note right of Service: Error Handling
    alt Subscription Error
        SubService-->>Service: Subscription Invalid
        Service-->>Controller: Subscription Error
    else Quota Exceeded
        SubService-->>Service: Quota Exceeded
        Service-->>Controller: Quota Error
    else Database Error
        Repository-->>Service: Database Error
        Service->>Repository: rollback()
        Service-->>Controller: Creation Error
    end
    Controller-->>Client: Error Response
    end

Steps

  1. Authentication & Authorization: Validate user and group membership
  2. Request Validation: Validate input data structure and constraints
  3. Subscription Validation: Check subscription status and quota limits
  4. Data Preparation: Process temporary conversion or manual input data
  5. Quota Calculation: Calculate resource usage and validate against limits
  6. Database Transaction: Create wishlist and related data with transaction safety
  7. Usage Update: Update subscription usage counters
  8. Response Generation: Return created wishlist with proper formatting

Error Handling

  • 401 Unauthorized: Invalid authentication
  • 403 Forbidden: Group access denied
  • 400 Bad Request: Invalid input data or validation errors
  • 402 Payment Required: Subscription expired or invalid
  • 409 Conflict: Quota exceeded or resource limits
  • 500 Internal Server Error: Database or system errors

Case 3: Show Wishlist Group

API: Show Wishlist Group

Sequence Diagram

sequenceDiagram
    participant Client
    participant Controller as WishlistToGroupController
    participant Repository as WishlistToGroupRepository
    participant Database
    
    Note over Client,Database: Show Wishlist Group Flow
    
    rect rgb(255, 255, 200)
    Note right of Client: Authentication Phase
    Client->>Controller: GET /api/v1/wishlist-to-group/{slug}
    Controller->>Controller: Authenticate User
    Controller->>Controller: Validate Group Membership
    end
    
    rect rgb(200, 230, 255)
    Note right of Controller: Validation Phase
    Controller->>Repository: findBySlug(slug)
    Repository->>Database: SELECT by slug
    Database-->>Repository: Wishlist Record
    Repository-->>Controller: Wishlist or null
    end
    
    rect rgb(200, 255, 255)
    Note right of Controller: Authorization Check
    alt Wishlist Found
        Controller->>Controller: Check Group Access
        alt Access Granted
            Controller->>Controller: Load Related Data
        else Access Denied
            Controller-->>Client: 404 Not Found
        end
    else Wishlist Not Found
        Controller-->>Client: 404 Not Found
    end
    end
    
    rect rgb(200, 255, 200)
    Note right of Controller: Success Response
    Controller->>Controller: Transform to Resource
    Controller-->>Client: JSON Response with Wishlist Data
    end

Steps

  1. Authentication: Validate user session
  2. Wishlist Lookup: Find wishlist by slug
  3. Authorization: Verify user has access to the wishlist's group
  4. Data Loading: Load related data and relationships
  5. Response Formatting: Transform to API resource format

Error Handling

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