StudyStack AI

StudyStack AI is a student-focused study app that turns uploaded PDFs into organized study sessions, cited answers, flashcards, quizzes, and review plans.

Live Demo

• Production app: https://studystack-aii.vercel.app/

Overview

StudyStack helps students study from the materials they already use in class. Upload notes, slides, readings, or study guides as PDFs, then use the app to ask questions, review source-backed answers, create flashcards, build quizzes, and plan review sessions.

The product is designed around reviewability. Answers and study tools stay connected to the uploaded document sections they came from, so students can verify ideas, revisit source material, and keep their study sessions organized.

Features

• Secure sign up, sign in, and sign out with protected app routes
• Private PDF upload and authenticated preview/download
• Document library with rename, refresh, delete, sorting, and status feedback
• Server-side PDF text extraction with structured pages, sections, formulas, examples, and local study spans
• Search across uploaded study materials
• Chat-first study flow with attachment-style PDF uploads
• Grounded study chat with persistent threads, saved Q&A history, and source citations
• Source links that jump back to the relevant document section
• Flashcard generation from uploaded materials with filtering, ratings, shuffle, and end-of-session review
• Manual flashcard set creation and editing
• Quiz generation with scoring, explanations, missed-question review, and source links
• Manual multiple-choice quiz creation and editing
• Interactive study planner with calendar-based reminders
• Math rendering for formulas and technical notation
• Student-facing marketing pages for features, workflow, and onboarding
• Practical security hardening for private files, user-scoped data, uploads, and browser headers

Tech Stack

• Next.js App Router
• TypeScript
• Tailwind CSS
• Supabase Auth
• Supabase Postgres with Row Level Security
• Supabase Storage for private PDF files
• OpenAI API for grounded answers and study-tool generation
• pgvector for semantic document search
• PDF.js for server-side PDF text extraction

How It Works

1. A student creates an account and uploads a PDF.
2. StudyStack prepares the document so it can be searched and used for study tools.
3. The student asks questions about the uploaded material.
4. The app finds relevant source sections from that student's documents.
5. Answers, flashcards, and quizzes are generated from those source sections.
6. The student can create manual study tools, edit their own sets, revisit saved answers, and reopen richer study sessions later.

Product Preview

Landing Page

The landing page introduces the chat-first study workflow and the app's focused student experience.

Dashboard

The dashboard acts as a study command center with resume actions, planning, and next-step guidance.

Study Chat

The chat workspace supports grounded questions over uploaded materials with persistent conversations.

Documents

The documents view manages the private source library used for chat, flashcards, and quizzes.

Flashcards

Flashcard sessions include richer review controls, progress tracking, and a focused study layout.

Quizzes

Quiz sessions provide a more complete test-and-review experience with progress, scoring, and navigation.

Getting Started

Prerequisites

• Node.js 20 or newer
• npm
• A Supabase project
• An OpenAI API key

1. Clone the Repository

git clone <repository-url>
cd studystack-ai

2. Install Dependencies

npm install

3. Configure Environment Variables

Copy the example environment file:

cp .env.example .env.local

Then provide values for a Supabase project and OpenAI key.

NEXT_PUBLIC_SUPABASE_URL=https://<supabase-project-ref>.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=<supabase-publishable-or-anon-key>
NEXT_PUBLIC_SITE_URL=http://localhost:3000
SUPABASE_DOCUMENTS_BUCKET=documents
OPENAI_API_KEY=<openai-api-key>
OPENAI_MODEL=gpt-5-mini
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
OPENAI_EMBEDDING_DIMENSIONS=1536

Important notes:

• NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY is intended for the browser and should be a low-privilege Supabase publishable or anon key.
• OPENAI_API_KEY must stay server-only. Do not prefix it with NEXT_PUBLIC_.
• SUPABASE_DOCUMENTS_BUCKET should match the private bucket configured in Supabase.
• Set NEXT_PUBLIC_SITE_URL to the deployed app URL in production.

