Platform guide · for engineers, admins and technical partners
How MockPrepAI works under the hood
Who uses it, every feature area, the exam and institute flows, the architecture and data model, and how it ships to production, with diagrams and real screens.
01 · Overview
An online mock-exam platform for Indian competitive exams
Aspirants take full-length timed papers that follow the official syllabus and marking scheme, then get a scored breakdown, a notebook of their mistakes and targeted drills. Coaching institutes run their own proctored exam sessions for their batches on the same engine.
Screens in the web app
API endpoints
Database tables
Automated tests
208 backend · 121 end-to-end
Seeded exam
Kerala PSC LDC 2026–27
- Questions
- 100
- Duration
- 75 min
- Correct
- +1.00
- Wrong
- −0.33
The platform is multi-exam: UPSC, SSC, Banking, Railways and state PSCs can each be configured with their own sections, blueprint and marking. It runs at mockprepai.in (web app) and api.mockprepai.in (API), in English and Malayalam, with light, soft and dark themes.
02 · Who uses it
Three audiences, one engine
Every account has a platform role. Institute members also have an institute role, which is separate: a student of a coaching centre is an ordinary candidate account linked to that institute.
Candidates
Aspirant · Pro aspirant
Practise, review and track progress.
Coaching institutes
Institute admin · Content manager · Exam controller · Student
Run branded, proctored exams for batches.
MockPrepAI team
Content editor · Exam manager · Admin · Super admin
Build exams, manage accounts and the platform.
| Platform role | What it can do |
|---|---|
| Aspirant | Browse exams, take mocks, results and history, mistake notebook, saved questions, analytics and Mock Duels. Limited to each exam's free-mock quota unless Pro or the exam bundle is owned. |
| Content editor | Backoffice access: edit mock-exam questions, upload documents, list and resolve reported questions. |
| Exam manager | Everything above, plus exams, sections and topics, mock papers, AI exam skills and AI generation. |
| Admin | Everything above, plus user management (create, edit, reset passwords, grant Pro) and Excel/JSON imports. |
| Super admin | Everything, plus institutes, platform settings and maintenance tools. Only a super admin can create or promote another super admin. |
| Institute role | What it can do |
|---|---|
| Institute admin | Full institute console, including adding staff, bulk importing students from Excel and editing or removing members. |
| Content manager, exam controller | Branding, batches, member list, institute mock papers, scheduled sessions and reports. |
| Student | Their scheduled exams, the exam lobby, history and answer keys, performance and batch details. |
03 · Candidate features
What an aspirant gets
The candidate portal is organised into Practice (dashboard, exams, duels) and Review (history, mistakes, saved questions, analytics). All diagnostic tools are free; the paid limits are the per-exam mock quota and the printable answer-key booklet.
Exam catalogue
/exams
Exam room
/attempt/[id]
Scorecard
/results/[id]
Attempt history
/dashboard/history
Mistake notebook
/dashboard/mistakes
Saved questions
/dashboard/saved-questions
Analytics
/dashboard/analytics
Mock Duels
/dashboard/challenges
Exam catalogue with search and filters
Exam page: key facts and the mock series
Attempt history with retakes and scorecards
Mock Duels: challenge a friend to the same paper
04 · Taking an exam
From Start to scorecard
The server is the source of truth for time and scoring. The browser saves answers as the candidate goes and keeps a local backup until the submission succeeds, so a dropped connection doesn't lose work.
Scoring
Each question carries its own marks and penalty from the paper. Negative marking applies only when the exam version enables it.
Readiness score
One 10–98.5 figure on the dashboard that blends average score, accuracy and how many mocks were taken.
Time pacing spectrum
The scorecard sorts every answered question by how long it took.
05 · Practice & duels
Turning mistakes into practice
Launch Mistake Drill builds a short personal paper from up to 20 unresolved mistakes. Drills are private and never appear in anyone else's mock list. A Mock Duel moves through these states:
Pending
Challenge sent by email
Scheduled
Accepted; a new time can be proposed
In progress
A player joins within 5 min of the start
Completed
Both submitted, results compared
Finished duels (completed or forfeited) are locked and can't be cancelled, rejected or rescheduled. Only the two players and admins can see a duel's result.
06 · Institute platform
Proctored exams for coaching centres
A super admin creates an institute and its first admin. The institute then manages its own courses, batches, members, private mock papers and scheduled sessions, with its own branding and login page. Each institute only ever sees its own data.
Scheduled
Staff set date, time, batch and rules
Lobby open
Students wait in the waiting room
Live
First student starts at the start time
Ended
Start + duration has passed
Reports
Rank list and proctoring audit
- Export as CSV
- Print a branded A4 rank sheet
- Pardon or disqualify from the audit
Session rules
- Optional strict time lock: no entry more than 15 minutes after the start.
- Entry closes once the session's duration has passed.
- Attempt limit per student, with staff retake grants.
- Optional batch filter and per-session pass-mark and penalty overrides.
Proctoring
- The exam room reports tab switches and leaving the window.
- With a limit of N (default 3), a student is flagged at N−1 and disqualified at N.
- Staff can review the log and pardon or disqualify. After a pardon the count starts again.
The session report ranks each student by their best attempt, and tied scores share a rank (1, 1, 3). It exports as CSV or prints as an A4 rank sheet with the institute's branding. When an admin adds members, the app shows each new account's one-time password, with a CSV download for Excel imports.
07 · Backoffice
How content gets made
The admin console is grouped into Content (exams, mock exams, exam identity, reported issues) and Business (pricing, accounts, institutes, platform settings). A mock paper can be created four ways:
- 1
Exam blueprint
Sections, topics and question quotas
- 2
Create the paper
Blank, Excel / CSV / JSON import, or AI
- 3
Edit questions
Inline editor with answers and explanations
- 4
Publish
Status READY, shown to candidates
- 5
Reported issues
Students flag a question; staff fix it in one step
Mock Exams: create, import, generate with AI and publish
Exam Pricing: free mocks per user and bundle price per exam
Reported questions flow back to the editor: staff correct the question and resolve the report in one step (Quick Fix).
08 · Business model
Free to start, pay per exam
There is no recurring subscription. Each exam has its own free-mock allowance and bundle price, set on the Exam Pricing page.
| Lever | How it works today |
|---|---|
| Free-mock quota | Each exam allows a set number of free attempts per user (10 by default). After that, starting a new mock shows the quota is used up, with the bundle price. |
| Exam bundle | Unlocks every mock for one exam, for life. Free (₹0) bundles unlock with one click. |
| Pro | Unlocks the printable exam booklet with its answer key. Admins can grant Pro to a user. |
| Institutes (B2B) | Seat capacity and a per-student rate are recorded per institute. Institute sessions and Mock Duels never count against the free quota. |
How a pack is paid for
The browser asks the API for an order (the price always comes from the exam), opens Razorpay Checkout with the returned public key, and sends Razorpay's signed confirmation back to the API, which verifies the signature against that order before unlocking the pack. Buying a pack the user already owns is refused. Needs RAZORPAY_KEY_ID and RAZORPAY_KEY_SECRET set on the backend.
09 · Architecture
How the pieces fit
A Next.js web app talks to a FastAPI backend over JSON. The API stores everything in PostgreSQL and uses Redis for caching and as the queue for background workers.
| Scheduled job | When | What it does |
|---|---|---|
| Replenish mock pools | Every 5 minutes | Queues AI generation for exams running low on ready papers |
| Update performance stats | Daily, 02:00 UTC | Recomputes each user's analytics |
| Clean up expired attempts | Daily, 03:00 UTC | Closes attempts whose time ran out |
10 · Data model
The core tables
55 tables in total. These are the ones the main flows run on: an exam's structure, a candidate's activity, purchases, duels and institutes.
Exams and candidate activity
Purchases, duels and institutes
11 · Tech stack
What it's built with
| Layer | Technology | Notes |
|---|---|---|
| Web app | Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS v4 | TanStack Query, Zustand, Recharts, Radix UI, Geist font |
| Design system | Semantic colour tokens, light / soft / dark themes | Shared page header, stat card, empty state and dialog components keep every screen consistent |
| API | Python 3.11, FastAPI, SQLAlchemy 2.0 (async), Pydantic v2 | JWT access and refresh tokens, bcrypt passwords, request IDs, security headers |
| Database | PostgreSQL 16 with pgvector; SQLite locally | Alembic migrations (head f3a7c2d1e9b4) |
| Jobs | Celery worker and beat on Redis 7 | Mock generation, analytics, notifications |
| AI | OpenAI, Anthropic, or a built-in mock provider | Exam skills drive AI paper generation from the blueprint |
| Brevo SMTP (console in development) | Verification and password-reset emails | |
| Testing | pytest (208), Playwright (121 end-to-end) | End-to-end suite runs on a freshly seeded local database |
12 · Deployment
Shipping to production
Pushing to main deploys through Coolify, which builds and runs docker-compose.prod.yml.
- 1
Push to main
Code merged on GitHub
- 2
GitHub Actions
Calls the Coolify deploy webhook
- 3
Build images
Backend and frontend Docker images
- 4
Start 7 services
Database, Redis, MinIO, API, workers, web
- 5
Live
Migrations run, then mockprepai.in serves
| Symptom | Usual cause | Where to look |
|---|---|---|
| CORS error in the browser | The API is down; the proxy's 503 page has no CORS headers | Coolify → backend container logs |
| 503 “no available server” | Backend container stopped, crashing or unhealthy | Backend logs, last 30–50 lines |
| Deploy fails pulling MinIO (401) | MinIO stopped publishing images | Compose now uses chainguard/minio |
| “greenlet” ImportError on start | SQLAlchemy 2.1 pulled in by an unpinned build | Pinned to <2.1 with greenlet listed |
13 · Quality & security
How quality and security are handled
Every change is checked by 208 backend tests and 121 end-to-end browser tests that run the real app on a freshly seeded database.
Payments
Accounts
Institute isolation
Exam integrity
Exam room resilience
Private practice
14 · Gaps & next steps
What isn't built yet
| Area | Status | Detail |
|---|---|---|
| Pro subscription checkout | Not built | Pro is granted by admins; exam packs can be bought online |
| Document processing | Not built | Uploaded PDFs are stored but not extracted or indexed for AI generation |
| File storage | Provisioned | MinIO runs, but no code reads or writes to it yet |
| AI jobs console | Hidden | The backend module exists but isn't connected; the page redirects |
| Translation coverage | Partial | English and Malayalam switch, but many labels are still English-only |
| Proctoring signals | Partial | Tab switches and window blur are reported; leaving fullscreen is not |
| Core exam flow, analytics, institutes, duels | Live | Covered by the automated test suites |
Source: docs/ARCHITECTURE_AND_FEATURES.md and docs/API_DOCUMENTATION.md in the repository, checked against the code in October 2026.