feat: audit and purge legacy backend files, stub Phase 2 AI LLM modules, create comprehensive PAGEWISE_API_DOCUMENTATION.md, and wire DPS test seeding

2026-09-09 11:28:34 +05:30
parent a28366f0c3
commit ec558d52fe
24 changed files with 812 additions and 1283 deletions
--- a/PAGEWISE_API_DOCUMENTATION.md
+++ b/PAGEWISE_API_DOCUMENTATION.md
@@ -0,0 +1,724 @@
+# PragatiVeer v2 — Pagewise UI & API Specification Map
+
+> **Document Type:** Comprehensive Pagewise Architecture, Button-to-API Interaction, and UI Specification Map  
+> **Target Audience:** Frontend Engineers, Full-Stack Developers, Product Managers, QA & DevOps  
+> **Last Verified:** September 2026  
+> **Frontend Engine:** Next.js 16 (App Router, React 19, TypeScript, TailwindCSS, Zustand)  
+> **Backend Engine:** FastAPI (Python 3.11) + PostgreSQL 15 (PgBouncer) + Redis 7 + MinIO S3  
+
+---
+
+## 1. Architectural & Network Request Flow
+
+### 1.1 Client-to-Backend Network Pipeline
+PragatiVeer v2 operates two primary communication paths between the Next.js frontend and the FastAPI backend:
+
+```mermaid
+graph LR
+    Browser["Client Browser"] -->|1. Page Navigation| NextServer["Next.js 16 App Router (:3000)"]
+    NextServer -->|2. Route Guard proxy.ts| Edge["Edge Cookie Evaluation"]
+    Browser -->|3. /api/* Internal Calls| Rewrites["next.config.ts Rewrites"]
+    Rewrites -->|http://backend:8000/api/*| FastAPI["FastAPI Backend (:8000)"]
+    Browser -->|4. Direct NEXT_PUBLIC_API_URL| FastAPI
+    FastAPI -->|Queries| PgBouncer["PgBouncer :5432"]
+    PgBouncer --> DB[("PostgreSQL 15")]
+    FastAPI -->|Cache & Tasks| Redis[("Redis 7")]
+    FastAPI -->|S3 Uploads| MinIO[("MinIO S3 :9000")]
+```
+
+1. **Proxy Middleware (`src/proxy.ts`):** Evaluates `auth_token` cookie on all `/dashboard/*` and `/admin/*` routes.
+   - Non-authenticated visitors heading to `/dashboard` are redirected to `/login`.
+   - Non-admin visitors (`token !== 'admin'`) heading to `/admin` are redirected to `/login`.
+2. **Reverse Proxy Rewrites (`next.config.ts`):** Inside Docker, `/api/:path*` is automatically rewritten to `http://backend:8000/api/:path*`.
+3. **Direct Client Fetching:** Certain client stores (e.g. `cbtStore.ts` and `src/app/cbt/[examId]/page.tsx`) use `NEXT_PUBLIC_API_URL` (default `http://localhost:8000`) for high-throughput examination requests.
+4. **Session Token Enforcement:** `localStorage.getItem("active_session_token")` provides single-device session validation against `/api/users/{id}/session`.
+
+---
+
+## 2. Master Page Directory
+
+| Route URL | Component File Location | Access Level | Primary Backend APIs Called |
+| :--- | :--- | :---: | :--- |
+| `/` | `src/app/page.tsx` | Public | None (Static / Marketing) |
+| `/about` | `src/app/about/page.tsx` | Public | None (Informational) |
+| `/contact` | `src/app/contact/page.tsx` | Public | None (Static Form / Mailto) |
+| `/login` | `src/app/login/page.tsx` | Public | `POST /api/auth/login`, `POST /api/users/{id}/session` |
+| `/signup` | `src/app/signup/page.tsx` | Public | `POST /api/auth/register`, `POST /api/auth/login`, `POST /api/users/{id}/session` |
+| `/forgot-password` | `src/app/forgot-password/page.tsx` | Public | `POST /api/auth/forgot-password` |
+| `/upgrade` | `src/app/upgrade/page.tsx` | Public / Auth | None (Routing to `/checkout?tier=...`) |
+| `/checkout` | `src/app/checkout/page.tsx` | Authenticated | `POST /api/billing/create-order`, `POST /api/billing/verify-payment` |
+| `/cbt/[examId]` | `src/app/cbt/[examId]/page.tsx` | Authenticated | `GET /api/tests/{examId}`, `GET /api/tests/{examId}/questions`, `POST /api/attempts/submit` |
+| `/dashboard` | `src/app/dashboard/page.tsx` | Student (`Free`+) | `GET /api/users/{id}`, `GET /api/ai-coach/study-plan/today`, `GET /api/growth/referral/{id}` |
+| `/dashboard/cbt` | `src/app/dashboard/cbt/page.tsx` | Student (`Free`+) | `GET /api/users/{id}`, `GET /api/tests`, `GET /api/users/{id}/attempts` |
+| `/dashboard/cbt/history/[attemptId]` | `src/app/dashboard/cbt/history/[attemptId]/page.tsx` | Student (`Free`+) | `GET /api/users/{id}/attempts`, `GET /api/tests/{id}`, `GET /api/questions/{id}` |
+| `/dashboard/dpp` | `src/app/dashboard/dpp/page.tsx` | Student (`Free`+) | `GET /api/tests?type=DPS`, `GET /api/users/{id}/attempts` |
+| `/dpp/review/[dppId]` | `src/app/dpp/review/[dppId]/page.tsx` | Student (`Free`+) | Local DPP attempt state & question review |
+| `/dashboard/analytics` | `src/app/dashboard/analytics/page.tsx` | Student (`Free`+) | `GET /api/users/{id}` (Performance graphs & accuracies) |
+| `/dashboard/progress` | `src/app/dashboard/progress/page.tsx` | Student (`Free`+) | `GET /api/og/progress` (Progress card export) |
+| `/dashboard/streaks` | `src/app/dashboard/streaks/page.tsx` | Student (`Free`+) | `GET /api/users/{id}` (Streak count & freeze tokens) |
+| `/dashboard/leaderboard` | `src/app/dashboard/leaderboard/page.tsx` | Student (`Free`+) | Client ranking engine & state filtering |
+| `/dashboard/materials` | `src/app/dashboard/materials/page.tsx` | Student (`Free`+) | Formula sheets repository & PDF downloads |
+| `/dashboard/rank-predictor` | `src/app/dashboard/rank-predictor/page.tsx` | Student (`Free`+) | Percentile-to-AIR calculation engine |
+| `/dashboard/community` | `src/app/dashboard/community/page.tsx` | Student (`Free`+) | Student doubt forum & study channels |
+| `/dashboard/settings` | `src/app/dashboard/settings/page.tsx` | Student (`Free`+) | `GET /api/users/{id}`, `PUT /api/users/{id}`, `POST /api/users/{id}/avatar` |
+| `/dashboard/ai-coach` | `src/app/dashboard/ai-coach/page.tsx` | Student (`AI_COACH`) | `GET /api/ai-coach/readiness/{id}`, `GET /api/growth/referral/{id}` |
+| `/dashboard/ai-coach/tutor` | `src/app/dashboard/ai-coach/tutor/page.tsx` | Student (`AI_COACH`) | `POST /api/ai-coach/chat/stream` (SSE stream) |
+| `/dashboard/ai-coach/study-plan` | `src/app/dashboard/ai-coach/study-plan/page.tsx` | Student (`AI_COACH`) | `GET /api/ai-coach/study-plan/today?user_id={id}` |
+| `/dashboard/ai-coach/readiness` | `src/app/dashboard/ai-coach/readiness/page.tsx` | Student (`AI_COACH`) | `GET /api/ai-coach/readiness/{id}` |
+| `/dashboard/ai-coach/mistakes` | `src/app/dashboard/ai-coach/mistakes/page.tsx` | Student (`AI_COACH`) | `GET /api/mistakes/today?user_id={id}`, `POST /api/mistakes/review` |
+| `/dashboard/ai-coach/cbt-dpp` | `src/app/dashboard/ai-coach/cbt-dpp/page.tsx` | Student (`AI_COACH`) | `GET /api/tests?type=DPS`, `GET /api/users/{id}/attempts` |
+| `/dashboard/ai-coach/cbt-dpp/[id]` | `src/app/dashboard/ai-coach/cbt-dpp/[id]/page.tsx` | Student (`AI_COACH`) | Submits to `/cbt/[examId]` |
+| `/dashboard/ai-coach/cbt-dpp/history/[attemptId]` | `src/app/dashboard/ai-coach/cbt-dpp/history/[attemptId]/page.tsx` | Student (`AI_COACH`) | `GET /api/users/{id}/attempts`, `GET /api/tests/{id}` |
+| `/dashboard/ai-coach/heatmap` | `src/app/dashboard/ai-coach/heatmap/page.tsx` | Student (`AI_COACH`) | Mistake frequency matrix by topic & difficulty |
+| `/dashboard/ai-coach/college-predictor` | `src/app/dashboard/ai-coach/college-predictor/page.tsx` | Student (`AI_COACH`) | `GET /api/ai-coach/readiness/{id}` + College cutoff mapping |
+| `/dashboard/ai-coach/time-optimization` | `src/app/dashboard/ai-coach/time-optimization/page.tsx` | Student (`AI_COACH`) | Time-per-question analysis & speed pace guide |
+| `/dashboard/ai-coach/strategy` | `src/app/dashboard/ai-coach/strategy/page.tsx` | Student (`AI_COACH`) | Exam temperament & question selection strategy |
+| `/dashboard/ai-coach/weekly-progress` | `src/app/dashboard/ai-coach/weekly-progress/page.tsx` | Student (`AI_COACH`) | Weekly AI mastery trajectory |
+| `/admin` | `src/app/admin/page.tsx` | Admin | Real-time system monitoring & KPI metrics |
+| `/admin/students` | `src/app/admin/students/page.tsx` | Admin | `GET /api/admin/students` |
+| `/admin/students/[studentId]` | `src/app/admin/students/[studentId]/page.tsx` | Admin | `GET /api/admin/students/{id}`, `PATCH /api/admin/students/{id}` |
+| `/admin/tests` | `src/app/admin/tests/page.tsx` | Admin | `GET /api/admin/tests`, `PUT /api/admin/tests/{id}/toggle`, `DELETE /api/admin/tests/{id}`, `POST /api/admin/tests/create_manual` |
+| `/admin/questions` | `src/app/admin/questions/page.tsx` | Admin | Global question search & question bank table |
+| `/admin/coupons` | `src/app/admin/coupons/page.tsx` | Admin | `GET /api/admin/coupons`, `POST /api/admin/coupons`, `DELETE /api/admin/coupons/{id}` |
+| `/admin/settings` | `src/app/admin/settings/page.tsx` | Admin | `GET /api/admin/settings`, `POST /api/admin/settings` |
+| `/admin/agents` | `src/app/admin/agents/page.tsx` | Admin | AI Agent orchestration & heartbeat monitor |
+| Policy Pages | `/privacy`, `/terms`, `/refund`, `/cancellation`, `/disclaimer` | Public | Static legal disclosures |
+
+---
+
+## 3. Exhaustive Pagewise UI & API Breakdowns
+
+---
+
+### 3.1 Authentication & Onboarding Pages
+
+#### A. Login Page (`/login`)
+- **File Location:** `src/app/login/page.tsx`
+- **Access Guard:** Public (Redirects authenticated users to `/dashboard` or `/admin`)
+- **UI Components:**
+  - Brand Logo linking to `/`
+  - Email `<input type="email" />`
+  - Password `<input type="password" />` with show/hide password toggle button
+  - "Forgot password?" link to `/forgot-password`
+  - "Sign In" submit button
+  - "Sign up" link to `/signup`
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Show/Hide Password` | Toggles password visibility | `setShowPassword(!showPassword)` |
+  | `Sign In Button` | Submits form, authenticates user | `handleLogin(e)` |
+  | `Forgot password?` | Navigates to password reset | `/forgot-password` |
+  | `Sign up` | Navigates to registration | `/signup` |
+- **APIs Invoked:**
+  1. `POST /api/auth/login`
+     - **Trigger:** On form submit (`handleLogin`)
+     - **Request Body:** `{ "email": "...", "password": "..." }`
+     - **Response:** `{ "success": true, "role": "user" | "admin", "token": "UUID" | "admin" }`
+     - **Side Effects:**
+       - Sets `document.cookie = "auth_token=...; path=/; max-age=2592000; SameSite=Lax"`
+       - Writes `localStorage.setItem("activeUserId", data.token)`
+       - Generates `crypto.randomUUID()` session token and writes `localStorage.setItem("active_session_token", sessionToken)`
+  2. `POST /api/users/{userId}/session`
+     - **Trigger:** Immediately following successful student login
+     - **Request Body:** `{ "session_token": "<random_uuid>" }`
+     - **Response:** `{ "status": "session_registered", ... }`
+     - **Redirect:** `window.location.href = "/admin"` (if admin) or `"/dashboard"` (if student)
+
+---
+
+#### B. Signup Page (`/signup`)
+- **File Location:** `src/app/signup/page.tsx`
+- **Access Guard:** Public
+- **UI Components:**
+  - Name `<input type="text" />`
+  - Email `<input type="email" />`
+  - Password `<input type="password" />`
+  - "Create Account" submit button
+  - "Sign In" link to `/login`
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Create Account Button` | Submits registration | `handleSignup(e)` |
+  | `Sign in Link` | Navigates to login | `/login` |
+- **APIs Invoked:**
+  1. `POST /api/auth/register`
+     - **Trigger:** On form submit
+     - **Request Body:** `{ "name": "...", "email": "...", "password": "..." }`
+     - **Response:** `{ "success": true, "message": "User registered successfully" }`
+  2. `POST /api/auth/login` (Auto-login chaining)
+     - **Trigger:** Immediately upon successful registration
+     - **Request Body:** `{ "email": "...", "password": "..." }`
+     - **Response:** `{ "success": true, "token": "<userId>", "role": "user" }`
+  3. `POST /api/users/{userId}/session`
+     - Registers active session token and redirects to `/dashboard`.
+
+---
+
+#### C. Forgot Password Page (`/forgot-password`)
+- **File Location:** `src/app/forgot-password/page.tsx`
+- **Access Guard:** Public
+- **UI Components:**
+  - Email `<input type="email" />`
+  - "Send Reset Link" button
+  - Success message banner
+  - "Back to login" link
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Send Reset Link` | Dispatches password reset email | `handleReset(e)` |
+  | `Back to login` | Navigates to `/login` | `/login` |
+- **APIs Invoked:**
+  1. `POST /api/auth/forgot-password`
+     - **Trigger:** On form submit
+     - **Request Body:** `{ "email": "student@example.com" }`
+     - **Response:** `{ "message": "If this email is registered, a password reset link has been sent." }`
+
+---
+
+### 3.2 Subscription & Checkout Subsystem
+
+#### A. Pricing & Upgrade Page (`/upgrade`)
+- **File Location:** `src/app/upgrade/page.tsx`
+- **Access Guard:** Public / Authenticated
+- **UI Components:**
+  - Plan selection cards:
+    - **Free Plan:** Basic mocks, limited practice sheets (Default)
+    - **Pro Plan (₹3,499/yr):** Unlimited Full-Syllabus CBT Mocks, Detailed Analytics, Daily DPS
+    - **AI Coach Plan (₹11,999/yr):** Real-time AI Tutor, College Predictor, Spaced Repetition Notebook, Adaptive Daily Study Plans
+  - Feature comparison matrix
+  - FAQ accordion
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Choose Pro` | Navigates to checkout for Pro | `router.push('/checkout?tier=Pro')` |
+  | `Upgrade to AI Coach` | Navigates to checkout for AI Coach | `router.push('/checkout?tier=Al_Coach')` |
+
+---
+
+#### B. Checkout & Payment Page (`/checkout`)
+- **File Location:** `src/app/checkout/page.tsx`
+- **Access Guard:** Authenticated (Redirects to `/login?redirect=/checkout?tier=...` if guest)
+- **UI Components:**
+  - Order summary sidebar (Plan name, subtotal, GST 18%, grand total)
+  - Delivery/Student Address inputs (`Address`, `City`, `Pincode`, `Phone`)
+  - Payment method selector: Razorpay / Cashfree / Stripe
+  - "Proceed to Payment" button with active loader
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Proceed to Payment` | Initiates backend order & triggers Razorpay Modal | `handlePayment()` |
+- **APIs Invoked:**
+  1. `POST /api/billing/create-order?user_id={userId}&plan_tier={tier}`
+     - **Trigger:** On `Proceed to Payment` click
+     - **Request Body:** `{ "gateway": "razorpay" }`
+     - **Response:**
+       ```json
+       {
+         "id": "order_XXXXXXXXXXXXXX",
+         "amount": 1199900,
+         "currency": "INR",
+         "status": "created"
+       }
+       ```
+  2. **Client-Side SDK:** Opens `window.Razorpay(options).open()`
+  3. `POST /api/billing/verify-payment`
+     - **Trigger:** Razorpay `handler(response)` callback upon payment approval
+     - **Request Body:**
+       ```json
+       {
+         "gateway": "razorpay",
+         "razorpay_order_id": "order_XXXXXX",
+         "razorpay_payment_id": "pay_XXXXXX",
+         "razorpay_signature": "signature_hash",
+         "user_id": "<userId>",
+         "tier": "Al_Coach"
+       }
+       ```
+     - **Response:** `{ "status": "success", "tier": "Al_Coach" }`
+     - **Action on Success:** Updates local user tier and redirects to `/dashboard?payment=success`.
+
+---
+
+### 3.3 Computer-Based Testing (CBT) Examination Engine
+
+#### A. Full-Screen CBT Examination Room (`/cbt/[examId]`)
+- **File Location:** `src/app/cbt/[examId]/page.tsx`
+- **Access Guard:** Authenticated (`Free`, `Pro`, or `AI_COACH` depending on test gating)
+- **UI Components:**
+  - Header: Candidate Name, Photo, Roll Number, Exam Title, Section Switcher (`Physics`, `Chemistry`, `Mathematics` or `Biology`)
+  - Floating Exam Timer (Hours : Minutes : Seconds) with visual alert when under 5 minutes
+  - Question Palette Matrix (Grid 1 to N with NTA standard colors: Green=Answered, Purple=Marked for Review, Red=Unanswered, Grey=Not Visited)
+  - Question Panel: Question Text (KaTeX LaTeX rendering), Image Diagram from MinIO, Multiple Choice Options (`A`, `B`, `C`, `D`) or Numerical Input box
+  - Action Bar:
+    - "Save & Next" button
+    - "Clear Response" button
+    - "Mark for Review & Next" button
+    - "Submit Test" button
+  - Submit Confirmation Modal: Summary table of Answered, Unanswered, Marked for Review questions
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | State / Store Handler |
+  | :--- | :--- | :--- |
+  | `Option Selection (A/B/C/D)` | Selects radio answer | `saveAnswer(questionId, optionKey)` |
+  | `Numerical Input Change` | Enters integer/decimal answer | `saveAnswer(questionId, value)` |
+  | `Save & Next` | Commits answer and advances index | `handleNextQuestion()` |
+  | `Clear Response` | Resets current question answer | `clearAnswer(questionId)` |
+  | `Mark for Review & Next` | Sets flagged review state and advances | `markForReview(questionId)` |
+  | `Question Palette Button [i]` | Direct jump to question index `i` | `setCurrentIndex(i)` |
+  | `Section Tab Switcher` | Filters question palette by Subject | `setActiveSection(sectionName)` |
+  | `Submit Test Button` | Opens final confirmation dialog | `setIsSubmitModalOpen(true)` |
+  | `Confirm Final Submission` | Dispatches submission payload | `submitAttemptToServer(userId)` |
+- **APIs Invoked:**
+  1. `GET /api/tests/{examId}?user_id={userId}`
+     - **Trigger:** On mount (`useEffect`)
+     - **Response:** Test metadata, sections mapping, total duration, question ID sequence.
+  2. `GET /api/tests/{examId}/questions`
+     - **Trigger:** On mount immediately following test metadata
+     - **Response:** Array of full question objects (LaTeX text, options, subject, topic).
+  3. `POST /api/attempts/submit`
+     - **Trigger:** On manual submission confirm OR auto-submit on countdown timeout
+     - **Request Body (`src/store/cbtStore.ts`):**
+       ```json
+       {
+         "test_id": "<examId>",
+         "user_id": "<userId>",
+         "time_spent": 10420,
+         "answers": [
+           {
+             "question_id": "<qId>",
+             "selected_option": "B",
+             "time_spent": 115,
+             "is_marked_for_review": false
+           }
+         ],
+         "status": "Submitted"
+       }
+       ```
+     - **Response:**
+       ```json
+       {
+         "id": "<attemptId>",
+         "score": 240,
+         "total_questions": 75,
+         "accuracy": 82.5,
+         "rank": 412
+       }
+       ```
+     - **Redirect:** Navigates directly to `/dashboard/cbt/history/{attemptId}`.
+
+---
+
+#### B. CBT Mock Directory Hub (`/dashboard/cbt`)
+- **File Location:** `src/app/dashboard/cbt/page.tsx`
+- **Access Guard:** Authenticated (`Free`+)
+- **UI Components:**
+  - Exam Filter Tabs: `All`, `JEE Main`, `JEE Advanced`, `NEET`
+  - Active Full Mocks Grid (Test Card: Title, Pattern badge, Total Questions, Time limit, Attempts count, "Start Test" or "Review" button)
+  - Recent Attempts History Table (Exam Title, Score, Accuracy, Date, "View Solution" button)
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Exam Filter Tabs` | Filters active tests by pattern | `setSelectedPattern(pattern)` |
+  | `Start Test Button` | Navigates into full-screen exam room | `router.push('/cbt/' + test.id)` |
+  | `View Solution Button` | Navigates to detailed attempt analysis | `router.push('/dashboard/cbt/history/' + attempt.id)` |
+- **APIs Invoked:**
+  1. `GET /api/users/{userId}` (Fetches user's targeted exam e.g. `JEE_MAIN`)
+  2. `GET /api/tests?user_id={userId}&exam_pattern={pattern}` (Lists available mock tests)
+  3. `GET /api/users/{userId}/attempts` (Fetches historical attempt records)
+
+---
+
+#### C. Test Attempt Analysis & Solution Review (`/dashboard/cbt/history/[attemptId]`)
+- **File Location:** `src/app/dashboard/cbt/history/[attemptId]/page.tsx`
+- **Access Guard:** Authenticated
+- **UI Components:**
+  - Score summary card: Final Score, Total Marks, Accuracy %, Positive Marks, Negative Marks, Percentile
+  - Question-by-question breakdown list:
+    - Status badge: Correct (+4), Incorrect (-1), Unattempted (0)
+    - Full LaTeX question rendering
+    - Student's chosen answer vs Official Correct Answer
+    - Step-by-step text solution
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Filter by Subject (All/Phys/Chem/Math)` | Filters questions | `setSelectedSubject(sub)` |
+  | `Filter by Status (Incorrect/Correct)` | Isolates student errors | `setStatusFilter(filter)` |
+  | `Back to Test Directory` | Navigates back | `/dashboard/cbt` |
+- **APIs Invoked:**
+  1. `GET /api/users/{userId}/attempts` (Locates `attemptId`)
+  2. `GET /api/tests/{source_id}?user_id={userId}` (Fetches test structure)
+  3. `GET /api/questions/{questionId}` (Fetches detailed solutions per question)
+
+---
+
+#### D. Daily Practice Sheets (DPS / DPP) Test Center (`/dashboard/dpp`)
+- **File Location:** `src/app/dashboard/dpp/page.tsx`
+- **Access Guard:** Authenticated (`Free`+ with tiered limits)
+- **UI Components:**
+  - Daily Sheets Calendar / Carousel:
+    - Biology Ch4 DPS
+    - Chemistry Ch4 DPS
+    - Mathematics Ch4 DPS
+    - Physics Ch4 DPS
+  - Sheet Status: `Pending` | `Completed` (with Score & Accuracy)
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Solve DPS Button` | Launches CBT engine for that practice sheet | `router.push('/cbt/' + sheet.id)` |
+  | `Review Solution Button` | Opens attempt breakdown | `router.push('/dashboard/cbt/history/' + attempt.id)` |
+- **APIs Invoked:**
+  1. `GET /api/tests?type=DPS&exam_pattern={pattern}` (Fetches seeded DPS tests)
+  2. `GET /api/users/{userId}/attempts` (Checks which DPS sheets have been completed)
+
+---
+
+### 3.4 Student Dashboard & Core Learning Hub
+
+#### A. Main Student Dashboard (`/dashboard`)
+- **File Location:** `src/app/dashboard/page.tsx`
+- **Access Guard:** Authenticated (`Free`+)
+- **UI Components:**
+  - Header: Welcome message, Active Target Exam (`JEE Main` / `NEET`), Streak Badge
+  - Performance Overview Grid: Tests Taken, Average Accuracy %, Study Streak, Target Score
+  - Embedded Adaptive Study Plan Card (`AdaptiveStudyPlan.tsx`)
+  - Embedded Mistake Heatmap Card (`MistakeHeatmap.tsx`)
+  - Embedded Viral Referral Card (`ReferralCard.tsx`)
+  - "Share Card" Button (Generates and downloads high-res progress PNG via `html-to-image`)
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Share Card Button` | Exports dashboard card as PNG | `handleExport()` (`html-to-image`) |
+  | `Start Today's DPS` | Launches daily practice | `/dashboard/dpp` |
+  | `Explore AI Coach` | Navigates to AI features | `/dashboard/ai-coach` |
+- **APIs Invoked:**
+  1. `GET /api/users/{userId}` via `useActiveUser()`
+  2. `GET /api/ai-coach/study-plan/today?user_id={userId}` (via `AdaptiveStudyPlan`)
+  3. `GET /api/growth/referral/{userId}` (via `ReferralCard`)
+
+---
+
+#### B. Student Profile & Settings Page (`/dashboard/settings`)
+- **File Location:** `src/app/dashboard/settings/page.tsx`
+- **Access Guard:** Authenticated
+- **UI Components:**
+  - Avatar Profile Picture with MinIO upload button
+  - Personal Information Form: First Name, Last Name, Email (read-only), Target Exam selector (`JEE Main`, `JEE Advanced`, `NEET`), School, State
+  - "Save Changes" button
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Avatar File Upload Input` | Uploads image directly to MinIO | `handleAvatarUpload(e)` |
+  | `Save Changes Button` | Updates student profile | `handleSave()` |
+- **APIs Invoked:**
+  1. `POST /api/users/{userId}/avatar`
+     - **Trigger:** On file input change
+     - **Request Form-Data:** `file: <binary_image>`
+     - **Response:** `{ "url": "http://localhost:9000/avatars/user_avatar_....png" }`
+  2. `PUT /api/users/{userId}`
+     - **Trigger:** On `Save Changes` click
+     - **Request Body:**
+       ```json
+       {
+         "name": "Rahul Sharma",
+         "target_exam": "JEE_MAIN",
+         "school": "Delhi Public School",
+         "state": "Delhi"
+       }
+       ```
+     - **Response:** Updated user record.
+
+---
+
+### 3.5 AI Coach Suite (`/dashboard/ai-coach/*`)
+
+> **Access Restriction:** All pages in this section are gated to `tier == "Al_Coach"`. Users on `Free` or `Pro` tiers see an upgrade paywall with a direct link to `/checkout?tier=Al_Coach`.
+
+#### A. AI Doubt Solver & Tutor Chat (`/dashboard/ai-coach/tutor`)
+- **File Location:** `src/app/dashboard/ai-coach/tutor/page.tsx` & `src/components/AI/TutorChat.tsx`
+- **Access Guard:** `AI_COACH` Tier
+- **UI Components:**
+  - Real-time chat message history (User messages in brand cyan, AI Tutor responses formatted in Markdown + KaTeX LaTeX equations)
+  - Chat `<input />` with send button and typing indicator
+  - Quick Suggestion Chips: *"Explain Photoelectric Effect"*, *"Solve JEE 2024 Math Integration"*, *"Give me a 3-step revision plan"*
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Send Message Button` | Submits doubt to streaming API | `sendMessage(text)` |
+  | `Suggestion Chips` | Populates input with prompt | `setInput(chipText)` |
+- **APIs Invoked:**
+  1. `POST /api/ai-coach/chat/stream`
+     - **Trigger:** On sending a message
+     - **Request Headers:** `Content-Type: application/json`, `Accept: text/event-stream`
+     - **Request Body:** `{ "user_id": "<userId>", "message": "Explain Lenz's Law" }`
+     - **Response Stream:** `text/event-stream; charset=utf-8` (Server-Sent Events)
+     - **Phase 2 Status:** Intentionally stubbed with friendly coming-soon notice to decouple from external LLM providers during initial launch.
+
+---
+
+#### B. Spaced Repetition Mistake Notebook (`/dashboard/ai-coach/mistakes`)
+- **File Location:** `src/app/dashboard/ai-coach/mistakes/page.tsx`
+- **Access Guard:** `AI_COACH` Tier
+- **UI Components:**
+  - Daily Mistake Card Queue: Displays questions that the student answered incorrectly in previous CBT exams, scheduled for revision today using the SuperMemo-2 (SM-2) algorithm.
+  - Interactive Answer Selector (`A`, `B`, `C`, `D`)
+  - "Submit Answer" button
+  - Post-submission Feedback Panel: Immediate correctness status, explanation, and new scheduled review interval (e.g. *"Reviewed! Next review in 6 days"*).
+  - "Next Question" button
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Select Answer (A/B/C/D)` | Selects answer option | `setSelectedOption(opt)` |
+  | `Submit Answer Button` | Submits review and updates SM-2 interval | `submitReview(mistakeId, option)` |
+  | `Next Question Button` | Advances to next queued mistake | `handleNext()` |
+- **APIs Invoked:**
+  1. `GET /api/mistakes/today?user_id={userId}`
+     - **Trigger:** On page mount
+     - **Response:** Array of pending mistake objects where `next_review <= NOW()`.
+  2. `POST /api/mistakes/review`
+     - **Trigger:** On `Submit Answer` click
+     - **Request Body:** `{ "mistake_id": "<mistakeId>", "selected_answer": "B" }`
+     - **Response:**
+       ```json
+       {
+         "status": "reviewed",
+         "is_correct": true,
+         "interval": 6,
+         "next_review": "2026-09-15T00:00:00Z"
+       }
+       ```
+
+---
+
+#### C. Exam Readiness & College Predictor (`/dashboard/ai-coach/readiness` & `/college-predictor`)
+- **File Location:** `src/app/dashboard/ai-coach/readiness/page.tsx`, `college-predictor/page.tsx`, `ReadinessGauge.tsx`, `CollegePredictorCard.tsx`
+- **Access Guard:** `AI_COACH` Tier
+- **UI Components:**
+  - Circular SVG Exam Readiness Gauge (0–100%)
+  - Readiness Breakdown: Accuracy Score, Time Management Score, Consistency Score, Topic Coverage
+  - AI College Predictor Card: Predicted Rank, Eligible IIT/NIT/AIIMS colleges based on historical cutoffs (Safe, Probable, Reach)
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Recalculate Score Button` | Refetches latest readiness calculation | `fetchReadiness()` |
+  | `Explore College Cutoffs` | Expands category details | `setCategoryFilter(...)` |
+- **APIs Invoked:**
+  1. `GET /api/ai-coach/readiness/{userId}`
+     - **Trigger:** On mount
+     - **Response:**
+       ```json
+       {
+         "readiness_score": 78,
+         "predicted_rank": 3420,
+         "confidence_interval": "± 400",
+         "subject_breakdown": {
+           "Physics": 82,
+           "Chemistry": 85,
+           "Mathematics": 67
+         }
+       }
+       ```
+
+---
+
+#### D. Adaptive Daily Study Plan (`/dashboard/ai-coach/study-plan`)
+- **File Location:** `src/app/dashboard/ai-coach/study-plan/page.tsx` & `src/components/AI/StudyPlanCard.tsx`
+- **Access Guard:** `AI_COACH` Tier
+- **UI Components:**
+  - Daily Study Plan Task List: Revision Target, Practice Target, Test Recommendation
+  - Task checkboxes to mark tasks as completed
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Task Checkbox` | Marks daily task complete | Local task state |
+  | `Start Recommended Task` | Deep-links to relevant test or DPS | `/dashboard/dpp` |
+- **APIs Invoked:**
+  1. `GET /api/ai-coach/study-plan/today?user_id={userId}`
+     - **Trigger:** On mount
+     - **Response:** Daily plan JSON generated by Celery Beat at 5:00 AM IST.
+
+---
+
+### 3.6 Admin Management Console (`/admin/*`)
+
+> **Access Restriction:** Protected by `proxy.ts` (Requires `auth_token=admin` cookie). Non-admin users are immediately redirected to `/login`.
+
+#### A. Command Center Overview (`/admin`)
+- **File Location:** `src/app/admin/page.tsx`
+- **Access Guard:** Admin Only
+- **UI Components:**
+  - KPI Stat Cards: Total Revenue, Active Students, AI Agent Accuracy %, Total Questions
+  - System Health & Accuracy Area Chart (`recharts`)
+  - Quick Action Buttons: "Refresh Data", "Create Test", "Manage Students"
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Refresh Data Button` | Triggers refetch of dashboard metrics | `fetchDashboardData()` |
+  | `Create Test Quick Link` | Navigates to Test Management | `/admin/tests` |
+
+---
+
+#### B. Student Directory & Profile Control (`/admin/students` & `[studentId]`)
+- **File Location:** `src/app/admin/students/page.tsx` and `src/app/admin/students/[studentId]/page.tsx`
+- **Access Guard:** Admin Only
+- **UI Components:**
+  - Students Directory Table: Name, Email, Target Exam, Class, Tier Badge (`Free`/`Pro`/`AI Coach`), Streak, Actions
+  - Search & Filter Bar: Filter by Exam (`JEE Main` / `NEET`) or Tier
+  - Detail Page (`[studentId]`):
+    - Full Profile Card
+    - Tier Override Selector (`Free` -> `Pro` -> `Al_Coach`)
+    - "Update Tier" button
+    - "Reset Streak" button
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `View Student Row` | Navigates to individual student control | `router.push('/admin/students/' + student.id)` |
+  | `Update Tier Button` | Changes student subscription tier | `handleTierUpdate(newTier)` |
+  | `Reset Streak Button` | Resets student streak counter to 0 | `handleResetStreak()` |
+- **APIs Invoked:**
+  1. `GET /api/admin/students` (Lists all student accounts)
+  2. `GET /api/admin/students/{studentId}` (Fetches single student record)
+  3. `PATCH /api/admin/students/{studentId}`
+     - **Trigger:** On tier change or profile update
+     - **Request Body:** `{ "tier": "Al_Coach" }`
+     - **Response:** Updated student record.
+
+---
+
+#### C. Test & DPS Management Center (`/admin/tests`)
+- **File Location:** `src/app/admin/tests/page.tsx`
+- **Access Guard:** Admin Only
+- **UI Components:**
+  - Active Tests Table: Title, Exam Pattern, Total Time, Scheduled Date, Active Switch toggle, Delete button
+  - Manual Test Creation Form / JSON Drag-and-Drop Uploader:
+    - Test Title `<input />`
+    - Exam Pattern selector (`JEE_MAIN`, `JEE_ADVANCED`, `NEET`)
+    - Test Type selector (`Mock`, `DPS`)
+    - Time Limit `<input />` (minutes)
+    - JSON Question File Uploader (Validates question schema: `question_text`, `options`, `correct_answer`, `subject`, `topic`)
+    - "Create Test" button
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Active Toggle Switch` | Toggles test visibility to students | `handleToggle(testId)` |
+  | `Delete Test Button` | Permanently deletes test and its questions | `handleDelete(testId)` |
+  | `JSON File Drop Zone` | Parses and validates questions JSON | `processFile(file)` |
+  | `Create Test Button` | Dispatches manual test creation | `handleCreateTest()` |
+- **APIs Invoked:**
+  1. `GET /api/admin/tests`
+     - **Trigger:** On mount
+     - **Response:** Array of all existing tests.
+  2. `PUT /api/admin/tests/{testId}/toggle`
+     - **Trigger:** On switch toggle
+     - **Response:** `{ "status": "toggled", "is_active": true|false }`
+  3. `DELETE /api/admin/tests/{testId}`
+     - **Trigger:** On delete confirm
+     - **Response:** `{ "status": "deleted" }`
+  4. `POST /api/admin/tests/create_manual`
+     - **Trigger:** On `Create Test` submit
+     - **Request Body:**
+       ```json
+       {
+         "title": "JEE Main Physics Final Mock",
+         "type": "Mock",
+         "exam_pattern": "JEE_MAIN",
+         "time_limit": 180,
+         "admin_id": "<adminId>",
+         "questions_json": [ ... ]
+       }
+       ```
+     - **Response:** `{ "status": "created", "test_id": "<uuid>", "questions_count": 75 }`
+
+---
+
+#### D. Coupon Management (`/admin/coupons`)
+- **File Location:** `src/app/admin/coupons/page.tsx`
+- **Access Guard:** Admin Only
+- **UI Components:**
+  - Active Coupons Table: Code, Discount %, Max Discount Amount, Status, Delete button
+  - New Coupon Creation Card: Code input, Discount percentage input, Max discount input, "Create Coupon" button
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Create Coupon Button` | Submits new coupon | `handleCreate()` |
+  | `Delete Coupon Button` | Deletes discount coupon | `handleDelete(couponId)` |
+- **APIs Invoked:**
+  1. `GET /api/admin/coupons` (Fetches active coupons list)
+  2. `POST /api/admin/coupons`
+     - **Request Body:** `{ "code": "PRAGATI50", "discount_percent": 50, "max_discount_amount": 2000 }`
+  3. `DELETE /api/admin/coupons/{id}` (Deletes coupon)
+
+---
+
+#### E. Global Platform Settings (`/admin/settings`)
+- **File Location:** `src/app/admin/settings/page.tsx`
+- **Access Guard:** Admin Only
+- **UI Components:**
+  - Maintenance Mode Switch
+  - Free Test Quota `<input />` (Number of free mock tests allowed before paywall)
+  - Allow Registrations Switch
+  - "Save Settings" button
+- **Buttons & Interactive Elements:**
+  | Button / Trigger | Action | Target / Handler |
+  | :--- | :--- | :--- |
+  | `Save Settings Button` | Persists global configuration | `handleSaveSettings()` |
+- **APIs Invoked:**
+  1. `GET /api/admin/settings` (Fetches current settings)
+  2. `POST /api/admin/settings`
+     - **Request Body:** `{ "maintenance_mode": false, "free_test_limit": 2, "allow_registrations": true }`
+
+---
+
+## 4. Master Button-to-API Cross Reference Matrix
+
+| Button / UI Element | Page Location | Trigger Type | HTTP Method & Endpoint | Payload / Parameters |
+| :--- | :--- | :--- | :--- | :--- |
+| **Sign In** | `/login` | Form Submit | `POST /api/auth/login` | `{ email, password }` |
+| **Register & Login** | `/signup` | Form Submit | `POST /api/auth/register` | `{ name, email, password }` |
+| **Reset Password** | `/forgot-password` | Form Submit | `POST /api/auth/forgot-password` | `{ email }` |
+| **Proceed to Payment** | `/checkout` | User Click | `POST /api/billing/create-order` | Query: `?user_id=...&plan_tier=...` |
+| **Razorpay Verification** | `/checkout` | SDK Callback | `POST /api/billing/verify-payment` | `{ razorpay_order_id, razorpay_payment_id, ... }` |
+| **Start CBT Exam** | `/dashboard/cbt` | Navigation | `GET /api/tests/{examId}` | Query: `?user_id=...` |
+| **Fetch Questions** | `/cbt/[examId]` | Page Mount | `GET /api/tests/{examId}/questions` | Path: `{examId}` |
+| **Final Submit Exam** | `/cbt/[examId]` | Modal Confirm | `POST /api/attempts/submit` | `{ test_id, user_id, answers, ... }` |
+| **Submit Mistake Review** | `/dashboard/ai-coach/mistakes` | User Click | `POST /api/mistakes/review` | `{ mistake_id, selected_answer }` |
+| **Send AI Doubt** | `/dashboard/ai-coach/tutor` | Form Submit | `POST /api/ai-coach/chat/stream` | `{ user_id, message }` |
+| **Upload Avatar** | `/dashboard/settings` | File Input | `POST /api/users/{id}/avatar` | Form-Data: `file: <image>` |
+| **Save Profile** | `/dashboard/settings` | User Click | `PUT /api/users/{id}` | `{ name, target_exam, school, state }` |
+| **Toggle Test Status** | `/admin/tests` | Switch Toggle | `PUT /api/admin/tests/{id}/toggle` | Path: `{id}` |
+| **Delete Test** | `/admin/tests` | Button Click | `DELETE /api/admin/tests/{id}` | Path: `{id}` |
+| **Create Manual Test** | `/admin/tests` | Form Submit | `POST /api/admin/tests/create_manual` | `{ title, exam_pattern, questions_json, ... }` |
+| **Update Student Tier** | `/admin/students/[id]` | Dropdown Change | `PATCH /api/admin/students/{id}` | `{ tier: "Al_Coach" }` |
+| **Create Coupon** | `/admin/coupons` | Form Submit | `POST /api/admin/coupons` | `{ code, discount_percent, ... }` |
+| **Delete Coupon** | `/admin/coupons` | Button Click | `DELETE /api/admin/coupons/{id}` | Path: `{id}` |
+| **Save Admin Settings** | `/admin/settings` | User Click | `POST /api/admin/settings` | `{ maintenance_mode, free_test_limit, ... }` |
+
+---
+
+## 5. Codebase Cleanup Audit & Phase 2 Roadmap
+
+### 5.1 Cleaned & Removed Legacy Files
+In accordance with production standards, the following 10 dead/legacy files and temporary development artifacts have been hard-deleted:
+- `backend/fix.py`: One-time script for manual LaTeX question corrections.
+- `backend/fix_from_source.py`: One-time PDF extraction script.
+- `backend/fix_ions.py`: One-time chemical formula fixer.
+- `backend/seed_dpps.py`: Legacy DPS script using PyMuPDF and OpenAI.
+- `backend/seed_dpps_mock.py`: Obsolete mock DPS generator.
+- `backend/seed_dpps_real.py`: Obsolete duplicate DPS script.
+- `backend/seed_from_dpps.py`: Redundant seeder variant.
+- `backend/pragativeer-prd.pdf`: Product Requirements Document binary removed from backend.
+- `backend/pragativeer.db`: Abandoned SQLite file (PragatiVeer exclusively uses PostgreSQL).
+- `backend/test.pdf` & `backend/test2.pdf`: Temporary test PDFs.
+
+### 5.2 Decoupled Dependencies (`requirements.txt`)
+The following heavy external packages were removed from `backend/requirements.txt`:
+- `openai==1.14.0`: Decoupled to eliminate reliance on external LLM keys during initial rollout.
+- `PyMuPDF==1.23.26`: Decoupled to prevent native C-library compile overhead in production.
+
+### 5.3 Stubbed Modules for Phase 2 AI Integration
+- `backend/llm.py`: Cleanly stubbed with an async generator returning a friendly coming-soon notice.
+- `backend/pdf_parser.py`: Cleanly stubbed with an empty list return.
+- `backend/worker.py`: Cleaned to retain exclusively the active 5:00 AM IST Celery Beat daily study plan scheduler.
+- `POST /api/admin/tests/upload`: Returns a structured message directing administrators to use `/api/admin/tests/create_manual` until Phase 2 is provisioned.
+
+---
+
+*Document compiled and verified for PragatiVeer v2 — Production Release*