Route Map

URLs and owning files

Use this map when you are not sure where a feature starts. For UI issues, open the route file first. For data or behavior issues, follow the route into the matching API handler and module.

Route

Files

Purpose

src/app/page.tsx

Landing page and entry point for unauthenticated visitors.

/docs

src/app/docs/page.tsx

Public contributor documentation for codebase orientation.

/login and /register

src/app/(auth)

Authentication screens and account onboarding flows.

/dashboard

src/app/dashboard

Student overview, progress entry point, and learning shortcuts.

/ncert

src/app/ncert and src/modules/ncert

Class, subject, chapter, topic, and NCERT PDF exploration.

/quiz

src/app/quiz and src/modules/quiz

Quiz creation, quiz sessions, answer submission, and scoring.

/notes

src/app/notes and src/modules/notes

Notes upload, extraction, storage, and note-based workflows.

/admin

src/app/admin and src/modules/admin

Admin-facing flows for seed/admin operations and analytics.

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.

App Router Pages

src/app

Route-based screens for public pages, auth, dashboard, NCERT explorer, notes, quiz, profile, and admin flows.

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.

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.

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.

Modules

Feature ownership boundaries

Each module owns a domain of behavior. When a change crosses modules, keep the integration explicit instead of hiding unrelated behavior in shared helpers.

auth

Owns registration, login, refresh tokens, cookies, password hashing, and session helpers.

src/modules/auth and src/lib/auth

ncert

Owns classes, subjects, chapters, topics, and NCERT content lookup.

src/modules/ncert

quiz

Owns quiz creation, session start, submitted answers, scoring, and quiz records.

src/modules/quiz

notes

Owns note records, extracted text, file URLs, and note upload workflows.

src/modules/notes

ai

Owns AI provider boundary, question generation, and subjective answer evaluation.

src/modules/ai and src/lib/ai

analytics

Owns student performance summaries, weak topic detection, and aggregate stats.

src/modules/analytics

admin

Owns admin-only actions, privileged content management, and admin dashboard data.

src/modules/admin

user

Owns profile reads, profile updates, and user-facing account metadata.

src/modules/user

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.

Prisma Workflow

Database lifecycle

Schema changes are handled through Prisma. Keep schema edits, migrations, generated client updates, and seed behavior aligned so contributors can reproduce your work locally.

pnpm db:generate

After cloning, after schema changes, or when generated Prisma imports are missing.

pnpm db:migrate

After setting DATABASE_URL and DIRECT_URL, and after changing schema.prisma.

pnpm db:seed

After migrations, when you need NCERT classes, subjects, chapters, and PDF links.

pnpm db:studio

When you want to inspect local database records in a browser.

Environment

What each env var does

The app should run with contributor-owned credentials only. Real production credentials should never be shared or committed.

DATABASE_URL

Runtime database URL. Use Docker Postgres locally or a hosted PostgreSQL provider.

DIRECT_URL

Migration database URL. Prisma migrations should use a direct database connection.

JWT_SECRET

Local token signing secret. Generate one with openssl rand -base64 32.

NEXTAUTH_URL

Use http://localhost:3000 locally. Use the deployed app URL in production.

GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET

Only required for Google login. Contributors not touching auth can leave them empty.

Cloudinary variables

Optional for now. Add them only when working on uploads or media features.

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.

Debugging

Common setup problems

Most contributor setup issues come from missing environment values, skipped Prisma generation, database connection mismatches, or expecting seed data to include full demo activity.

Cannot find generated Prisma client

Run pnpm db:generate. The generated client folder is intentionally ignored by git.

Migration fails with missing DIRECT_URL

Set DIRECT_URL in .env. This project uses DIRECT_URL in prisma.config.ts.

Docker Postgres port conflict

Another Postgres may already be using 5432. Stop it or change the Docker port mapping.

Dashboard or analytics looks empty

Seed data creates NCERT metadata, not full user history. Create quizzes/attempts locally.

Google login does not work locally

Add Google OAuth credentials or use non-OAuth flows while working on unrelated features.

Full pnpm lint fails

Some existing files still need lint cleanup. Run ESLint on files you changed for focused checks.

Pull request checklist

Keep one pull request focused on one bug, feature, or documentation improvement.

Mention which page, module, or API route you changed.

Run the most relevant check, such as pnpm eslint path/to/file.tsx.

Add screenshots for UI changes when possible.

Do not commit .env, database credentials, generated Prisma files, or local build output.

Explain any setup assumptions, skipped checks, or known limitations in the PR description.

Change strategy

Start with the smallest working change. If a fix only affects one page, keep it in that page. If multiple pages need the same behavior, move the repeated logic into a component or shared helper.

For backend work, avoid putting business rules directly inside API route handlers. Keep request handling in route/controller files and place reusable behavior in services or repositories.

For database work, update the Prisma schema first, create the migration, regenerate the client, and document any seed data changes that reviewers need to run.

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?

Open GitHub Repository

Route Map

URLs and owning files

Use this map when you are not sure where a feature starts. For UI issues, open the route file first. For data or behavior issues, follow the route into the matching API handler and module.

Route

Files

Purpose

src/app/page.tsx

Landing page and entry point for unauthenticated visitors.

/docs

src/app/docs/page.tsx

Public contributor documentation for codebase orientation.

/login and /register

src/app/(auth)

Authentication screens and account onboarding flows.

/dashboard

src/app/dashboard

Student overview, progress entry point, and learning shortcuts.

/ncert

src/app/ncert and src/modules/ncert

Class, subject, chapter, topic, and NCERT PDF exploration.

/quiz

src/app/quiz and src/modules/quiz

Quiz creation, quiz sessions, answer submission, and scoring.

/notes