4. Run Supabase Setup SQL

Run the SQL files in Supabase SQL Editor in this order:

1. supabase/documents.sql
2. supabase/storage.sql
3. supabase/document_text.sql
4. supabase/chat_history.sql
5. supabase/study_tools.sql
6. supabase/manual_study_tools.sql
7. supabase/study_planner.sql
8. supabase/structured_documents.sql if upgrading an existing Supabase project that ran an older schema

Supabase setup checklist:

• Enable email authentication.
• Configure the Site URL and callback URLs for local and production environments.
• Keep the documents storage bucket private.
• Confirm Row Level Security policies are enabled and applied.
• Confirm pgvector is available for semantic search.

5. Run Locally

npm run dev

Open http://localhost:3000.

6. Build for Production

npm run build
npm run start

Environment Variables

Variable	Required	Description
NEXT_PUBLIC_SUPABASE_URL	Yes	Public Supabase project URL.
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	Yes	Low-privilege Supabase browser key.
NEXT_PUBLIC_SITE_URL	Yes	App URL used for auth redirects. Use http://localhost:3000 locally.
SUPABASE_DOCUMENTS_BUCKET	Yes	Private Supabase Storage bucket for uploaded PDFs.
OPENAI_API_KEY	Yes	Server-only OpenAI API key.
OPENAI_MODEL	Yes	Model used for answers, flashcards, and quizzes.
OPENAI_EMBEDDING_MODEL	Yes	Model used to embed document sections.
OPENAI_EMBEDDING_DIMENSIONS	Yes	Embedding size expected by the database schema.

Project Structure

src/app/(marketing)        Marketing pages: home, features, how it works, get started
src/app/(auth)             Sign in, sign up, and auth actions
src/app/(app)              Protected study app routes
src/app/api                Server routes for upload finalization
src/components             Shared UI, app, document, chat, planner, flashcard, and quiz components
src/lib                    Supabase, OpenAI, PDF, retrieval, structured document, and security helpers
supabase                   Database, RLS, storage, and retrieval SQL setup
public/brand               StudyStack logo assets

Security and Privacy Notes

StudyStack is designed for private study materials. The app uses Supabase Auth, Row Level Security, private storage buckets, authenticated PDF preview/download routes, and server-only OpenAI calls.

Security-related implementation details include:

• User-owned tables are scoped with RLS policies.
• Uploaded PDFs are stored in a private bucket under per-user paths.
• PDF uploads are limited to PDF files and capped at 50 MB.
• The OpenAI API key is only used server-side.
• Browser security headers are configured in next.config.ts.
• Retrieved document text is treated as untrusted input in AI prompts.
• Planner entries, chat threads, flashcards, quizzes, and document records are scoped to the authenticated user.

Self-hosted deployments should verify that the SQL policies in supabase/ are applied in the target Supabase project.

Deployment Notes

This project is ready to deploy on Vercel or a similar Next.js host.

For Vercel:

1. Import the GitHub repository.
2. Add the environment variables listed above.
3. Set NEXT_PUBLIC_SITE_URL to the production URL.
4. Add the production callback URL in Supabase Auth settings.
5. Run the Supabase SQL setup before testing uploads or app routes.

Supabase Auth URLs should include:

• Local callback: http://localhost:3000/auth/callback
• Production callback: https://<production-domain>/auth/callback

Development Commands

npm run dev      # Start the local dev server
npm run build    # Create a production build
npm run start    # Run the production build locally
npm run lint     # Run ESLint
npm run eval     # Run document-understanding regression checks

Roadmap

Potential future improvements:

• OCR support for scanned PDFs
• Spaced repetition scheduling
• Better class/course organization
• Study progress tracking
• More configurable flashcard and quiz generation
• Optional collaborative study spaces

License

This repository is currently shared for portfolio and demonstration purposes. No license is granted for reuse, modification, or redistribution at this time.