diff --git a/README.md b/README.md index 9617f49..e5f49df 100644 --- a/README.md +++ b/README.md @@ -4,60 +4,56 @@ An AI-assisted academic workspace for managing courses, schedules, materials, as [![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) -**[Live Demo: StudyOS on Vercel](https://semester-ai-companion.vercel.app)** +## [Live Demo: StudyOS on Vercel](https://semester-ai-companion.vercel.app) -> 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. +> Some AI functionality requires Anthropic API access. The public deployment intentionally does not expose an active API key to avoid uncontrolled usage costs. The integrations are implemented in the repository and can be enabled with the required server-side configuration. -## Overview +## Product preview -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. +Explore the current product through the [live application](https://semester-ai-companion.vercel.app). -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. +| Schedule and calendar | Assignment tracking | +| --- | --- | +| ![StudyOS weekly schedule with course filters and calendar events](./docs/screenshots/schedule.png) | ![StudyOS assignment dashboard with progress and course filters](./docs/screenshots/assignments.png) | +| **Course workspace** | **Quiz generation** | +| ![StudyOS course workspace with exams and mock-exam controls](./docs/screenshots/course-workspace.png) | ![StudyOS quiz generator with course and difficulty controls](./docs/screenshots/quiz-generator.png) | + +## What StudyOS does + +- Organizes courses, assignments, exams, schedules, grades, and graduation plans +- Presents upcoming work and academic progress in a focused dashboard +- Supports weekly and monthly calendars, study events, and academic-date imports +- Parses syllabi and schedule screenshots into reviewable academic data +- Stores course materials for user-scoped extraction and study workflows +- Generates course-grounded quizzes and practice exams and supports contextual tutoring +- Provides responsive navigation and explicit loading, error, empty, and success states + +## Engineering highlights + +- Migrated the original Vite and React Router SPA to the Next.js App Router +- Built Supabase authentication, Postgres, Storage, migrations, and Row Level Security-backed data flows +- Implemented and validated six Deno-based Supabase Edge Functions +- Hardened authenticated parsing, user-owned material access, and external academic-calendar retrieval +- Added HTTPS-only URL handling, DNS/private-address checks, redirect validation, timeouts, and response limits +- Added quiz usage controls, file/input validation, and safer client-facing errors +- Replaced placeholder tests with focused coverage and added GitHub Actions CI +- Standardized package management on npm and removed obsolete scaffold dependencies +- Improved responsive behavior, keyboard accessibility, route states, and mobile calendar usability +- Deployed the application and branch preview environments with Vercel ## 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. +The Next.js application runs on Vercel and communicates with Supabase for authenticated data and file storage. Privileged validation, file processing, external URL retrieval, and Anthropic requests 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 | +| UI and client state | Tailwind CSS, shadcn/ui, Radix UI, TanStack Query, Framer Motion | +| Authentication and data | Supabase Auth and Postgres with Row Level Security | +| File storage | Supabase Storage with user-scoped paths and policies | +| Server workflows | Six Deno-based Supabase Edge Functions | +| AI integration | Anthropic Messages API, called from Edge Functions | +| Delivery | Vercel and GitHub Actions | ## Tech stack @@ -67,22 +63,21 @@ The browser application is deployed on Vercel and communicates directly with Sup **Quality and delivery:** Vitest, Testing Library, ESLint, TypeScript, npm, GitHub Actions, Vercel -## AI functionality +## Project evolution and AI-assisted development -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. +StudyOS started as a Lovable prototype for quickly validating the product idea. I then used it as a sandbox for experimenting with AI-assisted development workflows and progressively took ownership of the architecture, security, testing, backend integration, and UX. -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. +The project evolved through a Vite-to-Next.js migration, deeper Supabase integration, authentication and Edge Function hardening, automated testing, CI, dependency cleanup, and accessibility and responsive-UX improvements. -## Local development +## Testing and CI + +The repository includes 17 focused tests covering authentication guards, quiz-generation quotas, academic-calendar validation, schedule/date normalization, local-date behavior, and shared helpers. Tests do not make live Anthropic calls. -### Prerequisites +GitHub Actions runs on pull requests and pushes to `main`, performing a clean install, application typecheck, lint, tests, production build, and Deno typechecking for all six Edge Functions. -- Node.js 20 or newer -- npm -- A Supabase project -- Supabase CLI access if applying migrations or deploying Edge Functions +## Local development -### Run the web application +Requires Node.js 20+, npm, and a Supabase project. ```bash git clone https://github.com/WaseemGhanem98/semester-ai-companion.git @@ -92,65 +87,25 @@ cp .env.example .env.local npm run dev ``` -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. - -### Configure the backend - -The repository includes the database migrations and all six Edge Functions. A typical Supabase workflow is: - -```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 -``` - -Deploy each function under `supabase/functions/` that your environment needs. Do not use JWT-verification bypass flags when deploying protected functions. +Then open [http://localhost:3000](http://localhost:3000). Google sign-in requires a configured provider and matching redirect URL in Supabase Auth. ## Environment variables -Copy [`.env.example`](.env.example) to `.env.local` for local frontend development. +See [`.env.example`](./.env.example) for safe placeholders. -| Variable | Scope | Requirement | +| Variable | Scope | Purpose | | --- | --- | --- | -| `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 | - -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. - -## Testing and CI - -Run the local quality checks with: - -```bash -npm run typecheck -npm run lint -npm test -npm run build -``` - -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. +| `NEXT_PUBLIC_SUPABASE_URL` | Public/client-safe | Supabase project URL | +| `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` | Public/client-safe | Browser-accessible project key | +| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Public/client-safe | Optional compatibility alias | +| `ANTHROPIC_API_KEY` | Server-side secret | Enables supported AI-backed Edge Functions | -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. +Secrets such as `ANTHROPIC_API_KEY` and `SUPABASE_SERVICE_ROLE_KEY` must never use a `NEXT_PUBLIC_` prefix or be committed. -## Security and engineering improvements +## Demo limitations and roadmap -- 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 +The public deployment is intended as a portfolio showcase. Anthropic-backed workflows are disabled to control API costs, while their implementation remains available in the repository. Some experimental features remain under active development. -## Known showcase limitations +## Live demo -- 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. +**[Open StudyOS on Vercel →](https://semester-ai-companion.vercel.app)** diff --git a/docs/screenshots/assignments.png b/docs/screenshots/assignments.png new file mode 100644 index 0000000..8204be2 Binary files /dev/null and b/docs/screenshots/assignments.png differ diff --git a/docs/screenshots/course-workspace.png b/docs/screenshots/course-workspace.png new file mode 100644 index 0000000..503adbe Binary files /dev/null and b/docs/screenshots/course-workspace.png differ diff --git a/docs/screenshots/quiz-generator.png b/docs/screenshots/quiz-generator.png new file mode 100644 index 0000000..466f7ba Binary files /dev/null and b/docs/screenshots/quiz-generator.png differ diff --git a/docs/screenshots/schedule.png b/docs/screenshots/schedule.png new file mode 100644 index 0000000..9756ea5 Binary files /dev/null and b/docs/screenshots/schedule.png differ