125 lines
6.6 KiB
Markdown
125 lines
6.6 KiB
Markdown
# 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 & Parent Systems**
|
|
- `GET/POST/PUT/DELETE /api/admin/*` - Full CRUD for Tests, Users, Coupons, and System Settings
|
|
- `POST /api/parent/register` - Parent account creation
|
|
- `POST /api/parent/link-student` - Link student to parent dashboard
|
|
|
|
## 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.
|