AI Learning Path Generator

Transform your learning goals into structured, actionable roadmaps

A learning path generator that helps users master complex skills by breaking them down into structured milestones with personalized resources, time estimates, and progress tracking.

Table of Contents

• Problem Statement
• Solution
• Features
• Tech Stack
• Architecture
• Quick Start (Docker)
• Getting Started
• Usage
• API Documentation
• Streaming
• Resumable Progress
• Design Decisions
• Future Improvements
• Time Breakdown

Problem Statement

Learning complex skills is overwhelming. People struggle with:

• Where to start: Too many resources, unclear prerequisites
• How to structure learning: No clear path from beginner to proficient
• Time management: Unrealistic expectations about time commitment
• Staying motivated: Lack of visible progress and milestones

Solution

A tool that:

1. Takes a high-level learning goal (e.g., "Learn Full-Stack Development")
2. Generates a structured learning path with 5-8 progressive milestones
3. Provides time estimates, resource recommendations, and clear descriptions
4. Enables progress tracking with visual feedback
5. Allows regeneration and refinement of paths

Features

Core Features

• Intelligent Generation: Uses GPT-4 to create personalized learning paths
• Structured Milestones: Each path broken into 5-8 sequential milestones
• Resource Recommendations: Curated resources for each milestone
• Time Estimates: Realistic hour estimates per milestone
• Progress Tracking: Mark milestones complete and visualize progress
• Persistent Storage: Save and retrieve learning paths
• Experience Levels: Tailored for beginner, intermediate, or advanced learners
• Time Commitment: Customize based on available hours per week

UX Highlights

• Dark, Modern UI: Glassmorphism effects with vibrant gradients
• Smooth Animations: Fade-in effects and micro-interactions
• Responsive Design: Works seamlessly on desktop and mobile
• Visual Progress: Progress bars and completion badges
• Expandable Milestones: Click to see detailed descriptions and resources

Tech Stack

Backend

• FastAPI (Python): High-performance async API framework
• SQLAlchemy: ORM for database interactions
• SQLite: Lightweight, file-based database
• OpenAI API: GPT-4 for learning path generation
• Pydantic: Data validation and serialization

Frontend

• React 18: Modern UI library with hooks
• Vite: Fast build tool and dev server
• Axios: HTTP client for API calls
• Vanilla CSS: Custom design system with CSS variables

Why These Choices?

• FastAPI: Aligns with company stack, excellent async support, auto-generated docs
• React + Vite: Fast development, modern tooling, minimal setup
• SQLite: No configuration needed, perfect for MVP, easy migration to PostgreSQL
• Vanilla CSS: Full control, demonstrates CSS skills, no framework overhead

Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Frontend (React)                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ LandingPage  │  │ LearningPath │  │  App (State) │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                            │
                    HTTP/JSON (Axios)
                            │
┌─────────────────────────────────────────────────────────────┐
│                      Backend (FastAPI)                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Routes     │  │  AI Service  │  │   Database   │      │
│  │  (REST API)  │  │  (OpenAI)    │  │  (SQLite)    │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘

Data Flow

1. User submits learning goal via form
2. Frontend sends POST request to /api/generate
3. Backend calls OpenAI API with structured prompt
4. AI returns JSON with path title, description, and milestones
5. Backend saves to database and returns to frontend
6. Frontend displays interactive learning path
7. User can mark milestones complete (PATCH /api/milestones/{id})

Quick Start (Docker)

The fastest way to run both services with a single command:

# 1. Copy the example env file and fill in your OpenAI key
cp .env.example .env
# Edit .env: set GEMINI_API_KEY=... (free key from aistudio.google.com)

# 2. Start everything
docker compose up --build

Service	URL
Frontend	http://localhost:3000
Backend	http://localhost:8000
API docs	http://localhost:8000/docs

Stop with docker compose down. The SQLite database is persisted in the db_data Docker volume.

---

Getting Started

Prerequisites

• Python 3.8+
• Node.js 16+
• OpenAI API key

Installation

1. Clone the repository

git clone https://github.com/GibbHubb/ai-learning-path-generator.git
cd ai-learning-path-generator

2. Set up the backend

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
# AP31 — the dependency list lives at the repo ROOT: Vercel's Python builder
# reads it from there and cannot follow an `-r ../file` include, so there is
# deliberately only one copy.
pip install -r ../requirements-dev.txt

3. Configure environment variables

# Create .env file in project root
echo "GEMINI_API_KEY=your_api_key_here" > ../.env

4. Set up the frontend

cd ../frontend
npm install

Running the Application

1. Start the backend (Terminal 1)

cd backend
python main.py
# Backend runs on http://localhost:8000

2. Start the frontend (Terminal 2)

cd frontend
npm run dev
# Frontend runs on http://localhost:5173

3. Open your browser

http://localhost:5173

Tests and CI

Every push and pull request runs .github/workflows/ci.yml:

Job	Engine	What it runs
backend (postgres)	Postgres 17 service container, the engine production runs	pytest backend/tests
backend (sqlite)	SQLite file, the local-dev default	the same suite, so the two legs are comparable
frontend	none	npm ci && npm run build

