QuestLearn: Where Every Student is the Hero of Their Own Story

🎯 The Inspiration

My inspiration for QuestLearn came from a deeply personal experience: tutoring my younger sister during her elementary school years. She struggled to learn and retain information using traditional methods. But I discovered something powerful—when I spent hours making learning fun and engaging, she absorbed everything like a sponge.

The problem was clear: effective learning requires personalized attention and engagement, but teachers can't give every student hours of one-on-one time. When I saw Google's Gemini 3 Hackathon announcement, I had an epiphany: What if AI could create the fun, gamified learning experiences my sister needed—at scale, for every student?

QuestLearn transforms boring curriculum into epic adventures. Students aren't just memorizing facts; they're pirates solving fraction puzzles to find treasure, detectives using photosynthesis to crack cases, and heroes on quests where learning is the superpower.

🧠 What I Learned

The Power of Gemini 3 for Educational Content

Working with Gemini 3 Flash taught me that AI isn't just good at generating content—it's exceptional at creating pedagogically sound, age-appropriate, and genuinely engaging educational experiences.

Key Discovery: Gemini 3's multimodal capabilities and long context window were game-changers. I could feed it:

Educational standards from the Common Standards Project API
Age-appropriate themes and narrative styles
Learning objectives and difficulty parameters

And it would generate complete, interactive HTML quests with:

Progressive difficulty scaffolding
Multiple-choice challenges with immediate feedback
Hints and tutorials that adapt to student needs
Celebration screens that feel genuinely rewarding

The Math Behind Adaptive Learning:

One fascinating challenge was implementing the three-tier difficulty system. For a given learning objective, we needed to generate content at three levels:

$$\text{Difficulty Level} = f(\text{grade level}, \text{student performance}, \text{content complexity})$$

Where:

Advanced Track: $\text{complexity} = \text{baseline} + 2\sigma$
Grade-level Track: $\text{complexity} = \text{baseline}$
Foundational Track: $\text{complexity} = \text{baseline} - 1.5\sigma$

This ensures every student gets appropriately challenging content without overwhelming or boring them.

Authentication is Hard (But Critical)

Building a secure authentication system for a K-12 platform taught me about:

OAuth 2.0 flows and the importance of redirect URI validation
JWT token security (learned the hard way that HS512 requires minimum 512-bit secrets!)
CORS and forwarded headers when deploying across multiple Railway services
Client-side vs server-side rendering challenges with Next.js environment variables

The moment OAuth finally worked end-to-end after hours of debugging redirect loops? Pure joy.

Database Design for Educational Analytics

Designing the PostgreSQL schema required thinking through complex relationships:

-- Progress tracking needs to capture:
-- Student → Multiple Classes → Multiple Curricula → Multiple Quests
-- With detailed analytics on each attempt

I learned to balance normalization (avoiding data duplication) with query performance (sometimes denormalizing for faster reads). The student progress tracking alone required:

Curriculum-level progress tracking
Individual quest completion records
Attempt history with detailed analytics (time spent, hints used, tutorial styles viewed)
Real-time Firebase integration for live updates

🛠️ How I Built It

Architecture Overview

Backend: Spring Boot + Kotlin

RESTful API with comprehensive endpoints
PostgreSQL for relational data (users, classes, curricula, progress)
Firebase for real-time features (live student activity)
Gemini 3 Flash API for AI quest generation
OAuth 2.0 with Google for authentication
JWT tokens with HS512 signing

Frontend: Next.js 14 + TypeScript

Server and client components for optimal performance
Role-based dashboards (Teacher, Student, Parent, Admin)
Responsive design with Tailwind CSS
Real-time progress updates via Firebase listeners

AI Integration: Gemini 3 Flash

Dynamic quest generation with educational standards alignment
Three-tier difficulty adaptation (Advanced/Grade-level/Foundational)
Interactive HTML generation with embedded JavaScript
Confidence scoring for curriculum-to-standards matching

