App Router Pages
src/app
Route-based screens for public pages, auth, dashboard, NCERT explorer, notes, quiz, profile, and admin flows.
Accessing archived manuscripts and institutional lectures
from the Monolith repository.
Institutional Authority
VidyaSetu V4.0.2
Reference: MS-2044-X
Archival Integrity Verified
Contributor Docs
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
Architecture
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.
src/app
Route-based screens for public pages, auth, dashboard, NCERT explorer, notes, quiz, profile, and admin flows.
src/app/api
Next.js route handlers that receive browser requests and delegate work to domain modules.
src/modules
Feature logic grouped by auth, admin, NCERT, quiz, notes, AI, analytics, and user concerns.
src/lib
Reusable helpers for Prisma, auth, cookies, Cloudinary, logging, responses, and provider integrations.
src/prisma/schema.prisma
Prisma models for users, NCERT structure, notes, quizzes, sessions, responses, AI logs, and analytics.
src/generated/prisma
Generated after running pnpm db:generate. This folder is ignored and should not be manually edited.
Request Flow
The codebase follows a simple path from UI interaction to database operation. When debugging, trace the feature in this order before changing shared code.
A page or client component calls an API route under src/app/api.
The API route calls the matching controller in src/modules.
The controller validates input and calls the service layer.
The service handles business rules and calls repositories or providers.
Repositories use Prisma to read or write PostgreSQL data.
The API route returns a structured response to the frontend.
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
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
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.
src/app
Use the App Router route folder that matches the URL you are changing.
src/modules
Update the relevant controller, service, repository, validator, or type file.
src/prisma/schema.prisma
Update the schema, create a migration, then regenerate the Prisma client.
src/modules/ncert and src/prisma/seed.ts
Use seed data for class, subject, chapter, and PDF link setup.
src/modules/auth and src/lib/auth
Check token creation, cookies, refresh logic, and route handlers together.
src/modules/quiz and src/app/quiz
Trace quiz creation, session start, response submission, and scoring.
Use README.md for environment variables, database setup, migrations, and seed data.
Run pnpm db:seed to populate NCERT classes, subjects, chapters, and PDF links.
Find the page or API route first, then follow it into the owning module.
Keep changes scoped to one issue or feature so review stays clear.
Need the full setup path?