College Tracking Platform

A full-stack web application for managing linear algebra coursework and tracking academic performance. The repository uses a pnpm monorepo with shared packages for the React client, Express API server and PostgreSQL database layer.

Key Features

• Google Authentication (Supabase OAuth) – every user gets a private, isolated workspace secured with JWTs.
• Minimal Public Landing Page – unauthenticated visitors see a sleek hero section and can sign-in; authenticated users are redirected to their dashboard.
• Semester & GPA Tracking – server-side GPA aggregation ensures a single source of truth; instant React visualisations powered by React-Query caching.
• Exam Calendar – create, edit and track upcoming exams with a calendar-first UI.
• Digital Library – upload PDFs to Supabase Storage; AI (Gemini) extracts title/author/TOC for quick navigation.
• AI-assisted Parsing – paste transcript text or UF "class card" HTML and the parser auto-creates semesters + courses.
• Syllabus Auto-Upload – when creating classes, uploaded syllabus files are automatically saved to Materials with proper categorization.
• Inline Class Creation – create new classes on-the-fly during exam creation with an intelligent Combobox interface.
• Real-time WebSocket Worker – background queue (packages/queues) ready for long-running tasks like OCR or summarisation.

Repository Layout

client/     React frontend
server/     Express backend
db/         Database schema and migrations
shared/     Shared types and utilities
packages/   Reusable packages (e.g. queues)
tests/      Unit and integration tests

See the architecture document for a detailed breakdown of the updated stack.

Getting Started

Prerequisites

• Node.js 20+
• pnpm (npm install -g pnpm)
• PostgreSQL

Setup

1. Install dependencies

   pnpm install

2. Create a .env file in the project root with your database connection

   DATABASE_URL=postgresql://user:password@localhost:5432/database

3. Start the development servers

   pnpm dev

Useful Commands

• pnpm dev – run client and server in development mode
• pnpm build – build all packages
• pnpm db:push – apply database migrations
• pnpm db:seed – seed the database
• pnpm lint – run ESLint
• pnpm format – run Prettier
• pnpm check – TypeScript type checking
• pnpm test – run the test suite

Code Quality

The repository uses ESLint, Prettier and Husky pre-commit hooks to maintain consistent code style. TypeScript strict mode ensures type safety across all packages.

Contributing

1. Fork the repository and create a feature branch.
2. Make your changes and ensure all tests pass.
3. Submit a pull request for review.

License

MIT

📂 Course Materials (Phase 2)

The new Course Materials system lets you upload and view PDFs, Word docs (DOCX), Excel workbooks (read-only placeholder), and images.

Quick start

1. Fire up the API + web client:

   pnpm dev

2. In a separate terminal run the AI queue worker (embeddings):

   pnpm queue:worker

3. Open http://localhost:5173 → Materials page → upload a file. The viewer automatically shows progress while OpenAI embeddings are generated in the background.

Technical notes

• Files are stored in Supabase Storage bucket materials at materials/{userId}/{uuid}.{ext}.
• Metadata lives in course_materials table with soft delete and RLS identical to books.
• Background job type material-embedding (BullMQ, Redis) extracts text (pdf.js/mammoth) then stores vectors in material_page_embeddings for semantic search.
• Front-end hooks (useMaterials, useAddMaterial …) leverage React Query and invalidation.
• Unified <DocumentViewer/> chooses PDF or DOCX renderer automatically; sidebar supports live editing.

See architecture/assignments_implementation_plan.md for a diagram contrasting the textbooks and course materials flows.

🎓 Enhanced Class & Exam Management

Syllabus Auto-Upload

When creating a new class through /classes/new, any uploaded syllabus files are automatically saved to the Materials section with:

• Title: #[Class Name] Syllabus
• Category: Syllabus
• Auto-organization: Files appear immediately in the class's materials for easy access

To disable this feature (e.g., for storage cost concerns), set the environment variable:

VITE_AUTO_SYLLABUS_UPLOAD=false

Deferred Class Creation Workflow

The exam creation page now supports intelligent class creation with AI-powered syllabus processing:

Feature Control

Enable the workflow with an environment variable:

VITE_INLINE_CLASS_CREATE=true

How It Works

1. Smart Detection: When saving exams, the system identifies classes that don't exist yet
2. User Choice: An AlertDialog prompts with two options:
   • "Create & Save": Automatically creates missing classes and processes any available syllabus content
   • "Skip": Saves exams without creating classes
3. Background Processing: New classes trigger automatic syllabus analysis to extract assignments
4. Real-time Feedback: Toast notifications inform users when syllabus processing completes

Benefits

• Streamlined Workflow: No need to pre-create classes before entering exam data
• Automatic Enrichment: Syllabus content becomes assignments automatically
• User Control: Choose when to create classes vs. proceed with existing data
• Cache Consistency: All course lists update immediately after class creation

This feature eliminates workflow friction while maintaining data integrity and providing intelligent defaults.