Chom Learn

One platform for students, teachers and parents across many schools. This repository is a monorepo: every app and shared package lives here, managed with pnpm workspaces and Turborepo.

Layout

apps/                   Workspace apps (every folder here is picked up automatically)
  web/                  Next.js web app at chom.co.za: sign-in, onboarding and
                        the web version for students and parents
  staff/                Next.js staff dashboard at staff.chom.co.za, for teachers
                        and school admins. Its own Vercel project (chom-staff)
  mobile/               Expo (React Native) app for iOS and Android: one app,
                        the signed-in person's role picks the experience
packages/               Shared workspace packages (picked up automatically)
  api/                  The typed data client shared by web and mobile, with
                        TypeScript types generated from the database
  tokens/               Design tokens: colours, type, spacing, radius.
                        TypeScript for mobile, tokens.css for web
  tsconfig/             Shared TypeScript settings
static/                 The student dashboard (no-build HTML), copied into
                        apps/web at build time and served at chom.co.za/app
  site/app/             The dashboard itself
  shared/               Its subject styles
supabase/               The database: migrations (structure and access rules),
                        test seed data and automated access tests
docs/
  decisions/            Architecture decision records (start with 0001)
  design/               Design spec shared by the learner and staff dashboards
scripts/
  build.mjs             Builds static/ into dist/
  gen-db-types.sh       Regenerates the database types (pnpm db:types)

To add a shared package, create a folder under packages/ with a package.json named @chom/<name>. No other registration is needed.

Getting started

Requires Node 22.6+ (the unit tests run TypeScript directly) and pnpm 10 (corepack enable installs the right version).

pnpm install

Command	What it does
pnpm dev:web	Run the web app at http://localhost:3000
pnpm dev:staff	Run the staff dashboard at http://localhost:3001
pnpm dev:mobile	Start Expo. Open on a phone with Expo Go, or an iOS/Android simulator
pnpm typecheck	Type-check every package
pnpm lint	ESLint for web and mobile (no warnings allowed), plus the design-token check
pnpm test	Unit tests (for example the check that blocks secret keys in apps)
pnpm format	Format everything with Prettier
pnpm format:check	Check formatting without changing files (what CI runs)
pnpm build	Production build of the web app
pnpm db:start	Start a local Supabase (needs Docker); applies migrations and test data
pnpm db:test	Run the database access and integrity tests
pnpm db:reset	Rebuild the local database from scratch
pnpm db:types	Regenerate packages/api/src/database.types.ts after changing the schema
pnpm db:stop	Stop the local Supabase

ESLint fails if code imports a package its own package.json doesn't list. node_modules is flat (Expo needs this), so without that rule an undeclared package would quietly work locally and break elsewhere.

Secrets and environment files

Never commit .env files. Every .env and .env.* file is ignored by git, and CI fails if one is force-added. To document which settings an app needs, commit a .env.example next to it with the variable names and no real values.

Database

Supabase (PostgreSQL), as decided in ADR 0001. Production is the Supabase project chom.co.za (eu-west-1, Ireland).

Structure. Every change to the database is a numbered file in supabase/migrations/, reviewed like code. Never change the production database through the dashboard.

Many schools, one database. Every school-scoped row carries school_id. Foreign keys include school_id, so the database itself refuses links across schools, for example enrolling a learner in another school's class.

Core tables.

This is the beginning of the README. Read the rest at the original. Read the full README ↗