Infrastructure: Railway

Backend service (Spring Boot)
Frontend service (Next.js)
PostgreSQL database
Automated CI/CD from GitHub

The Quest Generation Pipeline

Teacher Input: Grade level, subject, learning objectives
Standards Matching: Common Standards Project API validates alignment
Gemini Prompt Engineering: Generate an interactive educational quest for [grade] students Theme: [engaging narrative] Learning objectives: [standards] Difficulty: [advanced/grade-level/foundational] Format: Complete HTML with embedded JavaScript
Quality Validation: AI confidence scoring ensures curriculum alignment
Storage: Quest HTML stored in database, served via /api/v1/quests/{id}/html
Student Interaction: Iframe-based player with postMessage API for progress tracking

The Most Satisfying Code

The quest completion tracking system using postMessage:

// Quest HTML sends completion data
window.parent.postMessage({
  type: 'QUEST_COMPLETE',
  score: 85,
  timeSpent: 1200,
  hintsUsed: 2,
  challengeResults: [...]
}, '*');

// QuestPlayer component receives and processes
useEffect(() => {
  const handleQuestComplete = async (event: MessageEvent) => {
    await progressApi.recordQuestCompletion({
      studentId,
      questId,
      score: event.data.score,
      // ... detailed analytics
    });
  };
  window.addEventListener('message', handleQuestComplete);
}, []);

This elegant pattern allows quest HTML (served from backend) to communicate with the Next.js frontend without CORS issues.

💪 Challenges I Faced

Challenge 1: The OAuth Redirect Loop of Doom

The Problem: After successful Google authentication, users were stuck in an infinite redirect loop instead of landing on the dashboard.

The Debug Journey:

OAuth succeeded ✅
JWT token generated ✅
Backend redirected to frontend ✅
Frontend called /api/v1/auth/me ❌ → went to frontend domain, not backend!

Root Cause: Next.js NEXT_PUBLIC_* environment variables must be set at build time, not runtime. The production build had undefined baked into the JavaScript for the API base URL.

The Solution:

// Had to hardcode the backend URL as fallback
const API_BASE_URL = process.env.NEXT_PUBLIC_API_BASE_URL || 
  'https://questlearn-production.up.railway.app';

Lesson Learned: In Next.js, environment variables work differently in development vs production. Always test the actual production build before deploying!

Challenge 2: JWT Secret Size Requirements

The Error:

The specified key byte array is 256 bits which is not secure enough 
for the HS512 algorithm which requires at least 512 bits

The Problem: I generated a random JWT secret that was too short for the HS512 algorithm.

The Math:

HS512 requires: $\text{key size} \geq 512 \text{ bits} = 64 \text{ bytes}$
My original key: $256 \text{ bits} = 32 \text{ bytes}$ ❌
Solution: Generated 72-character alphanumeric key = $576 \text{ bits}$ ✅

Lesson Learned: Security requirements aren't suggestions—cryptographic algorithms have minimum key sizes for a reason!

Challenge 3: Railway HTTPS Redirect Issues

The Problem: Backend was generating http:// URLs instead of https:// even though Railway provides SSL.

Root Cause: Spring Boot didn't know it was behind an HTTPS proxy.

The Solution:

server:
  forward-headers-strategy: FRAMEWORK

This tells Spring Boot to trust X-Forwarded-Proto headers from Railway's proxy.

Lesson Learned: Modern deployment often involves reverse proxies—your app needs to be "proxy-aware" to generate correct URLs.

Challenge 4: Gemini Quest Generation Structure

The Problem: Gemini was generating beautiful, educational quest content, but not following the required three-screen structure:

Introduction screen
Challenge screens (with scoring)
Celebration screen

Why This Mattered: The scoring system depended on parsing specific postMessage events from each screen type.

The Solution: Enhanced prompt engineering with explicit structure requirements:

You MUST structure the quest with exactly three screens:

