Study Buddy v2

Study Buddy v2 is a Next.js learning platform for exam preparation. It combines practice questions, mock exams, progress tracking, AI-assisted study support, subscriptions, and school/admin workflows in a single app.

Stack

• Next.js 16 App Router
• React 18
• TypeScript
• Tailwind CSS
• Prisma + PostgreSQL
• Supabase Auth
• OpenAI API

Core Product Areas

• Study materials: subject/topic browsing and topic-level practice drills
• Past questions: answer submission, grading, and explanations
• Mock exams: start, save progress, submit, and grade full exam instances
• Progress: subject progress, practice accuracy, and exam history
• AI: quick chat, saved AI question threads, and study recommendations
• Accounts and billing: auth, profile, subscriptions, and payments
• Admin and schools: content upload, user lookup, and school membership management

Product Strategy Reminders

• Human tutoring strategy: consider an Uber/Airbnb-style marketplace model for human tutors. The platform can match students with vetted tutors, handle scheduling, trust signals, ratings, and payments, while letting tutor supply scale without Study Buddy directly employing every tutor.

Product TODOs

• AI tutor/chat safeguards: make the AI tutor more robust against malpractice and misuse. Add detection, reporting, review workflows, and temporary account suspension for repeated consecutive unresolved malpractice/misuse incidents.
• AI tutor/chat relevance: stop the AI from answering unrelated questions and keep responses focused on supported study/tutoring use cases.
• AI tutor/chat UI: make the chat/tutor interface more visually appealing, auto-scroll when new messages arrive, and add a clear visible scrollbar/scroll area for long conversations.
• AI tutor visual identity: change/update the AI tutor image.
• AI Q&A threads: fix the thread counting/updating bug; AI Q&A threads seem to not actually count or update correctly.

Payment Notes

• Paystack payment support exists for subscriptions/billing. /api/v1/payments/verify verifies a payment reference after the app sends it, while /api/v1/payments/webhook is the server-to-server fallback Paystack calls when payment events happen. The webhook helps record payments even if the user closes the browser, loses connection, or the frontend callback fails after payment.
• The current build warning for app/api/v1/payments/webhook/route.ts comes from an old App Router-incompatible export const config = { api: { bodyParser: false } } block. The handler already reads the raw request body with await req.text(), which is the important part for Paystack signature verification.

Email Delivery Notes

• Use Resend as Supabase Auth's custom SMTP provider before production. Supabase's default Auth email sender is development-only and currently rate-limited to 2 emails per hour.
• Resend SMTP settings for Supabase:
  • host: smtp.resend.com
  • port: 587 for STARTTLS, or 465 for implicit TLS
  • username: resend
  • password: the Resend API key
  • sender email: use a verified auth-only sending address, for example no-reply@auth.yourdomain.com
  • sender name: Study Buddy
• Do not commit the Resend API key. Configure it only in the Supabase Dashboard under Authentication SMTP settings, or through the Supabase Management API using a secure local shell environment.
• Verify the sending domain in Resend and configure SPF, DKIM, and DMARC before relying on password reset or verification emails in production.
• Prefer a Supabase recovery email template that uses token_hash; it works even when users open reset links in a different browser or device from where they requested the email:

<a href="{{ .RedirectTo }}?token_hash={{ .TokenHash }}&type=recovery">
  Reset password
</a>

Repo Shape

study-buddy-v2/
├── app/                 # Pages and API routes
├── components/          # Shared UI components
├── lib/                 # Auth, Prisma, Supabase, and feature helpers
├── prisma/              # Schema, migrations, and seed data
├── docs/                # Supporting documentation
└── public/              # Static assets

Main App Routes

• / landing page
• /dashboard
• /materials
• /materials/practice/[topicId]
• /exams
• /exams/[instanceId]
• /progress
• /chat
• auth pages under /login, /sign-up, /forgot-password, /reset-password/update

API Surface

All app APIs live under app/api/v1.

Main domains:

• auth and account
• profile
• schools
• AI
• past questions
• mock exams
• progress
• subscriptions
• payments
• admin content

See app/api/v1/README.md for the route-level reference.

Database

The schema is defined in prisma/schema.prisma.

Key models:

• User, UserProfile, AdminUser
• Subject, Topic, PastQuestion
• PastQuestionAttempt
• MockExamTemplate, MockExamInstance, MockExamAnswer
• AiQuestion, AiQuestionMessage, Recommendation
• ProgressTrack
• Subscription, Transaction
• School, SchoolStudent

Local Setup

Install dependencies:

npm install

Run the app:

npm run dev

Apply migrations:

npx prisma migrate deploy

Generate Prisma client if the schema has changed:

npx prisma generate

Seed the database:

npx prisma db seed

Dependency Notes

• Next.js is currently using 16.3.0-canary.92 because the latest stable release available during the audit still reported a moderate npm audit issue through Next's nested postcss dependency. Re-check this periodically and move back to a stable patched Next.js release once npm audit --audit-level=moderate stays clean.
• Avoid blindly running npm audit fix --force for this issue; npm suggested a breaking downgrade to Next 9 instead of a safe patch.

Environment

The app expects environment variables for:

• Supabase URL and anon key
• database connection strings
• OpenAI API key
• payment provider secrets
• optional cron secret for recommendation generation
• CAPTCHA frontend config when Supabase Auth CAPTCHA is enabled:
  • NEXT_PUBLIC_CAPTCHA_PROVIDER=hcaptcha or NEXT_PUBLIC_CAPTCHA_PROVIDER=turnstile
  • NEXT_PUBLIC_CAPTCHA_SITE_KEY=...

Recommended Docs

• CODEBASE_BREAKDOWN.md: broad codebase map
• docs/WEBSITE_GUIDE.md: path-by-path app walkthrough
• docs/PERFORMANCE_AND_LOW_DATA_RULEBOOK.md: mandatory performance, bandwidth, low-data, and resilience rules for future LLM/code changes
• AI_FEATURES_GUIDE.md: AI-specific implementation notes
• app/api/v1/README.md: API contracts