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

• POST /api/auth/register - Create new student account
• POST /api/auth/login - Authenticate & receive JWT session
• POST /api/auth/forgot-password - Request password reset link
• POST /api/auth/otp-request / otp-verify - Phone number authentication

Users & Profiles

• GET/PUT /api/users/{id} - Fetch/update user profiles and settings
• POST /api/users/{id}/avatar - Upload profile picture to MinIO
• GET /api/users/{id}/attempts - Retrieve past test history

CBT Engine

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

AI Coach

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

Subscription & Billing (Gateway Agnostic)

• POST /api/billing/create-order - Generate payment gateway order IDs
• POST /api/billing/verify-payment - Cryptographically verify webhooks and upgrade tier

Admin System

• GET/POST/PUT/DELETE /api/admin/* - Full CRUD for Tests, Users, Coupons, and System Settings

Parent System (Planned / UI Mocked)

• Note: The UI exists at /parent/dashboard but currently uses fallback mock data. Backend APIs are not yet built.
• [Planned] POST /api/parent/register - Parent account creation
• [Planned] POST /api/parent/link-student - Link student to parent dashboard
• [Planned] GET /api/parent/{parent_id}/dashboard/{student_id} - Fetch real-time student analytics

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.