Class Companion
A classroom companion for adult ESOL (English for Speakers of Other Languages) learners and their teachers. The app brings grammar guides, vocabulary practice, classroom games, assignments, and progress tracking into one mobile-friendly learning space.
Meaningful effort earns recognition: students receive points for practice and participation, with additional rewards for achievement. Reliable credit, clear feedback, and access to learning on a phone are core product requirements.
For reviewers
Start with the codebase tour, then see contributing for checks and change conventions. The documentation index separates implementation notes, classroom resources, audits, and planning.
This repository contains both the application and the teaching materials it supports. Curriculum files and printable handouts are intentional parts of the project.
What the app does
- Learners: complete grammar, vocabulary, speaking, and writing activities; play practice games; follow assignments and course-map work; view feedback and progress.
- Teachers: manage classes and enrollment, assign activities, and review student work.
- Practice rewards: points, streaks, achievements, and class leaderboards, with safeguards against duplicate awards from retries.
- Mobile access: responsive layouts and an installable progressive web app. Offline submission queueing is controlled by a feature flag.
Stack
Next.js 16 App Router · React · TypeScript · PostgreSQL · Prisma 6 · NextAuth · Tailwind CSS 4. Tests use Vitest, Node's test runner, and Playwright; GitHub Actions runs the CI checks. Exact dependency versions are recorded in package-lock.json.
Local setup
Use Node.js 20.9 or newer (CI currently uses Node 20), npm, and a separate PostgreSQL development database. CI uses PostgreSQL 16. Use the committed npm lockfile for reproducible installs.
From a cloned checkout:
cp .env.example .env
Edit .env before proceeding:
| Variable | Local value |
|---|
DATABASE_URL | Connection string for your development PostgreSQL database |
NEXTAUTH_URL | http://localhost:3000 |
NEXTAUTH_SECRET | Generate with openssl rand -base64 32 |
DEV_SEED_ACCOUNT_PASSWORD | A unique password for local seeded accounts |
TEST_STUDENT_DEFAULT_PASSWORD | A unique password for system-created test accounts |
Additional integrations and feature flags are described in .env.example. Keep local credentials out of Git. An existing .env.local can override app settings from .env; ensure both point to the intended development services.
Install dependencies, apply committed migrations, and seed the development database:
npm ci
npm run ci:db:prepare
npm run db:seed
npm run db:seed:achievements
npm run db:seed:course-map
npm run dev
Open localhost:3000. The base seed creates the administrator account marlie and student accounts such as ricardo, using DEV_SEED_ACCOUNT_PASSWORD for newly created accounts. A password change is required at first login. Re-running the base seed preserves existing passwords.
These commands populate a development database; they are not a complete copy of the live classroom. Additional activity seeds are listed in package.json and the scripts index.
Quality checks
The standard pre-push check runs types, lint, Vitest coverage, and Node tests without migrating or seeding a database:
npm run check:push
npm run check:repo-hygiene
For individual checks:
npm run typecheck
npm run lint
npm test
Install the optional tracked pre-push hook with npm run hooks:install. Content audits are included in the test suite; npm run test:content runs just those checks.
Builds write to the configured database. npm run build generates Prisma, runs the migration wrapper, seeds course-map data, and builds Next.js. Use an isolated development/test database. The health:* gates that invoke a build also have these side effects.
Playwright expects a production build and seeded E2E accounts. On an isolated test database:
npm run test:e2e:install
npm run ci:e2e:setup
npm run build
npm run test:e2e:smoke
See .github/workflows/ci.yml for the automated environment and CONTRIBUTING.md for review expectations.
Repository map
| Path | Contents |
|---|
src/app/ | App Router pages, layouts, and API handlers |
src/components/ | Activity renderers, games, dashboards, and shared UI |
src/lib/ | Authentication, database access, progress, rewards, and domain logic |
src/content/ | Authored learning content, including grammar guides |
src/types/ | Shared TypeScript domain types |
prisma/ | Database schema, migrations, and seeds |
tests/ | Unit, route, content, and browser tests |
scripts/ | Content generation, audits, imports, and operational tools |
public/ | Static assets and service worker |
FY26/, |
Product and engineering references
Releases
Small changes are batched locally before release. Before a production deployment or promotion, fetch GitHub and verify the exact source includes the latest origin/main; then verify the live domain and record the deployed source commit. See AGENTS.md for the full release requirements and deployment notes for operational context.
Usage
Free for educational use. Created by teachers, for teachers.