SCREEN 1 - INTRODUCTION:
- Set the scene and narrative
- NO questions or scoring
- End with: <button onclick="showScreen(2)">Start Quest!</button>

SCREEN 2 - CHALLENGES:
- Present [X] multiple-choice questions
- Track score with: correctAnswers++
- Use: <button onclick="checkAnswer(...)">

SCREEN 3 - CELEBRATION:
- Display final score
- Provide encouraging feedback
- Send completion: window.parent.postMessage({type: 'QUEST_COMPLETE', score: ...})

Lesson Learned: When working with AI, be extremely explicit about structure requirements. What seems "obvious" to humans needs to be spelled out for AI.

Challenge 5: Database Migrations in Production

The Problem: How do you evolve a database schema without breaking production?

The Solution: Flyway migration versioning:

-- V1__initial_schema.sql (immutable - never change)
-- V2__add_progress_tracking.sql (new feature)
-- V3__add_tutorial_analytics.sql (enhancement)

Each migration is:

Versioned (V1, V2, V3...)
Immutable (never modify old migrations)
Idempotent (safe to run multiple times)
Tested (in local Docker environment first)

Lesson Learned: Database migrations are scary in production. Having a solid versioning strategy and local testing environment is crucial.

🎨 What Makes QuestLearn Special

1. True Differentiation at Scale

Most "adaptive learning" platforms show the same content with minor tweaks. QuestLearn generates completely different quests for each difficulty level:

Advanced: Pirates calculating compound interest on treasure investments
Grade-level: Pirates splitting gold coins evenly among crew
Foundational: Pirates counting gold coins with visual aids

Same learning objective (fractions), completely different experiences.

2. Teacher-Centric Design

Unlike consumer edtech that adds to teacher workload, QuestLearn was designed from day one to save teachers time:

✅ Auto-grading with detailed analytics
✅ Automatic differentiation (no manual grouping)
✅ Standards-aligned (works with existing curriculum)
✅ Parent communication built-in
✅ One-click curriculum generation

3. Educational Rigor Meets Gaming Fun

The quest themes aren't just window dressing—they're carefully designed for each age group:

Elementary (K-5): Whimsical, exploratory (space explorers, dinosaur detectives)
Middle School (6-8): Adventure-based (mystery solving, time travel)
High School (9-12): Professional contexts (journalism, forensics, engineering)

Each theme provides authentic context for why students need to learn the content.

4. Privacy-First Architecture

Working with K-12 data requires serious privacy considerations:

🔒 All student data encrypted at rest and in transit
🔒 Role-based access control (teachers can't see other teachers' students)
🔒 Parental consent flows built-in
🔒 FERPA-compliant data handling
🔒 OAuth instead of student-managed passwords

📊 Future Vision

Short Term (Next 3 Months)

Complete teacher dashboard with class management
Implement parent portal for progress monitoring
Add real-time student help request system
Build curriculum marketplace (teachers share quests)

Medium Term (6-12 Months)

Multi-language support (starting with Spanish)
Offline mode for low-connectivity schools
AI-powered learning difficulty prediction
Integration with Google Classroom, Canvas, Schoology

Long Term (1-2 Years)

Voice-enabled quests for early readers
VR/AR quest experiences
Peer collaboration quests (multiplayer learning)
Professional development platform (teachers learn to use AI in education)

🎯 Impact Metrics

If QuestLearn reaches just 1,000 students:

$10,000,000$ hours saved in teacher prep time annually
- Calculation: 1,000 students = ~50 teachers × 10 hours/week × 40 weeks = 20,000 hours
- At $50/hour teacher time value = $1M in value created
Engagement boost: Studies show gamification increases engagement by 40-60%
- Potential to re-engage 400-600 previously disengaged students
Learning outcomes: Adaptive learning platforms show 20-30% improvement in test scores
- Helping 200-300 students achieve grade-level proficiency