Each backend leg first checks the collected test count against a floor (MIN_TESTS in the workflow), because a suite that silently collects fewer tests looks exactly like one that passed. No API key is set in CI: every test mocks the model provider.

Locally:

pip install -r requirements-dev.txt
python -m pytest backend/tests -q                       # SQLite (default)

# Postgres, the production engine: a throwaway local container
docker run -d --name ap-test-pg -e POSTGRES_PASSWORD=pw -p 55441:5432 postgres:17-alpine
TEST_DATABASE_URL=postgresql://postgres:[email protected]:55441/postgres python -m pytest backend/tests -q

The suite reads TEST_DATABASE_URL, never DATABASE_URL, and refuses any host that is not localhost/127.0.0.1: it drops every table before every test, so it must never be able to reach a real database.

Evaluating the generator (AP39)

backend/evals/ scores the learning-path generator against a gold set of 15 goals (goldset.json: 6 categories, 6 languages) on five deterministic checks: the model JSON validates against GeneratedPath; category matches; 5-8 milestones; keyword recall (the gold keywords were written from each goal, before any response existed); estimated_hours non-decreasing.

python backend/evals/run.py              # offline: fixtures through the real /api/generate, no network
python backend/evals/run.py --live       # real Gemini calls (needs GEMINI_API_KEY, asks first)
python backend/evals/run.py --record     # --live, then overwrite fixtures/ with the real replies
python backend/evals/run.py --write-baseline   # after an intended change: re-pin baseline.json

backend/tests/test_evals_ap39.py fails if an offline score drops below baseline.json.

Read the number honestly:

• Offline measures the pipeline (prompt handling, validation, category coercion, the route, the response model) against fixed replies. It does not re-measure the model. Only --live does that. Every run prints the fixtures' source and date beside the score.
• ⚠️ The current fixtures are hand-written, not recorded ("source": "hand-authored"): no API key was available when the harness was built. They were written by the same person who wrote the keywords, so keyword recall on them is 1.00 by construction and says nothing about the model. Run --record once with a key to replace them.
• The aggregate is a regression signal, not a quality score.
• After any change to the prompt in ai_service.py: bump PROMPT_VERSION, run --record, review the table, then --write-baseline.

Usage

1. Enter your learning goal

   • Describe what you want to learn (e.g., "Machine Learning for Beginners")

2. Select experience level

   • Choose: Beginner, Intermediate, or Advanced

3. Set time commitment

   • Select weekly hours available for learning

4. Generate path

   • Click "Generate Learning Path" and wait ~5-10 seconds

5. Explore your path

   • View structured milestones in timeline format
   • Click milestones to expand and see details
   • Check off completed milestones
   • Track overall progress

6. Generate new paths

   • Click "New Path" to create another learning roadmap

API Documentation

Endpoints

POST /api/generate

Generate a new learning path

Request Body:

{
  "goal": "Learn Full-Stack Web Development",
  "experience_level": "beginner",
  "time_commitment": "10-20 hours/week"
}

Response:

{
  "id": 1,
  "title": "Full-Stack Web Development Mastery",
  "description": "A comprehensive path...",
  "experience_level": "beginner",
  "time_commitment": "10-20 hours/week",
  "created_at": "2024-01-22T12:00:00",
  "milestones": [
    {
      "id": 1,
      "title": "HTML & CSS Fundamentals",
      "description": "Learn the building blocks...",
      "order": 0,
      "estimated_hours": 15,
      "resources": ["MDN Web Docs", "freeCodeCamp"],
      "completed": false,
      "completed_at": null
    }
  ]
}

GET /api/paths

Get all learning paths

GET /api/paths/{path_id}

Get a specific learning path

PATCH /api/milestones/{milestone_id}

Update milestone completion status

Request Body:

{
  "completed": true
}

DELETE /api/paths/{path_id}

Delete a learning path

Interactive API Docs

Visit http://localhost:8000/docs for Swagger UI documentation

Streaming

Path generation uses Server-Sent Events (SSE) via POST /api/generate/stream.

How it works

1. The frontend opens a streaming fetch to /api/generate/stream.
2. The backend calls OpenAI (using the same prompt and in-memory cache as the sync endpoint), then yields each milestone as a separate data: SSE event as soon as the full response is available.
3. Each milestone is immediately persisted to the database before being yielded, so partial progress is never lost.
4. A final event: done carries the complete LearningPathResponse JSON — the frontend switches to the path view with zero extra requests.
5. The existing sync endpoint POST /api/generate is untouched and continues to work.

SSE event format

data: {"id": 1, "title": "...", "order": 0, ...}

data: {"id": 2, "title": "...", "order": 1, ...}

event: done
data: {"id": 7, "title": "Full path title", "milestones": [...], ...}

The progressive milestone list is rendered live in the generation form so users can see the path being built in real time.

---

Resumable Progress

Every path and its completion state are stored in SQLite.

