Demo System

The PadawanForge demo provides an anonymous, barrier-free introduction to cognitive training through rapid true/false statement judgment. Players experience the complete game mechanics without registration requirements while maintaining the option to save progress and convert to full accounts.

Overview

Purpose

The demo system showcases the core PadawanForge experience through:

  • Anonymous Play: No login required, instant access to gameplay
  • Complete Experience: Full 7-minute session with 40 AI-generated statements
  • Guest Sessions: Temporary identity with progress tracking and analytics
  • Virtual Tutors: AI-powered guidance with distinct personalities
  • Progress Tracking: XP, accuracy, streak analytics, and achievements
  • Account Conversion: Seamless upgrade to full registered account

Target Audience

  • New Players: First-time users exploring cognitive training capabilities
  • Casual Players: Users wanting quick sessions without account commitment
  • Evaluators: Educators, researchers, or decision-makers assessing the platform
  • Mobile Users: Players on devices where account creation may be cumbersome

Architecture Overview

Guest Session System

Guest sessions provide temporary identity and progress tracking without account creation, using a hybrid storage approach for optimal performance and persistence.

Session Structure

interface DemoSession {
  id: string;                    // Session UUID
  sessionToken: string;          // Secure authentication token
  guestUsername: string;         // "Guest_ABC123" format
  guestAvatar?: string;          // Optional avatar
  
  // Analytics data
  ipAddress?: string;
  userAgent?: string;
  referrer?: string;
  utmSource?: string;
  utmMedium?: string;
  utmCampaign?: string;
  
  // Session state (stored in session_data JSON)
  sessionData: {
    totalSessions: number;       // Sessions completed
    totalXP: number;             // Cumulative experience
    averageAccuracy: number;     // Running accuracy percentage
    bestStreak: number;          // Longest hot streak achieved
    sessionHistory: SessionSummary[]; // Recent sessions
    currentGame?: GameState;     // Active game state
    achievements: Achievement[]; // Unlocked achievements
  };
  
  // Activity tracking (stored in activity_data JSON)
  activityData: {
    pageViews: number;
    featuresUsed: string[];
    totalInteractions: number;
    engagementScore: number;
  };
  
  // Conversion tracking (stored in conversion_data JSON)
  conversionData: {
    testVariant?: string;        // A/B test assignment
    conversionTriggers: string[]; // Events that might trigger conversion
    timeToConversion?: number;    // If converted, time taken
  };
  
  expiresAt: Date;              // 24-hour expiration
  lastActivity: Date;
  isConverted: boolean;
  convertedToPlayerUuid?: string;
  createdAt: Date;
  updatedAt: Date;
}

Storage Strategy

  • Database Storage: Primary storage in Cloudflare D1 with JSON fields for flexibility
  • Session Token: Secure token for session identification and authentication
  • KV Backup: Optional Cloudflare KV storage for high-performance session lookup
  • Browser Cache: Client-side localStorage for offline capability and quick access
  • Expiration: 24-hour automatic cleanup with grace period handling

Session Lifecycle

  1. Creation: Auto-generate guest identity on demo entry
  2. Persistence: Dual storage (localStorage + KV) for maximum reliability
  3. Restoration: Cross-device session recovery via secure token
  4. Expiration: Automatic cleanup after 24 hours of inactivity
  5. Conversion: Optional upgrade to full account preserving all progress

Core Gameplay

Session Structure

  • Duration: Precisely 420 seconds (7 minutes) for optimal cognitive load
  • Statements: 40 targeted true/false questions generated by AI
  • Pacing: ~10.5 seconds average per statement with adaptive timing
  • Difficulty: Adaptive based on real-time performance metrics
  • Topic Mix: Balanced selection across Basic/Intermediate/Advanced levels

Game Flow

  1. Initialization: Auto-generate guest session and prepare AI question generation
  2. Loading Phase: AI generates 40 topic-specific statements (30-60 seconds)
  3. Topic Selection: Choose focus areas (History, Science, etc.) or mixed topics
  4. Tutor Assignment: AI persona automatically matches selected topics
  5. Statement Loop: 40 rapid-fire true/false challenges with real-time feedback
  6. Session Summary: Complete performance analysis with XP rewards and achievements

Player Actions

  • True: Mark statement as correct (+10 points if right, -5 if wrong)
  • False: Mark statement as incorrect (+10 points if right, -5 if wrong)
  • Skip: Pass on statement (no points, breaks streak)
  • Pause: Temporary halt (limited usage, time continues)