src/app/notes and src/modules/notes

Notes upload, extraction, storage, and note-based workflows.

/admin

src/app/admin and src/modules/admin

Admin-facing flows for seed/admin operations and analytics.

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

App Router Pages

src/app

Route-based screens for public pages, auth, dashboard, NCERT explorer, notes, quiz, profile, and admin flows.

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.

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.

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.

Modules

Feature ownership boundaries

Each module owns a domain of behavior. When a change crosses modules, keep the integration explicit instead of hiding unrelated behavior in shared helpers.

auth

Owns registration, login, refresh tokens, cookies, password hashing, and session helpers.

src/modules/auth and src/lib/auth

ncert

Owns classes, subjects, chapters, topics, and NCERT content lookup.

src/modules/ncert

quiz

Owns quiz creation, session start, submitted answers, scoring, and quiz records.

src/modules/quiz

notes

Owns note records, extracted text, file URLs, and note upload workflows.

src/modules/notes

ai

Owns AI provider boundary, question generation, and subjective answer evaluation.

src/modules/ai and src/lib/ai

analytics

Owns student performance summaries, weak topic detection, and aggregate stats.

src/modules/analytics

admin

Owns admin-only actions, privileged content management, and admin dashboard data.

src/modules/admin

user

Owns profile reads, profile updates, and user-facing account metadata.

src/modules/user

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.

Prisma Workflow

Database lifecycle

Schema changes are handled through Prisma. Keep schema edits, migrations, generated client updates, and seed behavior aligned so contributors can reproduce your work locally.

pnpm db:generate

After cloning, after schema changes, or when generated Prisma imports are missing.

pnpm db:migrate

After setting DATABASE_URL and DIRECT_URL, and after changing schema.prisma.

pnpm db:seed

After migrations, when you need NCERT classes, subjects, chapters, and PDF links.

pnpm db:studio

When you want to inspect local database records in a browser.

Environment

What each env var does

The app should run with contributor-owned credentials only. Real production credentials should never be shared or committed.

DATABASE_URL

Runtime database URL. Use Docker Postgres locally or a hosted PostgreSQL provider.

DIRECT_URL

Migration database URL. Prisma migrations should use a direct database connection.

JWT_SECRET

Local token signing secret. Generate one with openssl rand -base64 32.

NEXTAUTH_URL

Use http://localhost:3000 locally. Use the deployed app URL in production.

GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET

Only required for Google login. Contributors not touching auth can leave them empty.

Cloudinary variables

Optional for now. Add them only when working on uploads or media features.

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.

Debugging

Common setup problems

Most contributor setup issues come from missing environment values, skipped Prisma generation, database connection mismatches, or expecting seed data to include full demo activity.

Cannot find generated Prisma client

Run pnpm db:generate. The generated client folder is intentionally ignored by git.

Migration fails with missing DIRECT_URL

Set DIRECT_URL in .env. This project uses DIRECT_URL in prisma.config.ts.

Docker Postgres port conflict

Another Postgres may already be using 5432. Stop it or change the Docker port mapping.

Dashboard or analytics looks empty

Seed data creates NCERT metadata, not full user history. Create quizzes/attempts locally.

Google login does not work locally

Add Google OAuth credentials or use non-OAuth flows while working on unrelated features.

Full pnpm lint fails

Some existing files still need lint cleanup. Run ESLint on files you changed for focused checks.

Pull request checklist

Keep one pull request focused on one bug, feature, or documentation improvement.

Mention which page, module, or API route you changed.

Run the most relevant check, such as pnpm eslint path/to/file.tsx.

Add screenshots for UI changes when possible.

Do not commit .env, database credentials, generated Prisma files, or local build output.

Explain any setup assumptions, skipped checks, or known limitations in the PR description.

Change strategy

Start with the smallest working change. If a fix only affects one page, keep it in that page. If multiple pages need the same behavior, move the repeated logic into a component or shared helper.

For backend work, avoid putting business rules directly inside API route handlers. Keep request handling in route/controller files and place reusable behavior in services or repositories.

For database work, update the Prisma schema first, create the migration, regenerate the client, and document any seed data changes that reviewers need to run.

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?

Open GitHub Repository

URLs and owning files

Understand the VidyaSetu codebase before you contribute.

How the code is organized

App Router Pages

API Routes

Domain Modules

Shared Libraries

Database Schema

Generated Prisma Client

From screen to data

Backend module shape

Feature ownership boundaries

auth

ncert

quiz

notes

ai

analytics

admin

user

Core Prisma models

Database lifecycle

What each env var does

Where to start

Add or adjust a page

Change backend behavior

Change database structure

Work on NCERT data

Work on auth

Work on quiz flow

Common setup problems

Cannot find generated Prisma client

Migration fails with missing DIRECT_URL

Docker Postgres port conflict

Dashboard or analytics looks empty

Google login does not work locally

Full pnpm lint fails

Pull request checklist

Change strategy

Read setup docs

Seed your database

Trace the route

Open a focused PR

Curating YourCurriculum...

URLs and owning files

Understand the VidyaSetu codebase before you contribute.

How the code is organized

App Router Pages

API Routes

Domain Modules

Shared Libraries

Database Schema

Generated Prisma Client

From screen to data

Backend module shape

Feature ownership boundaries

auth

ncert

quiz

notes

ai

analytics

admin

user

Core Prisma models

Database lifecycle

What each env var does

Where to start

Add or adjust a page

Change backend behavior

Change database structure

Work on NCERT data

Work on auth

Work on quiz flow

Common setup problems

Cannot find generated Prisma client

Migration fails with missing DIRECT_URL

Docker Postgres port conflict

Dashboard or analytics looks empty

Google login does not work locally

Curating Your
Curriculum...