Roles & Permissions

CSMS uses a four-level admin + student permission model. Management scope converges top-down: a higher level can manage lower levels, but cannot operate across data outside its own scope.

Roles Overview

Role	Scope	Core Capabilities
super_admin Super Admin	Global (no affiliated school)	School onboarding review, announcements, system settings, admin management, passwordless login to any admin account, cross-school bans
school_admin School Admin	School only	Manage school's grades, teacher accounts, classes
grade_admin Grade Admin	School + Grade	Manage grade's classes, view grade data
class_admin Class Admin (Homeroom)	School + Grade + Class	Student management, score adjustments, seating, statistics
Student	Self	View own scores, class ranking, edit personal info

Scope Logic (Horizontal × Vertical)

At the code level (server/utils/auth.ts), permissions converge via three dimensions: schoolId / gradeId / classId:

• Super admin / School admin: gradeId and classId being null means "all" (whole school).
• Grade admin: only operates classes within its own grade.
• Class admin: only operates its own class.

An admin's "affiliation" can be edited by the super admin per management level; options are constrained by level. For example, a class admin cannot be promoted to manage other classes.

Cross-school Isolation

Each school has its own database file (data/schools/{schoolId}.db), routed at the application layer via useSchoolDb(event, schoolId). Lower-level admins requesting another school's data are rejected by the permission middleware — no cross-school read or write.

API Token Issuance Scope

The scope of external Open API tokens is forced to not exceed the issuer's own scope:

• A school admin can issue tokens covering at most its own school.
• A class admin can only scope tokens to its own class.

See .

Student Side

Students log in with an independent Token (distinct from admin Session). They can only view their own scores, their class ranking, and edit non-sensitive personal info (e.g. username). Student APIs are prefixed with /api/student/**.