Quests Documentation

The quest system is built on a flexible architecture that allows for dynamic quest generation and management. Quests are primarily generated from the reward_configurations table, making them easily configurable without code changes.

System Components

Quest Lifecycle

1. Quest Generation - Quests are created from active reward configurations
2. User Discovery - Users can browse and search available quests
3. Progress Tracking - System tracks user progress toward quest completion
4. Completion Detection - System automatically detects when quest requirements are met
5. Claiming Process - Users manually claim completed quests to receive rewards
6. Reward Distribution - Points are awarded and activities are logged
7. Achievement Check - System checks for achievement unlocks

The quest system supports various types of challenges, each designed to encourage different aspects of platform engagement and trading activity.

Primary Quest Types

Quest Properties

• Repeatable - Some quests can be completed multiple times
• Time-Limited - Quests may have expiration dates for urgency
• Progressive - Some quests have multiple tiers or levels
• Conditional - Quests may have specific requirements or prerequisites

Quests are organized into distinct categories with unique visual styling and reward structures. Each category targets specific user behaviors and platform engagement patterns.

Category System

Category Assignment Logic

Quests are automatically categorized based on their name and key using intelligent pattern matching:

const getChallengeCategory = (challenge) => {
  const name = challenge.name?.toLowerCase() || '';
  const key = challenge.key?.toLowerCase() || '';
  
  if (name.includes('profit') || key.includes('profit_milestone')) {
    return 'profit_milestones';
  }
  
  if (name.includes('volume') || key.includes('volume_milestone')) {
    return 'volume_milestones';
  }
  
  if (name.includes('streak') || key.includes('streak')) {
    return 'streak';
  }
  
  if (name.includes('trading') || key.includes('trading')) {
    return 'trading';
  }
  
  return 'general';
};

The quest system provides comprehensive progress tracking for all user activities, allowing users to see their advancement toward quest completion in real-time.

Progress Components

• Current Progress - Number of completed requirements
• Required Progress - Total requirements needed for completion
• Progress Percentage - Visual progress bar representation
• Status Tracking - Active, completed, claimed states
• Time Tracking - Quest duration and expiration monitoring

Progress States

Progress Calculation

Quest progress is calculated based on the specific quest type and requirements:

// Example progress calculation for trading volume quest
$currentVolume = $user->getTradingVolume($startDate, $endDate);
$requiredVolume = $quest->required_count;
$progress = min(($currentVolume / $requiredVolume) * 100, 100);

// Update quest completion
$completion = QuestCompletion::updateOrCreate([
    'user_id' => $user->id,
    'quest_id' => $quest->id
], [
    'progress' => $currentVolume,
    'status' => $progress >= 100 ? 'completed' : 'active'
]);

The quest reward system provides multiple types of rewards for quest completion, with points being the primary currency and achievements providing additional recognition.

Reward Types

Reward Calculation

Quest rewards are calculated based on several factors:

• Base Points - Fixed reward amount for quest completion
• Difficulty Multiplier - Higher rewards for more challenging quests
• Streak Bonus - Additional points based on user's trading streak
• Tier Bonus - Multipliers based on user's current tier level
• First-Time Bonus - Extra rewards for first-time quest completions

Reward Distribution Process

// Quest claiming and reward distribution
public function claim(Request $request, Quest $quest)
{
    $user = auth()->user();
    
    // Find completed quest
    $completion = QuestCompletion::where('user_id', $user->id)
        ->where('quest_id', $quest->id)
        ->where('status', 'completed')
        ->where('claimed', false)
        ->first();
    
    if (!$completion) {
        return response()->json(['success' => false], 400);
    }
    
    DB::beginTransaction();
    
    try {
        // Mark as claimed
        $completion->update(['claimed' => true]);
        
        // Award points
        $user->increment('points_balance', $quest->reward_points);
        
        // Log activity
        $user->activities()->create([
            'activity_type' => 'quest_completed',
            'points_awarded' => $quest->reward_points,
            'description' => "Completed quest: {$quest->title}",
            'metadata' => json_encode([
                'quest_id' => $quest->id,
                'quest_title' => $quest->title,
            ]),
        ]);
        
        DB::commit();
        
        return response()->json([
            'success' => true,
            'points_awarded' => $quest->reward_points,
            'new_balance' => $user->points_balance,
        ]);
    } catch (\Exception $e) {
        DB::rollBack();
        return response()->json(['success' => false], 500);
    }
}

The quest claiming process ensures that users actively engage with completed quests and provides a clear mechanism for reward distribution.

Claiming Requirements

• Quest Completion - All quest requirements must be met
• Unclaimed Status - Quest must not have been previously claimed
• Active Status - Quest must still be active and not expired
• User Authentication - User must be logged in and authorized

Claiming Process Flow

1. Quest Completion Detection - System automatically detects when quest requirements are met
2. Status Update - Quest status changes from "active" to "completed"
3. User Notification - User is notified of quest completion
4. Claim Button Activation - Claim button becomes available in the UI
5. User Action - User clicks claim button to receive rewards
6. Reward Distribution - Points are awarded and activities are logged
7. Achievement Check - System checks for achievement unlocks
8. Status Finalization - Quest status changes to "claimed"

