​
Overview

The tag analysis system in IntelliQ automatically processes quiz content to generate relevant tags and categories, maintaining user statistics for both user-provided and AI-generated tags. This system works asynchronously using QStash to ensure smooth quiz submission experience.

​
Flow Diagram

​
Data Structure

The system maintains two levels of tag data:

  1. Quiz Level (in quizzes table):
{
  generatedTags: string[],      // AI-generated tags for this quiz
  generatedCategories: string[] // Broader categories for this quiz
}
  1. User Level (in userAnalysis table):
{
  userTags: { tag: string; count: number }[],           // User-provided tags
  generatedTags: { tag: string; count: number }[],      // AI-generated tags
  generatedCategories: { category: string; count: number }[] // AI-generated categories
}

  1. Quiz Submission When a user completes a quiz (singleplayer or multiplayer), the system:

    POST /api/v1/quiz-submissions/{type}

    The submission triggers a QStash job for tag analysis.

  2. Tag Analysis (Async)

    POST /api/v1/admin/tags/analyze

    The analysis job:

    • Generates tags and categories using AI
    • Updates the quiz record
    • Updates user statistics
    • Invalidates relevant caches

  3. Retrieve User Analysis

    GET /api/v1/user/analysis/tags

    Returns the user’s tag statistics and preferences.

  4. Get Top Categories

    GET /api/v1/user/analysis/top-categories

    Returns the user’s most frequent quiz categories.

​
Response Examples

{
  "success": true,
  "quizId": "557e75e4-d80e-4463-a282-f449190d4d1e",
  "tags": ["physics", "mechanics", "newton-laws"],
  "categories": ["Science", "Physics"]
}

​
Technical Implementation

  1. QStash Integration

    • Uses @upstash/qstash for reliable async processing
    • Configurable delay to batch process tags
    • Automatic retries on failure

  2. Cache Management

    • User cache version incremented after analysis
    • Ensures frontend receives updated statistics

  3. Database Schema

    -- Quiz tags
ALTER TABLE quizzes
ADD COLUMN generated_tags text[],
ADD COLUMN generated_categories text[];

-- User analysis
CREATE TABLE user_analysis (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id uuid REFERENCES users(id),
  user_tags jsonb[],
  generated_tags jsonb[],
  generated_categories jsonb[],
  created_at timestamptz DEFAULT now(),
  updated_at timestamptz NOT NULL
);

​
Error Handling

The system handles various error cases:

  • Failed AI tag generation
  • Database transaction failures
  • Invalid quiz references
  • Rate limiting
  • Cache invalidation issues

Each error is logged and retried through QStash’s built-in retry mechanism.

​
Security Considerations

  1. Tag analysis endpoint protected by admin token
  2. User analysis data access restricted to owner
  3. Rate limiting on analysis requests
  4. Sanitization of AI-generated tags
  5. Validation of user-provided tags

​
Benefits

  1. Asynchronous Processing

    • No delay in quiz submission
    • Better user experience
    • Reduced server load

  2. Rich Metadata

    • Improved quiz discovery
    • Better content organization
    • Personalized recommendations

  3. User Insights

    • Track user interests
    • Identify popular categories
    • Guide content creation

Written by Ricky Raveanu