Documentation

AI JOB QUEUE FEATURES

AI Job Queue System - Feature Guide

🚀 How to Access the New Features

1. AI Jobs Dashboard

Location: Click "AI Jobs" in the navigation bar URL: http://localhost:3001/ai-jobs

This dashboard shows:

Active Jobs: Real-time tracking of all processing jobs
Job History: Complete history of all AI generation attempts
Usage Quota: Visual display of your monthly limits
Statistics: Success rate, cache hit rate, daily usage
Cost Tracking: See estimated and actual costs

2. Enhanced Course Generation

Location: When editing a course → Structure tab → "Generate Course with AI"

New features:

GPT-5 Support: Toggle to use GPT-5 with 128k token output
Job Priority: Set priority (Low, Normal, High, Urgent)
Real-time Progress: See job status and queue position
Quota Display: Check remaining quota before submitting
Cache Indicators: See when cached results are used

3. Job Management Features

#### Queue Management

Cancel Jobs: Cancel queued jobs before processing
Retry Failed Jobs: Retry failed generations with one click
Queue Position: See your position in the processing queue

#### Cost Controls

Monthly Quotas:

- Job limit (e.g., 100 jobs/month) - Token limit (e.g., 1M tokens/month) - Cost limit (e.g., $50/month)

Auto-reset: Quotas reset automatically each month
Warnings: Get alerts when approaching limits

4. Performance Features

#### Caching System

Automatic Caching: Identical requests return cached results
Cache Hit Indicator: Visual badge shows when cache is used
Cost Savings: Track money saved through caching
No Wait Time: Cached results return instantly

#### Background Processing

Non-blocking: Continue working while jobs process
Multi-worker: Multiple jobs process in parallel
Auto-retry: Failed jobs retry automatically (up to 3 times)

📊 Key Metrics Tracked

Job Metrics

Processing time (milliseconds)
Tokens used per request
Content blocks generated
Model used (GPT-4, GPT-5, DALL-E)

Cost Metrics

Estimated cost (before processing)
Actual cost (after completion)
Cost saved by caching
Monthly spending trends

Performance Metrics

Queue wait time
Processing duration
Success/failure rate
Cache hit rate

🔐 Security Features

User Isolation: Users only see their own jobs

Request Deduplication: SHA-256 hashing prevents duplicate processing

Cost Limits: Hard limits prevent runaway costs

Quota Enforcement: Cannot submit jobs beyond quota

Authentication Required: All job operations require login

🎯 Use Cases

For Course Creators

Generate comprehensive course structures with GPT-5

Create detailed section content

Generate DALL-E images for sections

Track all generation history

Retry failed generations

For Administrators

Monitor system-wide job processing

View analytics and usage trends

Manage user quotas

Clear cache when needed

Track cost across all users

🛠️ Technical Implementation

Backend Components

JobQueueService: Manages job lifecycle and caching
BackgroundJobProcessor: Processes jobs asynchronously
GraphQL API: Full job management via GraphQL
MySQL Tables:

- ai_jobs: Job queue and history - ai_job_cache: Cached results - user_ai_quotas: User limits - ai_job_analytics: System metrics

Frontend Components

useAIJobs Hook: React hook for job management
AIJobProgress: Real-time job status component
AIQuotaDisplay: Quota visualization
AIJobsDashboard: Complete monitoring interface

🚦 Job Status Flow

shell

QUEUED → PROCESSING → COMPLETED
                   ↘ CACHED (if from cache)
                   ↘ FAILED (with retry option)
                   ↘ CANCELLED (user action)

💡 Tips for Best Performance

Use Normal Priority: Unless urgent, use normal priority

Batch Similar Requests: System caches similar prompts

Monitor Quota: Check quota before large generations

Use GPT-4 Default: GPT-5 only when needed (more expensive)

Enable Images Selectively: DALL-E adds cost

🔄 Common Workflows

Generate Course Structure

Go to course edit page

Click "Generate Course with AI"

Configure settings (sections, level, audience)

Toggle GPT-5 if needed

Submit and watch progress

View results when complete

Monitor Active Jobs

Navigate to AI Jobs dashboard

View "Active" tab for current jobs

See queue position and progress

Cancel if needed

Check quota usage

Retry Failed Generation

Go to AI Jobs dashboard

Switch to "History" tab

Find failed job

Click retry button

Job re-enters queue

📈 Future Enhancements

WebSocket support for real-time updates
Batch job submission
Schedule jobs for later
Export job history
Custom model selection
Team quotas and sharing

🆘 Troubleshooting

Job Stuck in Queue

Check if quota exceeded
Verify backend is running
Check for system errors

Cache Not Working

Different parameters = different cache
Cache expires after 7 days
Admin can clear cache

Quota Exceeded

Wait for monthly reset
Contact admin for increase
Check cost optimization

Note: The system is designed for security and cost control. All AI processing happens server-side with proper authentication and quota management.