polish recruiter-facing project documentation

.env.example

@@ -1,4 +1,16 @@
+# Required for the browser application. These Supabase project values are
+# designed to be public/client-safe and are protected by Row Level Security.
 NEXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
 NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-supabase-publishable-or-anon-key
+
 # Optional compatibility alias if your Supabase project still documents the key as "anon"
 # NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-publishable-or-anon-key
+
+# Optional AI integration. This is a server-side Supabase Edge Function secret,
+# not a frontend variable. Configure it with `supabase secrets set`; never add a
+# NEXT_PUBLIC_ prefix or place a real secret in a committed environment file.
+# ANTHROPIC_API_KEY=your-anthropic-api-key
+
+# Supabase provides SUPABASE_URL, SUPABASE_ANON_KEY, and
+# SUPABASE_SERVICE_ROLE_KEY to deployed Edge Functions. The service-role key
+# must never be exposed to the browser.

README.md

@@ -1,114 +1,164 @@
 # StudyOS
 
-StudyOS is an academic workspace for students who want one place to manage courses, schedules, assignments, exams, grades, and AI-assisted study workflows.
+An AI-assisted academic workspace for managing courses, schedules, materials, assessments, grades, and semester planning.
 
-The app combines a Next.js frontend with Supabase for authentication, database/storage, and Edge Functions. Uploaded course material can be indexed and used to generate course-specific quizzes, mock exams, and tutoring responses.
+[![CI](https://github.com/WaseemGhanem98/semester-ai-companion/actions/workflows/ci.yml/badge.svg)](https://github.com/WaseemGhanem98/semester-ai-companion/actions/workflows/ci.yml)
 
-## What the app does
+**[Live Demo: StudyOS on Vercel](https://semester-ai-companion.vercel.app)**
 
-- Manage courses, professors, credits, and semester details
-- Track assignments, exams, and study events
-- Upload syllabi and extract assignments, exams, and grading breakdowns
-- Upload course materials for AI-powered quiz generation
-- Generate quizzes and mock exams from indexed course material
-- Use an AI tutor with access to your academic context
-- Track grade components and course performance
+> The deployed site is a showcase environment. Core planning and data-management workflows are available, while API-backed AI features require a separately configured Anthropic API key.
 
-## Core architecture
+## Overview
 
-Frontend:
-- React
-- TypeScript
-- Next.js App Router
-- Tailwind CSS
-- shadcn/ui
-- TanStack Query
+StudyOS brings the operational parts of a semester into one focused workspace. Students can organize courses, deadlines, schedules, materials, grades, and graduation plans, then use their own academic context to generate practice content or ask an AI tutor for help.
 
-Backend:
-- Supabase Auth
-- Supabase Postgres
-- Supabase Storage
-- Supabase Edge Functions
-- Anthropic API for AI-powered parsing, tutoring, extraction, and quiz generation
+The project demonstrates full-stack product engineering across a responsive Next.js interface, Supabase-backed data and storage, authenticated Edge Functions, AI integrations, automated testing, CI, and production deployment.
+
+## Why I built it
+
+StudyOS began as a Lovable prototype used to validate the product idea quickly. That starting point was useful for exploring the workflow and interface before investing in deeper engineering work.
+
+It then became a practical environment for experimenting with and comparing multiple AI-assisted development tools and workflows. The application evolved beyond the original prototype through a migration from Vite and React Router to the Next.js App Router, manual Supabase integration, authentication and Edge Function hardening, database migrations, automated tests, CI, dependency cleanup, and a focused accessibility and responsive-UX pass.
+
+The result is both a student productivity product and a record of iterative engineering: prototype quickly, identify risk and friction, then improve the architecture and user experience deliberately.
+
+## Key features
+
+- Course, assignment, exam, schedule, grade, and graduation-plan management
+- Dashboard summaries for upcoming work and academic progress
+- Weekly and monthly calendar views with academic-date imports
+- Syllabus parsing for assignments, exams, course details, and grading weights
+- Schedule screenshot parsing and selective event import
+- Course-material uploads with user-scoped storage and text extraction
+- Course-grounded quizzes, practice exams, and AI tutoring
+- Responsive navigation, accessible interactions, and explicit loading, error, empty, and success states
+
+## Product tour
+
+No product screenshots are currently checked into the repository. For a strong portfolio presentation, the recommended final capture set is:
+
+1. **Dashboard** — semester summary, upcoming deadlines, and onboarding state
+2. **Schedule** — populated week view with academic dates and study events
+3. **Course workspace** — course details, uploaded materials, and syllabus import
+4. **Quiz flow** — generated question, answer feedback, and results
+5. **Mobile view** — responsive dashboard or schedule navigation
+
+Screenshots should use a dedicated demo account with realistic sample data and no personal information or secrets.
+
+## Architecture
+
+The browser application is deployed on Vercel and communicates directly with Supabase for authenticated product data. Operations that require privileged validation, file processing, external URL retrieval, or Anthropic access run in Supabase Edge Functions.
+
+| Layer | Implementation |
+| --- | --- |
+| Web application | Next.js App Router, React, TypeScript |
+| UI and client state | Tailwind CSS, shadcn/ui and Radix primitives, TanStack Query, Framer Motion |
+| Authentication and data | Supabase Auth and Postgres with row-level security |
+| File storage | Supabase Storage with user-scoped object paths and policies |
+| Server-side workflows | Six Deno-based Supabase Edge Functions |
+| AI integration | Anthropic Messages API, called only from Edge Functions |
+| Delivery | Vercel for the app; GitHub Actions for validation |
+
+## Tech stack
+
+**Frontend:** Next.js 15, React 18, TypeScript, Tailwind CSS, shadcn/ui, Radix UI, TanStack Query, Recharts, Framer Motion
+
+**Backend:** Supabase Auth, Postgres, Row Level Security, Storage, SQL migrations, Edge Functions, Deno
+
+**Quality and delivery:** Vitest, Testing Library, ESLint, TypeScript, npm, GitHub Actions, Vercel
+
+## AI functionality
+
+AI-powered workflows are implemented in the codebase for syllabus parsing, schedule screenshot parsing, academic-calendar import, material extraction, quiz and practice-exam generation, and contextual tutoring.
+
+These workflows rely on Anthropic API access. The public showcase intentionally does not include an active `ANTHROPIC_API_KEY` to prevent uncontrolled API usage costs. Developers can enable the supported AI features for their own deployment by configuring the server-side secret in Supabase.
 
 ## Local development
 
-Requirements:
-- Node.js 18+
+### Prerequisites
+
+- Node.js 20 or newer
 - npm
 - A Supabase project
+- Supabase CLI access if applying migrations or deploying Edge Functions
 
-Install and run:
+### Run the web application
 
-```sh
-npm install
+```bash
+git clone https://github.com/WaseemGhanem98/semester-ai-companion.git
+cd semester-ai-companion
+npm ci
+cp .env.example .env.local
 npm run dev
 ```
 
-The dev server runs at `http://localhost:3000` by default.
+Add your Supabase public project values to `.env.local`, then open [http://localhost:3000](http://localhost:3000). Google sign-in also requires a configured Google provider and matching redirect URL in Supabase Auth.
 
-## Environment variables
+### Configure the backend
 
-The frontend expects these values in `.env.local`:
+The repository includes the database migrations and all six Edge Functions. A typical Supabase workflow is:
 
-```env
-NEXT_PUBLIC_SUPABASE_URL=...
-NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=...
-# Optional compatibility alias if your Supabase dashboard labels it as an anon key
-# NEXT_PUBLIC_SUPABASE_ANON_KEY=...
+```bash
+npx supabase login
+npx supabase link --project-ref YOUR_PROJECT_REF
+npx supabase db push
+npx supabase secrets set ANTHROPIC_API_KEY=your-server-side-key
+npx supabase functions deploy FUNCTION_NAME
 ```
 
-These values are for the client application only.
-
-## Edge function secrets
+Deploy each function under `supabase/functions/` that your environment needs. Do not use JWT-verification bypass flags when deploying protected functions.
 
-The AI features require this secret in Supabase Edge Functions:
+## Environment variables
 
-```env
-ANTHROPIC_API_KEY=...
-```
+Copy [`.env.example`](.env.example) to `.env.local` for local frontend development.
 
-Without that secret, features like quiz generation, material extraction, syllabus parsing, AI tutoring, and screenshot/calendar parsing will fail.
+| Variable | Scope | Requirement |
+| --- | --- | --- |
+| `NEXT_PUBLIC_SUPABASE_URL` | Public/client-safe | Required for the web app |
+| `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` | Public/client-safe | Required for the web app |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Public/client-safe | Optional compatibility alias for the publishable key |
+| `ANTHROPIC_API_KEY` | Server-side secret | Optional; required only to enable AI-backed Edge Functions |
 
-## Database and backend deployment
+Supabase supplies its platform variables to deployed Edge Functions. Never expose `ANTHROPIC_API_KEY` or `SUPABASE_SERVICE_ROLE_KEY` through a `NEXT_PUBLIC_` variable or commit them to the repository.
 
-This repository contains SQL migrations and Edge Functions, but they must be applied to your Supabase project before the backend changes are live.
+## Testing and CI
 
-Typical workflow:
+Run the local quality checks with:
 
-```sh
-supabase login
-supabase link --project-ref YOUR_PROJECT_REF
-supabase db push
-supabase functions deploy generate-quiz
-supabase functions deploy extract-material-text
-supabase functions deploy ai-tutor
-supabase functions deploy parse-syllabus
-supabase functions deploy parse-schedule-screenshot
-supabase functions deploy parse-academic-calendar
+```bash
+npm run typecheck
+npm run lint
+npm test
+npm run build
 ```
 
-## Important behavior
+The test suite covers authentication guards, quiz-generation quotas, academic-calendar validation, schedule/date normalization, local-date behavior, and shared helper behavior without making live Anthropic requests.
 
-- Quiz generation is course-specific and should only use indexed material tied to the selected course
-- PDF, image, and text uploads can be used for AI indexing
-- Some uploaded file types may be stored without being usable for quiz generation until extraction/indexing support exists
-- Quiz and tutoring quality depends on the amount and quality of uploaded course material
+GitHub Actions runs on pull requests and pushes to `main`. It performs a clean npm install, application typecheck, lint, tests, production build, and Deno typechecking for all six Supabase Edge Functions. CI does not require production secrets.
 
-## Build
+## Security and engineering improvements
 
-To create a production build:
+- Migrated the frontend from Vite/React Router to the Next.js App Router
+- Added user-scoped Row Level Security and Storage policies through versioned SQL migrations
+- Hardened authenticated Edge Function flows and user ownership checks
+- Restricted material extraction to database-owned storage paths
+- Added SSRF defenses for academic-calendar retrieval, including HTTPS-only URLs, DNS/IP validation, redirect checks, timeouts, and response limits
+- Added input/file validation, safer error handling, and quiz usage limits
+- Standardized on npm, audited dependencies, and removed obsolete scaffold dependencies
+- Replaced placeholder tests with focused utility and authentication tests
+- Added CI and separate Deno typechecking for Edge Functions
+- Improved responsive behavior, keyboard access, status feedback, and route-level loading/error states
 
-```sh
-npm run build
-```
-
-To run the production build locally:
+## Known showcase limitations
 
-```sh
-npm run start
-```
+- Anthropic-backed features require a server-side API key and are not enabled in the public showcase deployment.
+- DOCX and PPTX uploads can be stored, but the current AI indexing path is designed for PDF, image, and text content.
+- Some settings/integration controls and the top-level mock-exam launcher remain roadmap UI; course-level practice-exam generation is implemented.
 
-## Project goal
+## Future improvements
 
-StudyOS is designed to reduce fragmentation in student workflows. Instead of separating calendars, notes, deadlines, grades, and study tools across different apps, it keeps them in one system and uses AI only where it adds practical value.
+- Add a polished screenshot and short demo-video set using seeded showcase data
+- Persist profile, notification, and integration preferences
+- Expand structured extraction support for additional document formats
+- Add end-to-end browser tests and production observability
+- Consolidate practice-exam creation into one consistent workflow

package.json

@@ -18,7 +18,6 @@
   },
   "dependencies": {
     "@hookform/resolvers": "^3.10.0",
-    "@lovable.dev/cloud-auth-js": "^0.0.3",
     "@radix-ui/react-accordion": "^1.2.11",
     "@radix-ui/react-alert-dialog": "^1.1.14",
     "@radix-ui/react-aspect-ratio": "^1.1.7",