# 2026-07-22 — Phase 1 PR 2: student cohorts (frontend closeout)

**Branch:** `feature/admin-cohorts-2026-07-22`
**Owner:** fchin
**Scope:** finish the cohorts surface — frontend (list / detail / form), routes, nav, E2E

## What landed

This is the closeout commit for PR 2. The backend (controller, Knex
migration, store, list page, detail page) was already on the feature
branch from earlier work; this PR adds the missing frontend surface so
the feature is actually usable from the browser.

### Schema (recap — already on branch)

- New Knex migration `2026072200000020_cohorts.js`:
  - `student_cohorts` — programme (zimsec/igcse/as/a2/primary/other) + level + academic_year + description + date range + is_active
  - `cohort_students` — many-to-many to `users` (only students), with `status` (active/inactive/transferred/graduated)
  - `cohort_classes` — many-to-many to `classes`
  - `cohort_exam_groups` — many-to-many to `exam_groups` (so a cohort can pick the right exam paper set)
  - `enrollments.cohort_id` — nullable FK added via ALTER (backfill is a separate, non-blocking op)
  - All four tables follow the standard sync contract (uid, sync_status, last_synced_at, is_deleted)
  - Unique indexes on (cohort_id, student_id) and similar for the other two join tables

### Backend (recap — already on branch)

- `server/src/controllers/cohorts.controller.js`:
  - 10 endpoints: list, detail, create, update, soft-delete, bulk-add students, remove student, link class, unlink class, link exam group, unlink exam group
  - `requireAdmin` for writes; `canRead` (`school_admin | systems_admin | principal`) for reads
  - Every write is audit-logged via `AuditService`
- `server/src/index.js` — controller mounted at `/api/cohorts`
- `server/src/services/SyncEngine.js` — 4 new tables appended to `tablesToSync` after `user_roles`, in FK dependency order

### Frontend (this PR)

- `client/src/store/cohorts.ts` (recap — already on branch) — Zustand store with `Cohort`, `CohortDetail` types, full CRUD + linking, `SUPPORTED_PROGRAMMES` constant
- `client/src/pages/admin/Cohorts.tsx` (recap) — list with programme / academic-year / search filters; card grid view; admin-only "New Cohort" button
- `client/src/pages/admin/CohortDetail.tsx` (recap, with edit button) — Overview / Students / Classes / Exam Groups tabs; admin-only Add/Link modals; new Edit button (admin only) → `/admin/cohorts/:id/edit`
- `client/src/components/CohortForm.tsx` (new) — modal for create + edit
  - Programme dropdown drives `level` suggestions via `PROGRAMME_LEVELS` map (ZIMSEC → ECD-A through Form 6, IGCSE → Year 1-2/IGCSE, AS → Form 5, A2 → Form 6, primary → Reception-Year 6, other → free-text)
  - Fields: name, programme, level (datalist — pick or free-text), academic_year, description, start_date, end_date, is_active
  - Same modal shell pattern as `CoverAssignmentForm` and `RoleBadge` siblings
- `client/src/App.tsx`:
  - `Cohorts`, `CohortDetail`, `CohortForm` imports
  - `CohortFormPage` wrapper (reuses the form modal for both `/admin/cohorts/new` and `/admin/cohorts/:id/edit`)
  - 4 new routes per role arm — school_admin, systems_admin (all 4 routes) and principal (read-only — list + detail only)
- `client/src/components/Nav.tsx`:
  - `Cohorts` entry (GraduationCap icon) added to school_admin, systems_admin, principal
  - Principal sees the entry as read-only; the page hides the "New Cohort" button

### E2E

- `client/e2e/cohorts.spec.ts` (new):
  - Admin happy-path: list mounts; create flow lands the new cohort on the list
  - RBAC: teacher and student get 403 on `GET /api/cohorts`
  - Principal read-only: list mounts, no "New Cohort" button
  - Skips cleanly if the principal demo account is missing from the seed
- `client/e2e/helpers/nav.ts` — `/admin/cohorts` added to `ROUTES_PER_ROLE.school_admin` and `ROUTES_PER_ROLE.systems_admin` (so the existing portal smoke walks the route)

## Decisions / why

- **Programme-driven level suggestions, not enforcement.** Different schools
  use different labels. The datalist is a hint, not a constraint.
- **One form modal, two routes.** `/new` and `/:id/edit` both render the same
  `CohortForm`. The page is a thin router-owned wrapper that loads the
  cohort in edit mode. This keeps the create + edit UI in lockstep
  automatically.
- **Principal is read-only at the route level.** No `/new` or `/:id/edit`
  route is mounted for principal. Belt-and-braces: the page also hides
  management buttons behind `canManage`.
- **No auto-create-on-class.** Intentional — keep cohort creation explicit
  so admins think about programme + year. The link is one click on the
  Classes tab.
- **`other` programme has no level suggestions.** Forces free-text so admins
  don't accidentally pick a misleading label.

## Out of scope (deferred)

- Bulk transfer between cohorts (PR 3+ follow-up if requested)
- Per-cohort enrollment report (Phase 2 dashboard)
- Cross-cohort timetable / shared subjects view
- Auto-backfill of `enrollments.cohort_id` for existing rows (will run on
  the next academic rollover, or via the `/admin/academic-rollover` UI)

## Verification

- [x] `npm run db:init` runs cleanly on a fresh DB (cohorts migration is
      forward-only, applied via Knex)
- [x] Backend smoke (run pre-closeout): create / list / detail / add student
      / link class / link exam group / remove student / unlink class all OK
- [ ] Browser smoke: navigate to `/admin/cohorts`, create one, open detail,
      add a student, link a class, soft-delete
- [ ] Principal sees the list and the read-only detail
- [ ] Teacher is denied 403 on `GET /api/cohorts` and on `/admin/cohorts`
      (ProtectedRoute redirects to their own dashboard)
- [ ] `npm run test:e2e -- --grep "@flow|Cohorts"` passes the new spec
- [ ] Portal smoke (`@smoke`) walks the new route without console errors