Imported from Its-Atharva-Gupta/ReaderCopilot (AGENTS.md). Install upstream with npx skills add Its-Atharva-Gupta/ReaderCopilot. Copyright stays with the author.

AGENTS.md — StudyNest

Repository Truth

StudyNest currently ships as a monorepo with two active apps:

backend/   Django + Django REST Framework API
frontend/  Vite + React + TypeScript client

Work from these directories as the source of truth. Do not reintroduce an older root-level frontend structure.

Product Shape In Code

The current app is a school-focused study platform with:

• Firebase sign-in on the frontend
• Invite-code-gated Django registration
• Notes organized by class, subject, and chapter
• Multi-image note uploads
• Teacher-verification heuristics via red-pen detection
• Note voting plus threaded comments with mentions
• Reader/copilot flows for textbooks and uploaded reading files
• OCR and PDF generation for notes
• Leaderboard and analytics dashboards

Architecture Rules

• Django is the system of record for app data.
• Backend auth trusts Firebase for identity and verifies Firebase ID tokens in Django.
• App-level user metadata is stored in users.AppUser.
• Invite access is enforced through users.InviteCode.
• Development note uploads are stored in Django media storage under backend/media/.
• boot-dev.sh starts a repo-local PostgreSQL instance on 127.0.0.1:5433 and seeds starter taxonomy data.
• If Postgres env vars are missing, Django can fall back to SQLite, but the intended local workflow is the boot script plus Postgres.

Current Backend Map

• backend/backend/settings.py: env loading, DB config, CORS, DRF auth defaults, media config
• backend/backend/urls.py: API routing plus dev-only media serving with CORS headers
• backend/users/: Firebase token verification, registration, /me, mentionable users, invite codes
• backend/notes/: taxonomy, note CRUD, local image upload, OCR, PDF export, copilot query logging
• backend/social/: vote toggling, threaded comments, replies, edit/delete, @mention parsing
• backend/leaderboard/: top uploaders and top liked contributors
• backend/analytics/: note views, copilot query analytics, dashboard stats
• backend/notes/management/commands/seed_taxonomy.py: local seed data for Class 8 subjects/chapters
• backend/notes/management/commands/backfill_note_pdfs.py: rebuild stored note PDFs

Current Frontend Map

• frontend/src/App.tsx: routing, auth bootstrap, protected-route gating
• frontend/src/lib/api.ts: Django API client and active note-upload integration
• frontend/src/lib/firebase.ts: Firebase client bootstrapping for auth
• frontend/src/lib/openrouter.ts: reader copilot calls to OpenRouter
• frontend/src/store/useAuthStore.ts: Firebase session + registration state
• frontend/src/store/useReaderStore.ts: reader/copilot session state
• frontend/src/pages/Home.tsx: landing dashboard for signed-in users
• frontend/src/pages/FeedPage.tsx: main note feed
• frontend/src/pages/HandwrittenNotesPage.tsx: teacher-verified note view
• frontend/src/pages/ForumPage.tsx: discussion-oriented note browsing
• frontend/src/pages/NoteDetail.tsx: note reader, OCR/PDF actions, voting, comments
• frontend/src/pages/Upload.tsx: active upload flow using Django /api/notes/upload/
• frontend/src/pages/BooksReaderPage.tsx: textbook/uploaded document reader with copilot
• frontend/src/pages/LeaderboardPage.tsx: contributor rankings
• frontend/src/pages/Dashboard.tsx: analytics dashboard
• frontend/src/config/books.ts: bundled textbook catalog

Important Behavioral Details

• Protected app routes require both Firebase authentication and successful Django registration.
• Registration consumes an unused invite code and creates AppUser.
• Note creation can mark a note as teacher-verified when red-pen detection is enabled and finds red-pen signals in uploaded images.
• Once a teacher-verified note exists for a chapter, that chapter is locked against new uploads.
• Note detail views create analytics.NoteView rows.
• Reader/copilot usage can create analytics.CopilotQuery rows through /api/notes/copilot-query/.
• Comments support nested replies, editing, deletion, and mention-handle discovery.
• The frontend still contains a Firebase Storage helper, but the active handwritten-note upload path goes through Django local media storage.

Local Development Workflow

Preferred startup:

./boot-dev.sh

What it does:

• stops previous backend, frontend, and repo-local Postgres processes
• starts PostgreSQL 16 using .postgres-data/
• creates the studynest database if needed
• runs Django migration
• runs manage.py seed_taxonomy
• starts Django on 127.0.0.1:8000
• starts Vite on 127.0.0.1:5173
• writes logs to .run/

Environment Notes

Backend expects values such as:

• DJANGO_SECRET_KEY
• DJANGO_DEBUG
• DATABASE_URL or DB_*
• FIREBASE_PROJECT_ID
• ENABLE_RED_PEN_CHECK

Frontend expects values such as:

• VITE_API_BASE_URL
• VITE_FIREBASE_API_KEY
• VITE_FIREBASE_AUTH_DOMAIN
• VITE_FIREBASE_PROJECT_ID
• VITE_FIREBASE_STORAGE_BUCKET
• VITE_FIREBASE_MESSAGING_SENDER_ID
• VITE_FIREBASE_APP_ID
• VITE_OPENROUTER_API_KEY

Backend OCR currently reads the OpenRouter key from backend env, frontend env, or root env if needed.

Coding Guidance

• Prefer small, direct implementations.
• Keep docs aligned with the code that exists now, not older product intentions.
• Preserve the Firebase-auth plus Django-verification split.
• Treat Django local media storage as the active note-upload implementation unless the code is intentionally migrated.
• When changing note creation, preserve the chapter lock behavior for teacher-verified notes unless product requirements explicitly change.
• When changing analytics or dashboards, remember they are driven by NoteView, CopilotQuery, votes, comments, and verified-note coverage.

Cleanup Guidance

Keep generated and runtime files out of version control, especially:

• .run/
• .postgres-data/
• backend/media/
• backend/db.sqlite3
• backend/**/__pycache__/
• frontend build output
• *.tsbuildinfo

Testing Priorities

When touching these areas, prioritize:

• Firebase token verification and /api/users/register/
• invite-code consumption and /api/users/me/
• protected route bootstrap in frontend/src/App.tsx
• taxonomy loading and upload flow
• teacher-verified chapter locking
• note detail view tracking, OCR, and PDF export
• vote toggling and nested comment behavior
• leaderboard and analytics dashboard responses
• boot-dev.sh startup path and taxonomy seeding