Database Architecture

Tables

demo_sessions

Primary table storing demo session metadata and tracking data:

CREATE TABLE demo_sessions (
    id TEXT PRIMARY KEY,                   -- Session UUID
    session_token TEXT UNIQUE NOT NULL,   -- Secure session token for authentication
    guest_username TEXT NOT NULL,         -- Generated guest username (Guest_ABC123)
    guest_avatar TEXT,                    -- Optional guest avatar
    ip_address TEXT,                      -- Client IP for analytics
    user_agent TEXT,                      -- Browser/client info
    referrer TEXT,                        -- Traffic source
    utm_source TEXT,                      -- Marketing attribution
    utm_medium TEXT,                      -- Marketing medium
    utm_campaign TEXT,                    -- Campaign tracking
    session_data TEXT,                    -- JSON: demo progress, game state, and session details
    activity_data TEXT,                   -- JSON: user interactions and behavior tracking
    conversion_data TEXT,                 -- JSON: A/B testing and conversion metrics
    expires_at TIMESTAMP NOT NULL,        -- 24-hour session expiration
    last_activity TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    is_converted BOOLEAN DEFAULT FALSE,   -- Account conversion status
    converted_to_player_uuid TEXT,        -- UUID if converted to full account
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

demo_session_activities

Detailed activity tracking for analytics and optimization:

CREATE TABLE demo_session_activities (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    demo_session_id TEXT NOT NULL,
    activity_type TEXT NOT NULL,          -- 'page_view', 'feature_use', 'interaction', 'game_action'
    activity_data TEXT,                   -- JSON: specific activity details and context
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (demo_session_id) REFERENCES demo_sessions(id) ON DELETE CASCADE
);

demo_session_metrics

Performance and conversion metrics for monitoring:

CREATE TABLE demo_session_metrics (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    demo_session_id TEXT NOT NULL,
    metric_name TEXT NOT NULL,            -- 'response_time', 'accuracy', 'engagement_score'
    metric_value REAL NOT NULL,           -- Numeric metric value
    metric_unit TEXT,                     -- 'ms', 'percentage', 'count', etc.
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (demo_session_id) REFERENCES demo_sessions(id) ON DELETE CASCADE
);

AI Statement Generation

Generation Process

  1. Topic Selection: System selects focus area (History, Science, etc.)
  2. Difficulty Distribution: Balanced mix across Basic (50%), Intermediate (30%), Advanced (20%)
  3. AI Generation: Cloudflare Workers AI generates 40 unique statements
  4. Validation: Automated checks for quality, clarity, and factual accuracy
  5. Caching: Generated statements cached for 1 hour to prevent regeneration

Statement Quality Guidelines

  • Factually Accurate: All statements must be objectively verifiable
  • Clear Language: Unambiguous wording suitable for rapid judgment
  • Appropriate Difficulty: Matched to target cognitive load
  • Topic Relevance: Directly related to selected focus area
  • Deterministic: Clear true/false answers without gray areas

AI Prompt Engineering

// Example AI generation prompt for History
const prompt = `Generate 40 true/false statements about History topics.
Requirements:
- Mix of Basic (20 statements), Intermediate (12 statements), and Advanced (8 statements)
- Objectively verifiable facts only
- Clear, unambiguous language
- Suitable for rapid 10-second judgment
- Cover diverse historical periods and regions
- Format: JSON array with statement, answer, difficulty, topic`;

Scoring & Achievement System

Scoring Mechanics

  • Correct Answer: +10 base points
  • Incorrect Answer: -5 points (encourages thoughtful responses)
  • Hot Streak Multipliers:
    • 3+ correct: 1.2× multiplier
    • 5+ correct: 1.5× multiplier
    • 8+ correct: 2.0× multiplier
  • Cold Streak Penalties: 3+ incorrect reduces multiplier to 0.8×
  • Skip Penalty: No points earned, breaks any active streak

Achievement System

interface Achievement {
  id: string;
  name: string;
  description: string;
  condition: (session: DemoSession) => boolean;
  xpBonus: number;
  rarity: 'common' | 'rare' | 'epic' | 'legendary';
}

// Example achievements
const achievements: Achievement[] = [
  {
    id: 'first_game',
    name: 'First Steps',
    description: 'Complete your first demo session',
    condition: (session) => session.totalQuestions >= 40,
    xpBonus: 50,
    rarity: 'common'
  },
  {
    id: 'perfectionist',
    name: 'Perfectionist',
    description: 'Achieve 100% accuracy in a session',
    condition: (session) => session.accuracy === 100,
    xpBonus: 200,
    rarity: 'legendary'
  },
  {
    id: 'speed_demon',
    name: 'Speed Demon',
    description: 'Average under 5 seconds per question',
    condition: (session) => session.averageResponseTime < 5000,
    xpBonus: 100,
    rarity: 'rare'
  }
];

Account Conversion System

Conversion Process

  1. Demo Completion: Player completes at least one full demo session
  2. Conversion Trigger: Player clicks “Save Progress & Sign Up” button
  3. OAuth Flow: Standard authentication flow with provider selection
  4. Progress Migration: All demo session data transferred to new account
  5. Database Update: demo_sessions marked as converted with player UUID
  6. Seamless Transition: Player continues with full account privileges

Data Preservation

  • Session History: All completed demo sessions preserved
  • Achievement Progress: Unlocked achievements carry over
  • Performance Metrics: Accuracy and streak records maintained
  • XP Balance: Earned experience points transferred
  • Analytics: Historical performance data integrated

Conversion Benefits

  • Progress Retention: No loss of demo achievements or statistics
  • Enhanced Features: Access to custom topics, advanced analytics
  • Social Features: Leaderboards, friend comparisons, community challenges
  • Persistence: Cross-device synchronization and cloud saves
  • Premium Content: Access to advanced difficulty levels and specialized topics

API Endpoints

Session Management

// Create new demo session
POST /api/demo/sessions
Body: { referrer?: string, utmSource?: string, utmMedium?: string, utmCampaign?: string }
Response: { 
  sessionId: string, 
  sessionToken: string,
  guestUsername: string,
  expiresAt: string
}

// Get session state
GET /api/demo/sessions/[sessionId]
Headers: { Authorization: `Bearer ${sessionToken}` }
Response: DemoSession

// Update session activity
PUT /api/demo/sessions/[sessionId]/activity
Headers: { Authorization: `Bearer ${sessionToken}` }
Body: { 
  activityType: string,
  activityData: object,
  metrics?: { name: string, value: number, unit?: string }[]
}

// Update session data
PUT /api/demo/sessions/[sessionId]
Headers: { Authorization: `Bearer ${sessionToken}` }
Body: { 
  sessionData?: object,
  activityData?: object,
  conversionData?: object
}

// Extend session expiration
POST /api/demo/sessions/[sessionId]/extend
Headers: { Authorization: `Bearer ${sessionToken}` }
Response: { expiresAt: string }

Analytics & Metrics

// Get demo analytics (admin only)
GET /api/demo/analytics
Query: { 
  startDate?: string,
  endDate?: string,
  utmSource?: string,
  activityType?: string
}
Response: {
  totalSessions: number,
  activeSessions: number,
  conversionRate: number,
  averageSessionDuration: number,
  topActivities: Activity[],
  conversionFunnelStats: FunnelStat[],
  dailyStats: DailyStat[]
}

// Track conversion event
POST /api/demo/sessions/[sessionId]/track-conversion
Headers: { Authorization: `Bearer ${sessionToken}` }
Body: { trigger: string, context?: object }
Response: { tracked: boolean }

Account Conversion

// Convert demo session to full account
POST /api/demo/sessions/[sessionId]/convert
Headers: { Authorization: `Bearer ${sessionToken}` }
Body: { playerUuid: string }
Response: { 
  success: boolean, 
  migratedData: {
    sessionData: object,
    activityCount: number,
    metricsCount: number
  }
}

// Check conversion eligibility
GET /api/demo/sessions/[sessionId]/conversion-status
Headers: { Authorization: `Bearer ${sessionToken}` }
Response: { 
  eligible: boolean,
  requirements: string[],
  benefits: string[]
}

Performance Optimizations

Session Data Management

  • JSON Storage: Flexible JSON fields allow efficient storage of complex session state
  • Indexed Queries: Strategic indexes on session tokens, expiration, and conversion status
  • Automatic Cleanup: Expired sessions automatically identified via view for cleanup
  • Batch Updates: Activity and metrics data batched for efficient database writes

Analytics Optimization

  • Separate Tables: Activity and metrics stored in dedicated tables for efficient querying
  • Time-Based Indexing: Timestamp indexes enable fast time-range analytics queries
  • Aggregated Views: Pre-computed analytics reduce real-time query overhead
  • Efficient Joins: Foreign key relationships optimize cross-table analytics

Caching Strategy

  • Session Token Cache: High-frequency session lookups cached in KV store
  • Browser Persistence: Client-side localStorage reduces server load
  • Analytics Cache: Dashboard metrics cached to reduce database queries
  • Lazy Loading: Session data loaded incrementally based on user interaction

Testing & Validation

Automated Testing

# Run demo system tests
bun run test -- --grep "demo"

# Test session management
bun run test -- src/test/demo-sessions.test.ts

# Test analytics tracking
bun run test -- src/test/demo-analytics.test.ts

# Test conversion flow
bun run test -- src/test/demo-conversion.test.ts

# Test database migrations
bun run test -- src/test/demo-migrations.test.ts

Manual Testing Flow

  1. Create Session: POST to /api/demo/sessions to create new demo session
  2. Track Activity: Use activity tracking endpoints to log user interactions
  3. Test Metrics: Verify metrics are properly stored and retrievable
  4. Session Persistence: Test session token authentication and data retrieval
  5. Expiration Handling: Verify 24-hour expiration and cleanup mechanisms
  6. Conversion Flow: Test full account conversion and data migration
  7. Analytics Dashboard: Verify admin analytics display correctly

Quality Assurance

  • Database Integrity: Verify foreign key constraints and data consistency
  • Security Testing: Validate session token security and authorization
  • Performance Testing: Monitor query performance and response times
  • Analytics Accuracy: Verify tracking data accuracy and completeness
  • Cross-Device Testing: Test session persistence across different devices

Troubleshooting

Common Issues

Session Authentication Failures

  • Symptoms: 401 errors, session not found, invalid token responses
  • Causes: Expired tokens, invalid session IDs, database connection issues
  • Solutions: Token refresh logic, session recreation, proper error handling

Data Persistence Problems

  • Symptoms: Activity data lost, metrics not saving, session state inconsistent
  • Causes: JSON parsing errors, database constraints, transaction failures
  • Solutions: JSON validation, proper error handling, database integrity checks

Performance Issues

  • Symptoms: Slow session queries, analytics timeout, high database load
  • Causes: Missing indexes, large JSON payloads, inefficient queries
  • Solutions: Query optimization, JSON field restructuring, index management

Conversion Failures

  • Symptoms: Account conversion errors, data migration incomplete
  • Causes: Foreign key violations, player UUID issues, transaction rollbacks
  • Solutions: Data validation, proper transaction handling, rollback recovery

Debug Tools

# Session debugging
curl -X GET "http://localhost:4321/api/demo/sessions/[sessionId]" \
  -H "Authorization: Bearer [sessionToken]"

# Activity tracking test
curl -X PUT "http://localhost:4321/api/demo/sessions/[sessionId]/activity" \
  -H "Authorization: Bearer [sessionToken]" \
  -H "Content-Type: application/json" \
  -d '{"activityType": "test", "activityData": {"debug": true}}'

# Analytics debugging
curl -X GET "http://localhost:4321/api/demo/analytics?startDate=2024-01-01" \
  -H "Authorization: Bearer [adminToken]"

# Database query debugging
echo "SELECT COUNT(*) FROM demo_sessions WHERE expires_at > CURRENT_TIMESTAMP;" | \
  bunx wrangler d1 execute padawan-forge-db --local

# Migration status check
echo "SELECT * FROM migration_stats WHERE migration_number = '0006_demo_system';" | \
  bunx wrangler d1 execute padawan-forge-db --local

Future Enhancements

Planned Features

  • Multiple Topics: Simultaneous multi-topic sessions
  • Adaptive Difficulty: Real-time difficulty adjustment based on performance
  • Social Features: Leaderboards and challenge sharing for converted accounts
  • Advanced Analytics: Heat maps, learning curves, cognitive load analysis
  • Accessibility: Screen reader support, keyboard navigation, high contrast modes

Technical Improvements

  • Progressive Web App: Offline capability and app-like experience
  • Advanced Caching: Intelligent pre-generation of popular topic combinations
  • Machine Learning: Personalized statement generation based on user patterns
  • Real-time Multiplayer: Competitive demo sessions between anonymous players

This demo system provides a flexible, analytics-focused foundation for anonymous user engagement that tracks detailed user behavior and conversion metrics while supporting the platform’s core functionality. The JSON-based architecture allows for rapid iteration and customization of tracking requirements without schema changes.

← Authentication System Level & Experience System →
PadawanForge v1.4.1