Claiming Interface

The quest claiming interface provides clear visual feedback and easy access to completed quests:

• Progress Indicators - Visual progress bars showing completion status
• Claim Buttons - Prominent buttons for claiming completed quests
• Reward Preview - Clear display of points to be awarded
• Status Badges - Color-coded badges showing quest status
• Completion Timestamps - When quests were completed and claimed

The quest system integrates with a comprehensive achievement system that provides additional recognition and rewards for user accomplishments.

Achievement Types

Achievement Unlock Process

// Achievement unlock checking
private function checkAchievementUnlocks($user)
{
    // Check for "Complete 5 Quests" achievement
    $completedQuests = QuestCompletion::where('user_id', $user->id)
        ->where('status', 'completed')
        ->count();
    
    $achievement = Achievement::where('unlock_criteria->type', 'quest_count')
        ->where('unlock_criteria->required_count', '<=', $completedQuests)
        ->whereDoesntHave('userAchievements', function ($query) use ($user) {
            $query->where('user_id', $user->id);
        })
        ->first();
    
    if ($achievement) {
        $user->achievements()->attach($achievement->id, [
            'unlocked_at' => now(),
        ]);
        
        // Award achievement points
        $user->increment('points_balance', $achievement->reward_points);
        
        return [
            'id' => $achievement->id,
            'name' => $achievement->name,
            'icon' => $achievement->icon,
            'reward_points' => $achievement->reward_points,
        ];
    }
    
    return null;
}

Achievement Display

Achievements are displayed with rich visual styling and categorization:

• Color-Coded Categories - Each achievement type has distinct colors
• Icon Representation - Visual icons for quick recognition
• Progress Tracking - Progress toward achievement completion
• Reward Information - Points and benefits for each achievement
• Unlock Timestamps - When achievements were earned

The quest system utilizes several database tables to manage quests, progress tracking, and reward distribution.

Primary Tables

Quest Model Structure

// Quest Model
class Quest extends Model
{
    protected $fillable = [
        'title',           // Quest name
        'description',     // Quest description
        'quest_type',      // Type of quest (trade, deposit, etc.)
        'reward_points',   // Points awarded for completion
        'required_count',  // Number of actions required
        'action_type',     // Type of action to track
        'is_repeatable',   // Can quest be completed multiple times
        'active',          // Is quest currently active
        'expires_at',      // Quest expiration date
    ];
    
    // Relationships
    public function completions(): HasMany
    {
        return $this->hasMany(QuestCompletion::class);
    }
}

Quest Completion Model Structure

// Quest Completion Model
class QuestCompletion extends Model
{
    protected $fillable = [
        'user_id',         // User who completed the quest
        'quest_id',        // Quest that was completed
        'progress',        // Current progress count
        'status',          // active, completed, claimed
        'claimed',         // Has the quest been claimed
        'completed_at',    // When quest was completed
    ];
    
    // Relationships
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
    
    public function quest(): BelongsTo
    {
        return $this->belongsTo(Quest::class);
    }
}

Data Relationships

• User → Quest Completions - One-to-many relationship for user quest progress
• Quest → Quest Completions - One-to-many relationship for quest progress tracking
• Quest Completions → Activities - Quest completions generate activity logs
• Quest Completions → Achievements - Quest completions can trigger achievement unlocks
• Reward Configurations → Quests - Dynamic quest generation from configurations

The quest system provides several API endpoints for quest management, progress tracking, and reward claiming.

Main Quest Endpoints

Quest List Response

{
  "quests": [
    {
      "id": 1,
      "title": "Complete 5 Trades",
      "description": "Execute 5 successful trades to earn bonus points",
      "type": "trade",
      "reward_points": 500,
      "required_progress": 5,
      "current_progress": 2,
      "status": "active",
      "claimed": false,
      "is_repeatable": false,
      "expires_at": "2024-12-31T23:59:59Z",
      "created_at": "2024-12-01T00:00:00Z"
    }
  ],
  "publicRewards": [
    {
      "id": 1,
      "name": "First Trade Bonus",
      "description": "Complete your first trade",
      "value": 100,
      "type": "integer",
      "unit": "points"
    }
  ]
}

Quest Claiming Response

{
  "success": true,
  "message": "Quest claimed successfully",
  "points_awarded": 500,
  "new_balance": 12500
}

Error Responses

// Quest not completed
{
  "success": false,
  "message": "Quest not completed or already claimed"
}

// Quest already claimed
{
  "success": false,
  "message": "Quest has already been claimed"
}

// Server error
{
  "success": false,
  "message": "Failed to claim quest: [error details]"
}

Performance Considerations

• Eager Loading - Quest completions are loaded with quests to prevent N+1 queries
• Filtering - Only active and non-expired quests are returned
• Caching - Public reward configurations can be cached for performance
• Pagination - Large quest lists can be paginated if needed