Kalinga

Kalinga is an offline-first teacher assistant prototype for multigrade classrooms. It combines class and learner management, date-specific attendance, ILAW lesson planning, shared resources, and Gabay—a page-aware Taglish teaching guide.

Prepare online, teach offline

The production app prepares its application files for offline reopening. Regular teachers can reopen their saved workspace on the same personal device, use saved lessons and attendance, and explicitly download PDFs for offline reading. Gabay AI and community features still need internet. Installing the PWA is optional; normal development does not register a service worker.

Read offline preparation, sign-out and verification limits before testing. Production-browser tests use synthetic Supabase fixtures, not real accounts. After building, run npm run test:offline with installed Chrome (or PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH). Actual Android and live-account acceptance remain separate checks.

Local development

Requirements: Node.js 22.13 or newer.

npm install
cp .env.example .env.local
npm run dev

Open http://localhost:3000. The interface and local Gabay guidance work even before the backend values are added.

Supabase setup

Create a Supabase project, then copy its Project URL and publishable key into .env.local:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your_publishable_key

Never place the Supabase service-role key in the browser environment or commit it to Git.

Link this repository to the project and apply the schema:

npx supabase login
npx supabase link --project-ref YOUR_PROJECT_REF
npx supabase db push --dry-run
npx supabase db push

The migration creates teacher-owned profiles, classes, learners, lesson plans, attendance, resources, a private resource bucket, and row-level security policies. Each authenticated teacher can access only their own classroom records; only explicitly shared resource metadata is readable by other teachers.

Groq-powered Gabay

Gabay calls Groq only through a Supabase Edge Function, so the Groq key is never shipped to the browser. Add the secret and the allowed web origins:

npx supabase secrets set GROQ_API_KEY=YOUR_GROQ_KEY
npx supabase secrets set GROQ_MODEL=openai/gpt-oss-20b
npx supabase secrets set ALLOWED_ORIGINS=https://your-vercel-domain.vercel.app
npx supabase functions deploy gabay-chat

Only the origins in ALLOWED_ORIGINS may call the function. To develop against a deployed function, opt localhost in explicitly — leave this unset in production:

npx supabase secrets set ALLOW_LOCAL_ORIGINS=true

Each teacher may make 30 Gabay requests every 5 minutes. The counter lives in public.gabay_rate_limits and is only writable through the claim_gabay_request function, so a browser cannot reset its own quota. The check fails open: if it cannot run, the request is logged and allowed, because the limiter guards cost rather than access and should never be able to take Gabay down. Override the defaults with:

npx supabase secrets set GABAY_RATE_WINDOW_SECONDS=300
npx supabase secrets set GABAY_RATE_MAX_REQUESTS=30

Connected Gabay requires a valid Supabase user session. Prototype mode does not call the AI service or expose the secret.

The AI receives only the recent chat and minimal classroom context: the teacher’s preferred display name, current screen, grade levels, subject, lesson topic, and connection state. Saved learner names, reference numbers, attendance statuses, and notes are deliberately excluded.

Vercel

Add these two values to the Vercel project’s Environment Variables and redeploy:

• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY

Keep GROQ_API_KEY in Supabase Edge Function secrets, not Vercel’s public environment and never in source control.

Verification

npm run lint
npm test
npm run build

Migrations can be checked without Docker or a Supabase project. This applies every migration to a throwaway local Postgres and asserts the behaviour they produce — mention tags, notification triggers, the backfill, Gabay rate limiting, and that row-level security still isolates one teacher from another:

brew install postgresql@17
./scripts/verify-migrations.sh

It never touches a real database. Run it before supabase db push.