Release: v9.0.0 (cumulative — Sprint 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9)
Date: 2026-07-26
Owner: Solo developer (zero-budget constraint)
This zip contains: the complete Mentora platform — every sprint, every chapter of the system design, every feature. Unzip into an empty folder and run it — no prior Mentora state required.
This is the final sprint. The 20-week roadmap is complete. All 17 chapters of the locked system design are covered. The platform is ready for beta launch.
Mentora is an adaptive AI learning platform built around 8 personalization pillars:
- Adaptive paths — DQN path optimizer with nightly offline retrain
- Mastery tracking — BKT (Bayesian Knowledge Tracing) for cold skills, DKT (Deep Knowledge Tracing) for high-volume skills
- Spaced repetition — SM-2 algorithm (same as Anki)
- AI tutoring — LangChain + LangGraph agent with Groq Llama-3.3-70B + RAG over Qdrant
- Content recommendation — LinUCB contextual bandit (16-dim context, 7 arms)
- Peer matching — bi-encoder semantic similarity over learner profiles
- Difficulty adjustment — real-time per-response based on mastery delta
- Learning analytics — parent + teacher dashboards, weekly PDF reports, cohort insights
The platform is built solo, on free-tier infrastructure, for ₹0/month. It's now a production-grade PWA ready for beta launch to 50 invited users.
- Repo skeleton (monorepo:
ai_service/+frontend/) - Alembic migrations (baseline + infra_cost_log)
- GitHub Actions CI/CD (3 workflows)
- Free-tier infra templates + scripts
- Docker Compose dev stack (Postgres 16, Redis 7, Qdrant, FastAPI, Celery)
- 3 ADRs (alembic-over-raw-sql, free-tier-only, monorepo-structure)
FREE_TIER_INFRA.mdmapping every paid service to its free-tier alternativeSPRINT_ROADMAP.mdcovering all 17 chapters of the locked system design
- 8 new DB tables (email_verifications, password_resets, mfa_secrets, learner_profiles, etc.)
- 22 new API endpoints across 3 routers (
auth,onboarding,me) - TOTP MFA (RFC 6238) with AES-GCM-encrypted secrets + 10 single-use backup codes
- Email verification + password reset via signed JWT action tokens
- Sliding-window rate limiting (Redis) on all
/auth/*routes - Account lockout (5 fails → 15 min)
- Refresh-token rotation with reuse detection
- 7-step resumable onboarding wizard
- 5-tab settings page (Profile / Security / MFA / Sessions / Danger zone)
- 41 unit tests; full OWASP Top 10 coverage documented
- Document upload pipeline (PDF / DOCX / EPUB / YouTube / Markdown / HTML)
- Chunking (RecursiveCharacterTextSplitter 1000/200)
- BGE-base-en-v1.5 embeddings (cached in Postgres)
- Qdrant vector DB upsert with payload filtering
- SSE streaming chat with Llama-3.3-70B + MMR retrieval
- 28 unit tests
- Skill taxonomy (~200 skills across 5 domains)
- Quiz engine with 7 question types (mcq, multi_select, fill_blank, short_answer, code_eval, ordering, matching)
- BKT service with O(1) mastery update
- SM-2 spaced repetition with quality-scored scheduling
- LinUCB contextual bandit (16-dim context, 7 arms)
- DQN path optimizer with nightly offline retrain
- Multi-stage cold start manager (topic similarity → peer emulation → full LinUCB)
- Prerequisite DAG with recursive checking
- Reward shaping (0.4 mastery + 0.3 engagement + 0.2 completion + 0.1 satisfaction)
- Event sourcing (learning_events + 5 materialized views)
- 72 unit tests
- Per-user Qdrant collections
- RAG pipeline with MMR (λ=0.5) + cross-encoder reranking (BGE-reranker-base)
- Query expansion via Llama-3.1-8B
- Multi-turn conversational AI with citation system
- 5 tutor personas (Mentor / Coach / Socratic / Study Buddy / Examiner)
- Knowledge-gap detection (nightly Celery task)
- Daily feedback aggregation
- Tool-use budget (max 5 tool calls per turn)
- Free DuckDuckGo web search integration
- 61 unit tests
- Apache AGE extension on Neon Postgres (in-database graph)
skill_edgestable with 4 edge types (prerequisite, related, reinforces, depends_on)- Curated + ML-inferred skill edges
- Prerequisite engine with recursive checking (
p_known > 0.7gate) - PyTorch LSTM DKT model with nightly offline retrain
- ONNX runtime inference (256 MB RAM safe)
- Per-skill switch (DKT for skills with >1000 attempts, BKT otherwise)
- node2vec graph embeddings for Graph-RL state augmentation
- 37 unit tests
- Connections (request/accept/reject) with bi-encoder peer matching
- Communities (Reddit-style posts + comments + votes + moderation)
- Study sessions with RSVP + ICS calendar invites
- LiveKit Cloud integration (WebRTC, 10 concurrent participants, 10k min/mo free)
- Yjs shared document via y-websocket (collaborative notes)
- tldraw shared whiteboard
- LiveKit auto-record to R2 + Groq Whisper transcription
- 50 unit tests
- Learner analytics (mastery over time, study streaks, time-spent, skill heatmaps)
- Cohort analytics for community owners
- Parental dashboard (safe-summary metrics, no chat content)
- Parent-child link flow with email invite
- Weekly PDF reports via Resend (Sundays 18:00 IST)
- Teacher dashboard with CSV roster import
- 5 new materialized views (hourly refresh via QStash → Celery)
- Real-time analytics via SSE
- FERPA consent gates (fail-closed middleware)
- COPPA enforcement (under-13 requires parent consent)
- Audit log (PII access logging, 7-year retention)
- 69 unit tests
- WCAG 2.2 AAA audit (manual + axe-core CI, 0 violations)
- Skip-link, font scaler (S/M/L/XL), motion toggle, dyslexia font, high contrast, color-blind modes
- GDPR Art 15 (data export) + Art 17 (right to deletion with 30-day grace) + Art 7 (cookie consent)
- COPPA enforcement with 5 age buckets
- SOC 2 Type II prep (12 controls seeded, incident response playbook)
- 8 SLOs (API P99, error rate, LLM success, RAG relevance, RL diversity, bg job success, DB pool, free-tier quota)
- Full observability stack: structlog + Sentry + OpenTelemetry + Prometheus + Langfuse
- 4 i18n locales (en, hi, te, ta) with 75 keys each
- 65 unit tests
- PWA — hand-rolled service worker (no next-pwa dependency; see ADR 0004)
- App-shell precache + runtime cache + offline write queue (IndexedDB)
- Install prompt with 14-day dismissal
- Update flow with user-visible "New version available" banner
- Offline banner with queue depth
- Web Push — VAPID (RFC 8291 + 8292) implemented in-house with
cryptography+httpx- 4-state push opt-in (unsupported / default / subscribed / denied)
- Per-device subscriptions, soft-revoke on 404/410
- Admin broadcast with optional cohort filter
- 5 notification kinds (review_due, session_reminder, weekly_report, achievement, beta_announcement)
- Beta programme — invite-gated, single cohort, 50 testers (see ADR 0006)
MENTORA-BETA-XXXXinvite codes with email-binding option- 14-day dismissal tracking
- Feedback widget (floating
?button on every page) with 4 kinds (bug / feature / praise / general) - NPS survey (0-10 scale + clarity score + free-text)
- Per-cohort analytics
- Public status page —
/statusroute +/api/v1/statusendpoint- 8 seeded components (API, DB, Redis, RAG, Tutor, LiveKit, Celery, CDN)
- Incident management with timeline updates (statuspage.io-style)
- 90-day uptime tracking (5-min buckets, pruned nightly)
- 4 overall states (all_operational / degraded / partial_outage / major_outage)
- Weekly status digest email (Mondays 15:30 IST)
- PWA offline-action sync — client-queued, server-validated allowlist (see ADR 0005)
- 9 allowed replayable paths (review_result, quiz_response, note CRUD, community_post, event, rl_feedback, chat_message)
- Idempotent on
client_uuid - 5-attempt retry, then dropped
- Per-user stats endpoint
- Performance beacons
- RUM endpoint
/api/v1/perf/beacon(1-in-100 sampled, 100k/day cap) - CI endpoint
/api/v1/perf/audit(Lighthouse CI uploads) - 90-day history with admin-only list
- RUM endpoint
- Lighthouse CI — runs on every PR, asserts Perf ≥95 / A11y ≥95 / BP =100 / SEO ≥95
- Performance budget — frontend ≤300KB initial / ≤200KB chunk; backend Docker ≤1.5GB
- Beta deployment workflow —
release/*tag → fly.io + Vercel + Alembic migrate + smoke test + Discord notify - 9 new docs — user-guide, api-reference, deployment-guide, beta-launch-playbook, runbook, performance-budget, 3 ADRs
- 515 cumulative unit tests (72 new in Sprint 9)
- Python 3.11+
- Node.js 20+
- Docker Desktop
- Git
- ~6 GB free disk space
# 1. Unzip
unzip mentora-through-sprint9.zip -d ~/dev/mentora
cd ~/dev/mentora
# 2. Copy .env and fill in (DATABASE_URL, GROQ_API_KEY, JWT_SECRET, VAPID keys)
cp .env.example .env
# Generate VAPID keys:
python3 -c "from cryptography.hazmat.primitives.asymmetric import ec; from cryptography.hazmat.primitives import serialization; k=ec.generate_private_key(ec.SECP256R1()); print(k.private_bytes(serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8, serialization.NoEncryption()).decode()); print(k.public_key().public_bytes(serialization.Encoding.PEM, serialization.PublicFormat.SubjectPublicKeyInfo).decode())"
# 3. Start infra (Postgres, Redis, Qdrant)
docker compose up -d
# 4. Set up backend
cd ai_service
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn main:app --reload --port 8000
# 5. In another terminal, start Celery
cd ai_service
celery -A workers.celery_app.celery_app worker --loglevel=info --concurrency=2
celery -A workers.celery_app.celery_app beat --loglevel=info
# 6. In another terminal, start frontend
cd frontend
npm install
npm run devOpen http://localhost:3000 — you should see the Mentora landing page.
For full instructions, see SPRINT_9_INSTALL.md.
mentora-through-sprint9/
├── ai_service/ # FastAPI backend
│ ├── main.py # App factory + router registration
│ ├── config.py # Pydantic settings (all sprints)
│ ├── routers/ # 34 routers, 164 endpoints
│ ├── services/ # 31 service modules
│ ├── schemas/ # Pydantic v2 models
│ ├── engines/ # BKT, SM-2, LinUCB, DQN, cold start
│ ├── pipelines/ # RAG, document processor
│ ├── core/ # security, observability, middleware
│ ├── migrations/versions/ # 11 Alembic migrations (Sprint 0-9)
│ ├── workers/ # Celery app + 8 task modules
│ ├── i18n/ # 4 locale catalogs
│ └── tests/ # 515 unit tests
├── frontend/ # Next.js 14 frontend
│ ├── src/
│ │ ├── app/ # App Router (60+ pages)
│ │ ├── components/ # PWA + beta + accessibility + analytics + ...
│ │ ├── hooks/ # PWA + auth + tutor hooks
│ │ ├── lib/ # API client, pwa/, observability/
│ │ └── i18n/ # I18nProvider + locale config
│ ├── public/ # manifest.json, sw.js, offline.html, icons/
│ ├── next.config.js # Headers, image formats, bundle budget
│ ├── lighthouserc.json # Lighthouse CI thresholds
│ ├── vercel.json # Vercel project config
│ └── package.json # v9.0.0
├── infra/
│ ├── deployment/ # fly.toml, docker-compose.prod.yml
│ ├── cdn/ # Cloudflare rules
│ ├── status-page/ # Status page config
│ └── observability/ # Sprint 8 Prometheus + Grafana + Loki + Tempo
├── scripts/ # Operational scripts
├── docs/ # Architecture + user docs + ADRs
├── .github/workflows/ # 7 CI/CD workflows
├── SPRINT_*_REPORT.md # 10 sprint reports
├── SPRINT_*_INSTALL.md # 9 install guides
├── SPRINT_ROADMAP.md # 10-sprint plan (all marked ✅)
├── MANIFEST.md # File inventory
├── FREE_TIER_INFRA.md # 22-service free-tier mapping
├── BACKLOG.md # Post-beta roadmap
└── README.md # This file
| Sprint | Theme | Status |
|---|---|---|
| 0 | Foundation hardening | ✅ Done |
| 1 | Identity & Learner Profile | ✅ Done |
| 2 | Content Ingestion & RAG | ✅ Done |
| 3 | Adaptive Intelligence (BKT + SM-2 + LinUCB + DQN + Cold Start) | ✅ Done |
| 4 | RAG & AI Tutor (LangChain + LangGraph + Groq) | ✅ Done |
| 5 | Knowledge Graph + DKT | ✅ Done |
| 6 | Social + Live Cohort | ✅ Done |
| 7 | Analytics & Dashboards | ✅ Done |
| 8 | Accessibility + Compliance + Observability | ✅ Done |
| 9 | PWA, Polish, Beta Launch | ✅ Done |
10 of 10 sprints complete. See SPRINT_ROADMAP.md for the full plan with system-design chapter traceability.
- Backend: FastAPI 0.111 + asyncpg + SQLAlchemy 2.0 (Alembic for migrations)
- Frontend: Next.js 14 (App Router) + React 18 + TypeScript + Tailwind + Radix UI + TanStack Query + Zustand
- Database: PostgreSQL 16 (Neon, 0.5 GB free) + Qdrant Cloud (1 GB free) + Apache AGE (in-DB graph)
- Cache/Queue: Redis 7 (Upstash, 10k cmds/day free) + Celery 5.3
- LLM: Groq (Llama-3.3-70B for chat, Llama-3.1-8B for fast tasks, Whisper-large-v3 for STT)
- Embeddings: BGE-base-en-v1.5 (local) + BGE-reranker-base (cross-encoder)
- Reranker: BGE-reranker-base + BM25 fallback
- ML/DKT: PyTorch LSTM with ONNX runtime inference
- Storage: Cloudflare R2 (S3-compatible, free 10 GB + free egress)
- Realtime: LiveKit Cloud (WebRTC, 10k min/mo free) + Yjs (collaborative) + tldraw (whiteboard)
- Email: Resend (3k/mo free)
- Auth: JWT + httpOnly refresh cookies + bcrypt cost 12 + TOTP MFA (pyotp)
- PWA: Hand-rolled service worker + VAPID Web Push (RFC 8291/8292, in-house crypto)
- CI/CD: GitHub Actions (free for public repos)
- Observability: Langfuse + Sentry + Prometheus + Grafana + Loki + Tempo + OpenTelemetry + structlog
- Hosting: fly.io (256 MB shared-cpu-1x, free) + Vercel (frontend, free hobby tier)
- CDN: Cloudflare (free tier — cache + WAF + rate limit)
All on free tiers. Total monthly cost: ₹0.
See FREE_TIER_INFRA.md for the full mapping.
| Document | Purpose |
|---|---|
SPRINT_ROADMAP.md |
10-sprint plan with system-design traceability |
SPRINT_{0..9}_REPORT.md |
Per-sprint architecture + deliverables + tests |
SPRINT_{1..9}_INSTALL.md |
Per-sprint install + smoke-test guides |
MANIFEST.md |
File inventory |
docs/user-guide.md |
End-user guide — 16 sections covering every beta feature |
docs/api-reference.md |
Flat endpoint reference — all 164 endpoints |
docs/deployment-guide.md |
Beta deployment guide — 13 sections |
docs/beta-launch-playbook.md |
14-day beta window operational playbook |
docs/runbook.md |
16-section on-call runbook with 11 incident scenarios |
docs/performance-budget.md |
Frontend + backend + network + free-tier budgets |
docs/auth-flow.md |
Sprint 1 auth sequence diagrams |
docs/rag-architecture.md |
Sprint 2 RAG pipeline deep dive |
docs/tutor-architecture.md |
Sprint 4 AI Tutor design |
docs/knowledge-graph-architecture.md |
Sprint 5 Apache AGE + DKT |
docs/social-live-architecture.md |
Sprint 6 LiveKit + Yjs + tldraw |
docs/analytics-architecture.md |
Sprint 7 dashboards + consent gates |
docs/accessibility-architecture.md |
Sprint 8 WCAG 2.2 AAA audit |
docs/compliance-runbook.md |
Sprint 8 GDPR/COPPA/FERPA/SOC 2 |
docs/observability-stack.md |
Sprint 8 Prometheus + Grafana + Loki + Tempo |
docs/wcag-manual-audit.md |
Sprint 8 manual accessibility audit |
docs/commit-convention.md |
Conventional commits |
docs/adr/0001-alembic-over-raw-sql.md |
ADR: Alembic for migrations |
docs/adr/0002-free-tier-only.md |
ADR: free-tier constraint |
docs/adr/0003-monorepo-structure.md |
ADR: monorepo layout |
docs/adr/0004-pwa-strategy.md |
ADR: hand-rolled SW vs next-pwa (Sprint 9) |
docs/adr/0005-offline-first.md |
ADR: client-queued server-validated allowlist (Sprint 9) |
docs/adr/0006-beta-launch.md |
ADR: invite-gated beta programme (Sprint 9) |
FREE_TIER_INFRA.md |
22-service free-tier mapping |
BACKLOG.md |
Post-beta roadmap (Sprints 10+) |
| Metric | Count |
|---|---|
| Sprints completed | 10 (Sprint 0 → Sprint 9) |
| Backend Python files | 130+ |
| Backend routers | 34 |
| Backend services | 31 |
| Backend engines | 12 (BKT, SM-2, LinUCB, DQN, cold start, difficulty adjuster, prerequisite checker, reward shaper, mastery estimator, query router, query transform, reranker) |
| Backend pipelines | 6 (RAG, document processor, embedding, transcription, conversation, tutor) |
| Backend Celery task modules | 8 |
| Backend Celery beat jobs | 30+ |
| Database migrations | 11 |
| Database tables | 60+ |
| Frontend TS/TSX files | 75+ |
| Frontend pages (App Router) | 30+ |
| Frontend components | 50+ |
| API endpoints | 164 |
| Unit tests | 515 (all passing) |
| ADRs | 6 |
| Sprint reports | 10 |
| Sprint install guides | 9 |
| Architecture docs | 9 |
| CI/CD workflows | 7 |
| i18n locales | 4 (en, hi, te, ta) |
| WCAG 2.2 AAA violations | 0 |
| SLOs with active alerts | 8 |
| SOC 2 controls seeded | 12 |
| Beta invite codes ready | 50 (via seed_beta_invites.py) |
| Total monthly cost | ₹0 |
The 20-week roadmap is complete. The next steps are operational:
- Provision free-tier accounts — see
docs/deployment-guide.md§1 - Set secrets — fly.io, Vercel, GitHub Actions (see §4)
- Deploy —
git tag release/v9.0.0 && git push origin release/v9.0.0 - Seed beta invites —
python scripts/seed_beta_invites.py --count 50 - Invite 50 testers — see
docs/beta-launch-playbook.md - Run the 14-day beta window — daily triage + weekly office hours
- Decide: go / no-go for public launch — based on retention + NPS
The post-beta roadmap (in BACKLOG.md) covers:
- Sprint 10-12: Mobile apps (React Native + Expo)
- Sprint 13: Marketplace (user-generated content, revenue share)
- Sprint 14: AI Voice Tutor (Groq Whisper STT + Llama-3.3 + Groq TTS)
- Sprint 15: White-label theming (B2B institution customization)
- Sprint 16+: SOC 2 Type II audit, paid tier, scale infra
These are explicitly out of scope for the current 20-week plan. Beta validation determines priorities.
Built solo, on free-tier infrastructure, over 20 weeks (Sprint 0 → Sprint 9). Total cost: ₹0.
The platform now includes:
- 164 API endpoints across 34 routers
- 60+ database tables across 11 migrations
- 515 passing unit tests
- 8 adaptive engines + 5 ML models
- 4 i18n locales with WCAG 2.2 AAA compliance
- 8 SLOs with active Prometheus alerts
- 12 SOC 2 controls seeded
- 50 invite codes ready for beta
Time to ship. 🚀