pragativeer-v2/PRD.md

# PragatiVeer v2 - Product Requirements Document (PRD) & Architecture

## 1. Product Overview
**PragatiVeer** is a next-generation, AI-powered daily practice platform and mock testing engine designed specifically for **JEE and NEET aspirants**. The platform offers a highly adaptive learning experience by integrating a CBT (Computer Based Test) engine, dynamic Daily Practice Problems (DPPs), and an AI Coach that tailors study plans, analyzes mistakes, and tracks syllabus progress.

## 2. Core Objectives
- Deliver a robust, scalable CBT engine simulating real exam environments for JEE and NEET.
- Provide AI-driven mistake tracking and spaced repetition to ensure long-term retention.
- Generate personalized study strategies, college predictions, and time-optimization techniques.
- Offer gamification (streaks, leaderboards, tier-based access) to enhance student engagement.

## 3. Architecture & Infrastructure
The application follows a modern decoupled architecture, containerized entirely via Docker, ensuring reproducibility and scalability.

### 3.1 Container Architecture (Docker Compose)
The stack is orchestrated using `docker-compose.yml` and consists of 8 distinct containers:

1. **pragativeer_frontend (Frontend App)**
   - **Framework:** Next.js (React), TailwindCSS, TypeScript.
   - **Role:** Renders the user interface, dashboards, and CBT interface. Communicates with the backend API.
   - **Port:** `3000`

2. **pragativeer_backend (FastAPI Backend)**
   - **Framework:** FastAPI (Python 3.11), SQLModel/Pydantic.
   - **Role:** Handles core business logic, API routing, authentication (JWT), and AI orchestrations (OpenAI).
   - **Port:** `8000`

3. **pragativeer_db (PostgreSQL Database)**
   - **Engine:** PostgreSQL 15 (Alpine).
   - **Role:** Primary persistent data storage for users, questions, test attempts, streaks, and analytics.
   - **Volume:** `pgdata` (Persistent)
   - **Port:** `5432`

4. **pragativeer_pgbouncer (PgBouncer)**
   - **Engine:** PgBouncer.
   - **Role:** Lightweight connection pooler for PostgreSQL, ensuring the database is not overwhelmed by high connection counts during peak exam periods.

5. **pragativeer_cache (Redis)**
   - **Engine:** Redis 7 (Alpine).
   - **Role:** High-speed in-memory cache for API responses, leaderboard rankings, and serves as the message broker for Celery background tasks.
   - **Volume:** `redisdata` (Persistent)
   - **Port:** `6379`

6. **pragativeer_worker (Celery Worker)**
   - **Engine:** Celery (Python).
   - **Role:** Processes heavy asynchronous background tasks asynchronously (e.g., generating AI responses, processing bulk exam analytics, sending emails) without blocking the main API threads.

7. **pragativeer_beat (Celery Beat)**
   - **Engine:** Celery Beat.
   - **Role:** The scheduler for periodic background jobs (e.g., nightly streak calculations, automated weekly progress report generation, DB cleanup).

8. **pragativeer_storage (MinIO)**
   - **Engine:** MinIO (S3-compatible object storage).
   - **Role:** Handles unstructured data storage, such as user profile pictures, uploaded question diagrams, and PDF exports.
   - **Volume:** `miniodata` (Persistent)
   - **Ports:** `9000` (API), `9001` (Console)

## 4. Key Features & Modules

### 4.1 Dashboard & Navigation
- **Tier-based Access:** Users are segmented into **Pro** and **AI Coach** tiers, dynamically unlocking premium features and AI-driven capabilities.
- **Glassmorphism UI:** Modern, premium aesthetics featuring glowing active states with light/dark theme support (Gold for Pro, Teal for AI Coach).
- **Top Header:** Target exam badges (JEE/NEET), current active streak counters, and profile drop-downs.

### 4.2 AI Coach Ecosystem
- **AI Tutor:** Real-time conversational AI for doubt resolution (OpenAI integration).
- **PrepPilot AI:** Adaptive target DPP generation based on current weak areas.
- **Mistake Analyzer (AI Powered):** Tracks incorrect answers and utilizes AI-powered spaced repetition to resurface them at optimal intervals.
- **Exam Readiness & College Predictor:** Data-driven predictions based on historical CBT scores.
- **AI Study Plan & Time Optimization:** Custom schedules generated dynamically for the user.

### 4.3 Testing & Analytics (CBT Engine)
- **Mock Tests:** Full-length simulations matching exact NTA (National Testing Agency) UI patterns.
- **Syllabus Tracker:** Granular chapter-by-chapter completion tracking.
- **Performance Analytics:** Visual charts tracking accuracy, speed, and subject-wise competence.

### 4.4 Comprehensive API Endpoints
The backend exposes the following RESTful APIs powered by FastAPI:

**Authentication**
- `[Built] POST /api/auth/register` - Create new student account
- `[Built] POST /api/auth/login` - Authenticate & receive JWT session
- `[Built] POST /api/auth/forgot-password` - Request password reset link
- `[Planned] POST /api/auth/otp-request` / `otp-verify` - Phone number authentication

**Users & Profiles**
- `[Built] GET/PUT /api/users/{id}` - Fetch/update user profiles and settings
- `[Planned] POST /api/users/{id}/avatar` - Upload profile picture to MinIO
- `[Built] GET /api/users/{id}/attempts` - Retrieve past test history

**CBT Engine**
- `[Built] GET /api/tests` - List active Mock Tests, PYQs, and Weekly Tests
- `[Built] GET /api/tests/{id}/questions` - Fetch test sections and questions
- `[Built] POST /api/attempts/submit` - Auto-grade and record a CBT session

**AI Coach**
- `[Planned] GET /api/ai-coach/readiness/{id}` - Predict JEE/NEET rank and college
- `[Planned] GET /api/ai-coach/study-plan/today` - Generate daily tasks
- `[Planned] GET /api/mistakes/today` - Fetch spaced repetition flashcards (SM-2 algorithm)
- `[Planned] POST /api/mistakes/review` - Update mistake mastery based on recall
- `[Built] POST /api/ai-coach/chat/stream` - AI Tutor socket connection

**Subscription & Billing (Gateway Agnostic)**
- `[Built] POST /api/billing/create-order` - Generate payment gateway order IDs
- `[Built] POST /api/billing/verify-payment` - Cryptographically verify webhooks and upgrade tier

**Admin System**
- `[Built] GET/POST/PUT/DELETE /api/admin/*` - Full CRUD for Tests, Users, Coupons, and System Settings

## 5. Technology Stack Summary
- **Frontend:** Next.js 14/15, TailwindCSS, Framer Motion, Lucide Icons, Shadcn UI.
- **Backend:** Python 3.11, FastAPI, Uvicorn.
- **Database ORM:** SQLModel (SQLAlchemy).
- **AI Integration:** OpenAI API.
- **Background Tasks:** Celery + Redis.
- **Storage:** MinIO, Boto3.
- **DevOps:** Docker, Docker Compose.

## 6. Future Scope
- Expand AI capabilities for voice-based doubt resolution.
- Introduce real-time multiplayer mock test battles.
- Deeper parent-dashboard integrations for performance tracking.