Lesson 8: Performance Optimization and Advanced Features

AI Quiz Performance & Content Platform — System Design for Engineers

Running a quiz product at scale means more than CRUD endpoints. You need indexed database access, compressed API responses, observable memory and connection pools, profile-based AI generation, human review workflows, and automated content refresh—all behind one operational surface. This project is a self-contained capstone stack that consolidates those concerns into a single FastAPI backend, a React dashboard, and a Docker runtime you can run with one compose file.

The engineer payoff is practical: you see how cross-cutting middleware, a shared core/ package, and two HTTP surfaces (product workflows vs. capability demos) stay coherent without spinning up separate microservices.

Core Components

Database Query Optimization

OptimizedQueries and QueryOptimizer in core/database/ provide JOIN-based quiz reads, leaderboard aggregation, and PostgreSQL EXPLAIN ANALYZE plus index-usage stats. PerformanceMonitorMiddleware records per-request timing. Product quiz routes call the optimized path by default; the learning surface exposes query stats and index usage for inspection.

API Response Optimization

CompressionMiddleware applies Brotli or gzip when responses exceed COMPRESSION_MIN_SIZE. CacheService in core/cache/redis_cache.py backs response caching with a memory fallback. Prometheus-style metrics land in performance_metrics and are surfaced through ops endpoints.

Memory Management

MemoryProfilerMiddleware and MemoryTracker sample RSS and tracemalloc diffs per request. MemoryMonitor runs a background loop and feeds /ws/memory WebSocket clients. A lightweight in-process SessionCache supports learning demos without polluting the product cache path.

Connection Pooling

DatabaseConnectionPool (psycopg2 ThreadedConnectionPool) and GeminiConnectionPool with rate limiting live in core/pools/. Pool metrics expose checkout counts, peak usage, and Gemini request rates—consumed by the ops dashboard and the connection-pooling learning routes.

Multi-Model Quiz Generation

ModelRouter, GenerationService, and QualityValidator in core/generation/ route question types to configured Gemini profiles (multiple_choice_expert, essay_creative, etc.). Generation jobs and outputs persist in generation_jobs and generated_questions. Fallback to a general profile occurs when quality scores fall below QUALITY_THRESHOLD.

Content Curation Workflow

CurationService and QuestionService implement a human-in-the-loop queue: submit → claim → approve/reject/revise with audit logs in curation_audit_logs. Priority scoring blends quality metrics, queue age, and borderline-confidence boosts.

Automated Content Refreshing

RefreshService, ContentService, and APScheduler jobs in core/content_lifecycle/ compute freshness scores, flag stale items, enqueue refresh_jobs, and version content in content_versions. Scheduled scans use FRESHNESS_SCAN_HOURS; batch processing respects REFRESH_BATCH_SIZE.

Architecture Overview

System topology

The diagram below shows how browser traffic hits the dashboard on port 3001, proxies API calls through the gateway on 8080, and reaches the FastAPI backend. The core engine sits beneath route handlers; Postgres and Redis attach at the data layer.