App Router Pages
src/app
Route-based screens for public pages, auth, dashboard, NCERT explorer, notes, quiz, profile, and admin flows.
Contributor Docs
Understand the VidyaSetu codebase before you contribute.
This page explains the project structure, request flow, database model, setup path, and the best files to open for common contribution tasks.
First local run
1Copy .env.example to .env.
2Choose hosted PostgreSQL or Docker PostgreSQL.
3Run pnpm install.
4Run pnpm db:generate.
5Run pnpm db:migrate.
6Run pnpm db:seed.
7Run pnpm dev.
Architecture
How the code is organized
VidyaSetu uses a Next.js App Router frontend with API routes and feature modules. Most changes should start from the route or module that owns the feature, then move inward toward services, repositories, Prisma, and shared libraries as needed.
API Routes
src/app/api
Next.js route handlers that receive browser requests and delegate work to domain modules.
Domain Modules
src/modules
Feature logic grouped by auth, admin, NCERT, quiz, notes, AI, analytics, and user concerns.
Shared Libraries
src/lib
Reusable helpers for Prisma, auth, cookies, Cloudinary, logging, responses, and provider integrations.
Database Schema
src/prisma/schema.prisma
Prisma models for users, NCERT structure, notes, quizzes, sessions, responses, AI logs, and analytics.
Generated Prisma Client
src/generated/prisma
Generated after running pnpm db:generate. This folder is ignored and should not be manually edited.
Request Flow
From screen to data
The codebase follows a simple path from UI interaction to database operation. When debugging, trace the feature in this order before changing shared code.
1
A page or client component calls an API route under src/app/api.
2
The API route calls the matching controller in src/modules.
3
The controller validates input and calls the service layer.
4
The service handles business rules and calls repositories or providers.
5
Repositories use Prisma to read or write PostgreSQL data.
6
The API route returns a structured response to the frontend.
Backend module shape
controller.ts receives requests and shapes responses.
service.ts owns business rules and orchestration.
repository.ts owns database access.
validator.ts validates incoming payloads.
types.ts keeps feature-specific TypeScript contracts.
Database
Core Prisma models
PostgreSQL is the source of truth. Prisma defines the schema, migrations shape the database, and the generated client gives the app typed access to the models.
User and Account handle credentials, OAuth accounts, refresh tokens, profile state, and roles.
AcademicClass, Subject, Chapter, and Topic represent the NCERT content structure.
Question and Option store MCQ and subjective question data.
Quiz, QuizSession, and QuestionResponse track quiz creation, attempts, scores, and timing.
SubjectiveEvaluation stores feedback and ideal answers for written responses.
Note stores uploaded or pasted study material and extracted text.
UserStats stores aggregate analytics for student progress.
AIGenerationLog tracks AI provider usage, status, token counts, and cost estimates.
Contribution Map
Where to start
Start from the smallest area that owns the behavior. A UI-only change should usually stay in `src/app` or `src/components`; a data change should usually include Prisma and the matching module.
Add or adjust a page
src/app
Use the App Router route folder that matches the URL you are changing.
Change backend behavior
src/modules
Update the relevant controller, service, repository, validator, or type file.
Change database structure
src/prisma/schema.prisma
Update the schema, create a migration, then regenerate the Prisma client.
Work on NCERT data
src/modules/ncert and src/prisma/seed.ts
Use seed data for class, subject, chapter, and PDF link setup.
Work on auth
src/modules/auth and src/lib/auth
Check token creation, cookies, refresh logic, and route handlers together.
Work on quiz flow
src/modules/quiz and src/app/quiz
Trace quiz creation, session start, response submission, and scoring.
Read setup docs
Use README.md for environment variables, database setup, migrations, and seed data.
Seed your database
Run pnpm db:seed to populate NCERT classes, subjects, chapters, and PDF links.
Trace the route
Find the page or API route first, then follow it into the owning module.
Open a focused PR
Keep changes scoped to one issue or feature so review stays clear.
Need the full setup path?