Students

The central register of every child in the school — profiles, class placement, documents, admissions, and student-facing logins.

What it does

Students is the system of record for every enrolled child in a school. Staff create and maintain a full profile per student — personal details, guardians, identity and health data, addresses, and academic placement — and attach supporting documents like birth certificates and transfer certificates. Each student can optionally be given a login so they see their own dashboard on the mobile app. The module also handles the messy real-world work of admitting students in bulk from a spreadsheet and promoting a whole class up a grade at year-end.

Who uses it

School admins / office staff — full create, edit, bulk import, promotion, and document management on the admin-web dashboard.
Students — read-only self-view of their own profile and summary on the mobile app.
All access is permission-gated under the student.* permission prefix (student.create, student.read, student.update, student.delete).

Key concepts

Student record — the core profile, keyed by a roll_number that is unique per tenant (not per class).
Admission number — a school-facing identifier assigned by the server (never taken from user input).
Class assignment — class_id ties a student to a class within an academic year; it changes on promotion.
User account — an optional linked login (user_id) so the student can sign in; a student may have none.
Student documents — files (birth certificate, TC, Aadhaar, ID proof) stored on AWS S3 with metadata in the DB; downloaded through an authenticated proxy, never public URLs.
Promotion batch — an audit record of a bulk class-change/promotion event.
Student status — a lifecycle enum: active, inactive, transferred, graduated, leaving, suspended, dropped_out.

How it works

Create / edit — staff fill a form (class selection is required — no silent fallback). Required fields are validated centrally (email, phone, Aadhaar, pincode, ISO dates). New students default to active; status is edit-only. Optionally a user login is created at the same time.
Class assignment & promotion — students are placed in a class per academic year. Bulk promotion moves selected students to a target class and writes a promotion-batch audit row. A preview endpoint gives a dry-run showing who moves and any conflicts before committing.
Documents — staff upload PDF/JPEG/PNG files (max 10 MB) against a document type; files land on S3 and are streamed back only to same-tenant users with permission.
Bulk import — an Excel/CSV upload with a preview (validate only, no writes) then a commit. Rows resolve to exactly one class from branch + programme + class_name + section; a wrong or missing branch/programme is a per-row error listing the real options.
Bulk actions — set status for many students at once, bulk delete, and CSV export of the filtered list.
Self-view — students hit their own dashboard summary (/api/students/me/dashboard), auth-gated but without needing student.read.

Rules & edge cases

Plan gating — every endpoint is gated by the student_management plan feature key; schools without it get no student module.
Tenant scoping — roll_number uniqueness, list results, and document access are all scoped to the tenant; one school can never read another’s students or files.
Soft delete — delete sets deleted_at; records aren’t physically removed, and default queries filter them out.
Admission numbers are server-assigned; any admission_number column in a bulk-import sheet is ignored.
Bulk-import disambiguation — branch matches on school-unit name/code, programme on name/code/board; ambiguity or a miss is surfaced as a row-level error rather than a silent guess. Phones are soft-validated (10–15 digits, dropped with a warning if invalid); several date formats accepted.
Records tab on the detail view (Fees / Attendance / Transport / Hostel summaries) is each independently permission-gated and hidden entirely when the user holds none of those permissions.

Where it lives

Backend: server/modules/students/ (API prefix /api/students)
Admin-web: /students list plus student detail and create/edit modal
Mobile: client/modules/students/
Plan feature key: student_management

Dashboard Attendance