Lesson 3: How We Built MasteryPath — Adaptive Quiz Logic in One FastAPI Stack

Week 3: Core Business Logic — Building MasteryPath

Introduction

Adaptive learning products fail in production for predictable reasons: difficulty is guessed instead of measured, scores ignore response time and confidence, and analytics arrive as raw tables instead of coaching signals. MasteryPath is a reference architecture that unifies six backend concerns—question difficulty, progressive adaptation, scoring, performance analytics, and topic graphs—behind one FastAPI surface and one learner-facing UI.

You will walk away with a composable core/ layout, a dual API pattern (curriculum routes plus product workflows), and a Docker stack you can exercise with pytest.

System Overview

The stack is Python 3.12 throughout: FastAPI for HTTP, SQLAlchemy 2.0 (async) on PostgreSQL for sessions and analytics, Redis for performance windows and scoring normalization, and optional Google Gemini for enhanced classification and insights. A static MasteryPath SPA on port 3000 talks to an nginx gateway on port 8080; the backend never exposes port 8000 directly to the host.

Responsibilities split cleanly:

• Presentation: Question Lab, Quiz Arena, Mastery Radar, and Knowledge Constellation views—product flows, not lesson index pages.

• API: /learn/lesson-15 … /learn/lesson-20 preserve curriculum shapes; /api/v1/* composes end-to-end journeys.

• Core: core/difficulty, core/adaptive, core/scoring, core/analytics, and core/topics.

• Worker: A lightweight process polls AnalyticsEvent rows and materializes QuizAttempt and PerformanceMetric records.

Engine / Core System Design

The engine owns domain rules; FastAPI owns transport and dependency injection. Product workflows never import lesson routers—they call core services only, and core never imports backend/app.

Difficulty — FeatureExtractor builds readability and vocabulary signals; DifficultyClassifier produces a canonical 0–1 score with optional Gemini enhancement on /classify-gemini.