• On app load the frontend calls GET /api/paths and, if a previous path exists, shows a "Resume your learning path on [title]?" banner with Continue / Start new buttons.
• Clicking Continue restores the path view with all previously ticked milestones intact.
• Each milestone card has a checkbox. Toggling it calls PATCH /api/milestones/{id} which sets completed and completed_at on the database row.
• Progress is therefore persistent across browser reloads and sessions.

---

Design Decisions

Product Decisions

Focus on Learning Specifically

• Generic task breakdown tools exist, but learning has unique needs
• Progressive structure matters (prerequisites, building blocks)
• Resource recommendations are crucial for self-learners

AI Prompt Engineering

• Structured JSON output ensures consistency
• Explicit instructions for progressive ordering
• Request for "why" explanations to add educational value

Progress Tracking Over Collaboration

• MVP focuses on individual learners
• Completion tracking provides motivation
• Visual progress creates sense of achievement

Technical Decisions

Monorepo Structure

• Single repository for simplicity
• Easy to run and deploy
• Clear separation of concerns

SQLite for MVP

• Zero configuration
• File-based, portable
• Easy migration path to PostgreSQL

Vanilla CSS Over Tailwind

• Full design control
• Demonstrates CSS expertise
• Faster for custom design system
• No build complexity

React State Over Redux

• Simple state needs (current path, view)
• useState sufficient for MVP
• Reduces complexity and bundle size

GPT-4 Mini for Cost Efficiency

• Sufficient quality for structured output
• Faster response times
• Lower API costs

UX Decisions

Dark Theme

• Modern, professional aesthetic
• Reduces eye strain for extended use
• Aligns with developer tools aesthetic

Glassmorphism

• Creates depth and visual interest
• Modern design trend
• Enhances premium feel

Timeline Visualization

• Intuitive representation of learning journey
• Shows progression clearly
• Familiar mental model

Expandable Milestones

• Reduces initial cognitive load
• Progressive disclosure of information
• Keeps interface clean

🔮 Future Improvements (v2)

Features

• User Authentication: Personal accounts and saved paths
• Path Sharing: Share learning paths with others
• Community Resources: User-submitted resource recommendations
• AI Refinement: "Regenerate this milestone" for fine-tuning
• Calendar Integration: Schedule milestones with deadlines
• Learning Analytics: Track time spent, completion rates
• Skill Trees: Visualize prerequisite relationships
• Mobile App: Native iOS/Android apps
• Collaborative Paths: Team learning with shared progress

Technical Improvements

• Caching: Cache AI responses for common goals — done (AP37): a durable generation_cache DB table replaces the old in-process dict (which almost never hit on Vercel — a fresh, empty dict per recycled function instance). Keyed on a SHA-256 of the normalised (goal, experience_level, time_commitment, language, model) tuple, so casing/whitespace variants of the same goal collide and a model change never silently serves stale output. Only a schema-valid result is ever cached; entries expire after CACHE_TTL_DAYS (default 30, see .env.example). Also closed the streaming endpoint's double provider call (/api/generate/stream used to call the generator AND the plain generator again for the header fields).
• Rate Limiting: Prevent API abuse — done (AP35): a durable, per-visitor, database-backed limiter on every route that calls a model. See .env.example (TRUSTED_PROXY_HEADER) and backend/rate_limit.py.
• Cost/usage tracking: cap and count model calls — done (AP36): every llm.chat_json call is capped (max_tokens, timeout) and recorded, win or fail, in model_calls. A DAILY_CALL_BUDGET env var caps total calls per day — once spent, the model-calling routes 503 without ever constructing the provider client. See .env.example (DAILY_CALL_BUDGET), backend/usage.py, and the CRON_SECRET-gated GET /api/admin/usage for today's per-model counts.
• PostgreSQL: Production-ready database
• Docker: Containerized deployment
• CI/CD: Automated testing and deployment
• Monitoring: Error tracking and analytics
• A/B Testing: Optimize prompts and UX

Time Breakdown

Total Time: ~6 hours

• Planning & Architecture (45 min)

  • Problem definition and solution design
  • Tech stack selection
  • Architecture planning

• Backend Development (1.5 hours)

  • FastAPI setup and configuration
  • Database models and migrations
  • AI service integration
  • REST API endpoints
  • Testing with Swagger UI

• Frontend Development (2.5 hours)

  • Vite + React setup
  • Design system and CSS
  • Landing page component
  • Learning path component
  • State management and routing
  • Responsive design

• Integration & Testing (45 min)

  • Connect frontend to backend
  • Test full user flows
  • Fix bugs and edge cases
  • Polish animations and UX

• Documentation (45 min)

  • README creation
  • Code comments
  • API documentation
  • Architecture diagrams

Tradeoffs Made

Chose to prioritize:

• ✅ Polished, complete user experience
• ✅ Strong visual design and animations
• ✅ Comprehensive documentation
• ✅ Clean, maintainable code

Deferred for v2:

• ⏭ User authentication
• ⏭ Path history/browsing
• ⏭ Advanced AI features (refinement, chat)
• ⏭ Deployment to production
• ⏭ Automated tests

License

MIT License - feel free to use this project for learning or inspiration!

Author

Max

• GitHub: @GibbHubb