CueLearn Platform

CueLearn is a React + Supabase platform that helps teachers, students, and parents plan classes, monitor progress, and collaborate through AI-assisted workflows. The project bundles dashboards, gamification, grading, and scheduling tools under a single Vite application that can be deployed as a modern SPA.

Tech Stack

• Framework: React 19, TypeScript, Vite
• State & Data: Custom hooks, Context API, Supabase client
• UI Toolkit: Radix UI primitives, Lucide icons, Tailwind utilities
• Testing: Vitest, Testing Library, Playwright (E2E)
• Tooling: ESLint, Prettier, TypeScript project references

Getting Started

1. Install prerequisites

   • Node.js 18+ (LTS) and npm 10+
   • Supabase project with anon + service keys

2. Install dependencies

   npm install

3. Configure environment

   • Copy .env.example to .env.local
   • Fill in Supabase keys, optional OpenAI + Jitsi values

4. Set up the database (optional)

   npm run db:setup
   # When done working:
   npm run db:teardown

5. Run the dev server

   npm run dev

Architecture Overview

src/
├─ components/        # Feature- and widget-level UI
├─ hooks/             # Domain-specific data + state hooks
├─ services/          # Supabase + business logic modules
├─ contexts/          # React context providers (auth, theming, etc.)
├─ supabase/          # Client configuration and typed helpers
├─ utils/             # Pure helper functions
├─ test/              # Shared test utilities (Vitest + RTL)
├─ pages/             # Top-level routing targets
└─ types/             # Shared TypeScript types

• Patterns: Hooks encapsulate queries + mutations, while services keep Supabase interactions isolated from UI. Components pull from hooks and shared UI primitives in src/components/ui.
• Routing: Vite + React Router drive SPA navigation under main.tsx and App.tsx.
• Styling: Global styles live in src/index.css; Tailwind utilities and Radix components handle layout and interaction.

Development Workflow

Task	Command
Start dev server	npm run dev
Type check	npm run typecheck
Lint (ESLint + Prettier config)	npm run lint
Lint with autofix	npm run lint:fix
Run unit tests	npm run test
Watch unit tests	npm run test:watch
Run Playwright E2E	npm run test:e2e
Build for production	npm run build

Contributing

1. Branching: Create feature branches from main or the active feature branch (e.g., feature/standardization).
2. Coding standards:
   • Follow ESLint + Prettier rules (npm run lint before committing).
   • Type all error boundaries and avoid direct console.* usage (use the shared logger).
   • Prefer async/await over chained Promises in new code.
3. Testing: Add or update Vitest suites alongside logic changes. Use Playwright for UI flows when needed.
4. Commits & PRs:
   • Keep commits scoped and descriptive.
   • Reference related issues in PR descriptions.
   • Ensure CI (lint, typecheck, tests) passes before requesting review.
5. Database changes: Document schema migrations and update Supabase scripts if tables/functions change.

Support & Documentation

• docs/feature-checklist.md tracks ongoing feature readiness.
• .github/prompts/plan-codeStandardization.prompt.md documents the current standardization initiative.
• Use GitHub Discussions/Issues for questions or new proposals.