# 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 Free, Pro, and AI Coach tiers, dynamically unlocking features.
- **Glassmorphism UI:** Modern, premium aesthetics with light/dark theme support.
- **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.

## 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.