1. Authentication & Session Security
Core session initialization, credential validation, JWT token exchange, impersonation, and logout workflows.
📍 Website Flow Placement
First step in the user journey. Invoked from the login screen (`/login`). Upon success, redirects users to their role-specific dashboard (`/student`, `/supervisor`, `/coordinator`, `/principal`, etc.).
🔗 Dependencies & Prerequisites
Requires user account to exist in `users` and `profiles` tables.
⚖️ Validation & Business Rules
Enforces brute-force rate limiting (5 attempts per 15 min). Passwords checked using bcrypt.compare. Returns `force_password_change` flag if first-time or temporary password is active.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| string | YES | Registered email address (case-insensitive, normalized). | |
| password | string | YES | Plaintext account password (evaluated against bcrypt hash). |
{
"email": "student@example.com",
"password": "SecurePassword123!"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| user.id | string (UUID) | Unique identifier of the authenticated user. |
| user.email | string | Verified email address. |
| user.full_name | string | Display name of the user. |
| user.role | string | Assigned role: student, supervisor, coordinator, principal, hod, college_admin, hospital_admin, superadmin. |
| user.college_id | string (UUID) | null | Associated college institution ID. |
| user.department_id | string (UUID) | null | Associated academic department ID. |
| flags.force_password_change | boolean | True if user must set a new password before accessing portal. |
| flags.requires_profile_completion | boolean | True if mandatory demographic/KYC fields are missing. |
{
"user": {
"id": "u-94820f12-88aa-4e12-b231-104928adbeef",
"email": "student@example.com",
"full_name": "Simran Kaur",
"role": "student",
"college_id": "c-10293847-56ba-4e99-8102-aabbccddeeff",
"department_id": "d-55667788-9900-4112-9988-112233445566"
},
"flags": {
"force_password_change": false,
"requires_profile_completion": false
}
}
📍 Website Flow Placement
Executed on every initial SPA load, page refresh, and router guard check to rehydrate user state.
🔗 Dependencies & Prerequisites
Requires active JWT cookie or Authorization header from previous login.
⚖️ Validation & Business Rules
Token signature verified with JWT_SECRET. Inactive users receive 401 with immediate logout trigger.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| user.id | string | User ID. |
| user.email | string | User email address. |
| user.full_name | string | User full name. |
| user.role | string | User primary system role. |
| user.college_id | string | null | Institutional college ID. |
| user.department_id | string | null | Department ID. |
| flags.force_password_change | boolean | Whether password reset is mandated. |
| flags.requires_profile_completion | boolean | Whether student/staff profile setup is incomplete. |
{
"user": {
"id": "u-94820f12-88aa-4e12-b231-104928adbeef",
"email": "student@example.com",
"full_name": "Simran Kaur",
"role": "student",
"college_id": "c-10293847-56ba-4e99-8102-aabbccddeeff",
"department_id": "d-55667788-9900-4112-9988-112233445566"
},
"flags": {
"force_password_change": false,
"requires_profile_completion": false
}
}
📍 Website Flow Placement
Triggered silently by the frontend HTTP interceptor upon receiving a 401 status on authenticated requests.
🔗 Dependencies & Prerequisites
Requires existing refresh token stored in browser cookie.
⚖️ Validation & Business Rules
Rotates refresh token and sets new expiry timestamp.
📥 Request Specification
{}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| user | object | Refreshed user profile object. |
{
"user": {
"id": "u-94820f12-88aa-4e12-b231-104928adbeef",
"email": "student@example.com",
"full_name": "Simran Kaur",
"role": "student"
}
}
📍 Website Flow Placement
Invoked when user clicks 'Logout' from navigation bar or user dropdown menu.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Clears `jwt` and `jwt_refresh` cookies by setting expiration to past epoch.
📥 Request Specification
{}
📤 Expected Response
Status Codes & Schema📍 Website Flow Placement
Triggered from User Account Security / Sessions settings page.
🔗 Dependencies & Prerequisites
Requires active authenticated session.
⚖️ Validation & Business Rules
Increments user `token_version` in DB, instantly invalidating all previously minted JWTs.
📥 Request Specification
{}
📤 Expected Response
Status Codes & Schema📍 Website Flow Placement
Security tab in User Profile settings.
🔗 Dependencies & Prerequisites
Requires authenticated session.
⚖️ Validation & Business Rules
Masks sensitive IP segments if privacy flags are enabled.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Session record ID. |
| [].ip_address | string | Client IP. |
| [].user_agent | string | Browser user agent string. |
| [].last_activity | string (ISO Date) | Timestamp of last request. |
| [].is_current | boolean | Whether this session matches current request. |
[
{
"id": "sess-8812-4411",
"ip_address": "103.21.144.10",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/128.0.0.0",
"last_activity": "2026-09-29T09:30:00.000Z",
"is_current": true
}
]
📍 Website Flow Placement
Invoked when user clicks 'Revoke Device' on the sessions list.
🔗 Dependencies & Prerequisites
Requires target session to belong to the authenticated user.
⚖️ Validation & Business Rules
Cannot revoke another user's session.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Session identifier to revoke. |
📤 Expected Response
Status Codes & Schema📍 Website Flow Placement
Triggered from Superadmin User Management panel via 'Impersonate' button.
🔗 Dependencies & Prerequisites
Requires target user account to exist and be active.
⚖️ Validation & Business Rules
Full audit trail logged with superadmin ID, target user ID, IP address, and timestamp.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| userId | string (UUID) | YES | Target user ID to impersonate. |
| password | string | YES | Superadmin's current password for re-authentication confirmation. |
{
"userId": "u-94820f12-88aa-4e12-b231-104928adbeef",
"password": "SuperAdminMasterPassword!"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Operation outcome. |
| user | object | Target user profile object with impersonated claims. |
{
"success": true,
"user": {
"id": "u-94820f12-88aa-4e12-b231-104928adbeef",
"email": "student@example.com",
"full_name": "Simran Kaur",
"role": "student",
"impersonated_by": "superadmin-master-id"
}
}
📍 Website Flow Placement
Legacy safety guard.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Direct open signups without verification are blocked.
📥 Request Specification
{}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| error | string | Guidance to use registration request workflow. |
{
"error": "Use the registration request workflow"
}
📍 Website Flow Placement
Legacy safety guard.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Direct password overwrite without OTP token is rejected.
📥 Request Specification
{}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| error | string | Instructional error message. |
{
"error": "Use the verified password-reset workflow"
}
📍 Website Flow Placement
Triggered on `/register` page when staff members sign up. Awaits Year Coordinator or Principal approval.
🔗 Dependencies & Prerequisites
Requires valid college/department reference.
⚖️ Validation & Business Rules
Stores password as bcrypt hash in `registration_requests` table. Prevents enumeration by returning generic acknowledgement.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| string | YES | Applicant's official email. | |
| password | string | YES | Proposed account password. |
| full_name | string | YES | Full legal name. |
| role | string | YES | Requested role: supervisor, coordinator, principal, student. |
| college_id | string (UUID) | OPT | College affiliation ID. |
| department_id | string (UUID) | OPT | Department ID. |
| hospital_id | string (UUID) | OPT | Hospital ID if clinical supervisor. |
| enrollment_no | string | OPT | PNRC Roll / Enrollment number (for students). |
{
"email": "teacher.manpreet@college.edu",
"password": "TeacherStrongPass1!",
"full_name": "Dr. Manpreet Singh",
"role": "supervisor",
"college_id": "c-10293847-56ba-4e99-8102-aabbccddeeff",
"department_id": "d-55667788-9900-4112-9988-112233445566"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Request status. |
| message | string | Acknowledgement notification. |
{
"success": true,
"message": "If eligible, the registration request will be reviewed."
}
2. Account Registration, External Verification & Student Activation
Multi-step student verification through the external council API, account activation, first-time OTP generation, and administrative approvals.
📍 Website Flow Placement
Primary entry point on the student activation screen (`/activate`). Initiates the student onboarding workflow.
🔗 Dependencies & Prerequisites
Calls external council API service (`studentProvisioningService.js`). Matches courses via `course_external_mappings` table.
⚖️ Validation & Business Rules
External passwords are never stored. Creates user with `force_password_change = 1`. Creates `student_academic_enrollments` record for Year 1. Sends 6-digit cryptographic OTP.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| enrollmentNo | string | YES | Official PNRC student enrollment/roll number. |
| mobile | string | YES | 10-digit mobile number matching external registration. |
| string | YES | Email address matching external registration. |
{
"enrollmentNo": "155854",
"mobile": "7018619880",
"email": "akash.veritos@gmail.com"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Indicates verification and provisioning status. |
| message | string | Status message. |
| studentCode | number | External council student code. |
| fullName | string | Student legal name from council records. |
| fatherName | string | Father's name. |
| motherName | string | Mother's name. |
| courseName | string | Resolved course name (e.g. GNM, ANM). |
| courseId | string (UUID) | Internal course ID. |
| academicYear | number | Initial academic year (Year 1). |
| string | Masked or confirmed email where OTP was dispatched. | |
| requiresFirstTimeSetup | boolean | True if student must complete OTP and password setup. |
{
"success": true,
"message": "Student verified successfully. A 6-digit OTP has been sent to your email.",
"studentCode": 155854,
"fullName": "TestSushanVeritos",
"fatherName": "TestingFatherName",
"motherName": "KRISHNA RANI",
"courseName": "General Nursing and Midwifery (GNM)",
"courseId": "c-gnm-4411-8899-0011",
"academicYear": 1,
"email": "akash.veritos@gmail.com",
"requiresFirstTimeSetup": true
}
📍 Website Flow Placement
Used by the activation modal to determine whether to prompt for OTP or direct the student to sign in.
🔗 Dependencies & Prerequisites
Requires user record in `users` table.
⚖️ Validation & Business Rules
Normalized lowercase email lookup.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| string | YES | Email address to check. |
{
"email": "akash.veritos@gmail.com"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| exists | boolean | Whether account exists. |
| status | string | Status: 'requires_setup', 'ready', 'inactive'. |
| requiresFirstTimeSetup | boolean | Whether first-time OTP and password setup is needed. |
| hasPendingOtp | boolean | Whether an unexpired OTP is waiting. |
{
"exists": true,
"status": "requires_setup",
"requiresFirstTimeSetup": true,
"hasPendingOtp": true
}
📍 Website Flow Placement
Step 2 of student account activation. Follows `/api/auth/verify-external-student`.
🔗 Dependencies & Prerequisites
Requires pending OTP stored in user's `reset_otp` column.
⚖️ Validation & Business Rules
OTP validated using constant-time hash comparison (`safeHashEqual`). Expires after 15 minutes.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| string | YES | Student email address. | |
| otp | string | YES | 6-digit verification code. |
{
"email": "akash.veritos@gmail.com",
"otp": "482910"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Verification outcome. |
| message | string | Confirmation instructions. |
{
"success": true,
"message": "OTP verified successfully. Please set your new password."
}
📍 Website Flow Placement
Triggered when user clicks 'Resend OTP' link on activation screen.
🔗 Dependencies & Prerequisites
Requires account in `requires_setup` state.
⚖️ Validation & Business Rules
Enforces 60-second cooldown period between successive OTP requests.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| string | YES | Student email address. |
{
"email": "akash.veritos@gmail.com"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Dispatch outcome. |
| message | string | Status message. |
{
"success": true,
"message": "A new 6-digit OTP has been sent to your email."
}
📍 Website Flow Placement
Final step of student account activation. Redirects to `/student` dashboard upon success.
🔗 Dependencies & Prerequisites
Requires valid unexpired OTP from verification step.
⚖️ Validation & Business Rules
Sets `force_password_change = 0`, sets `is_active = 1`, clears `reset_otp`, and issues httpOnly JWT session cookie.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| string | YES | Student email address. | |
| otp | string | YES | 6-digit OTP code. |
| newPassword | string | YES | New password (min 8 chars, uppercase, lowercase, number, symbol). |
{
"email": "akash.veritos@gmail.com",
"otp": "482910",
"newPassword": "StudentPermanentPassword2026!"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Setup completion status. |
| message | string | Success notification. |
| user | object | Newly activated user profile. |
{
"success": true,
"message": "Account setup complete. Welcome to PNRC Nursing E-Logbook.",
"user": {
"id": "u-94820f12-88aa-4e12-b231-104928adbeef",
"email": "akash.veritos@gmail.com",
"full_name": "TestSushanVeritos",
"role": "student"
}
}
📍 Website Flow Placement
Coordinator Dashboard -> Staff Approvals tab.
🔗 Dependencies & Prerequisites
Requires coordinator assignment.
⚖️ Validation & Business Rules
Scopes results to coordinator's institution and department.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | number | OPT | Pagination page number (default 1). |
| limit | query | number | OPT | Page size (default 20). |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| requests[].id | string | Request identifier. |
| requests[].email | string | Applicant email. |
| requests[].full_name | string | Applicant name. |
| requests[].role | string | Requested role. |
| requests[].created_at | string (ISO Date) | Submission date. |
{
"requests": [
{
"id": "req-1029-4411",
"email": "dr.gurpreet@college.edu",
"full_name": "Dr. Gurpreet Kaur",
"role": "supervisor",
"created_at": "2026-09-28T14:20:00.000Z"
}
],
"total": 1
}
📍 Website Flow Placement
Coordinator Dashboard -> Staff Approvals -> Approve/Reject action.
🔗 Dependencies & Prerequisites
Requires active registration request record.
⚖️ Validation & Business Rules
Transfers record from `registration_requests` into `users` and `profiles` in a single DB transaction.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| requestId | string (UUID) | YES | Registration request ID to resolve. |
| action | string | YES | Decision: 'approve' or 'reject'. |
| departmentId | string (UUID) | OPT | Assigned department on approval. |
| rejectionReason | string | OPT | Mandatory remarks if rejected. |
{
"requestId": "req-1029-4411",
"action": "approve",
"departmentId": "d-55667788-9900-4112-9988-112233445566"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Resolution outcome. |
| message | string | Status notification. |
{
"success": true,
"message": "Request approved and profile created"
}
📍 Website Flow Placement
Superadmin Portal -> User Approvals table.
🔗 Dependencies & Prerequisites
Pending request ID.
⚖️ Validation & Business Rules
Superadmin can approve requests across all colleges; College Admin restricted to own college.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| requestId | string (UUID) | YES | Target request ID. |
| action | string | YES | 'approve' | 'reject'. |
| rejectionReason | string | OPT | Reason if rejected. |
{
"requestId": "req-1029-4411",
"action": "approve"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Status. |
| message | string | Result message. |
{
"success": true,
"message": "Registration approved successfully."
}
3. Password Management & OTP Recovery
Authenticated self password modification, forgotten password recovery via OTP, and administrative credential resets.
📍 Website Flow Placement
User Profile -> Change Password modal, or forced password change interceptor on first login.
🔗 Dependencies & Prerequisites
Requires active session.
⚖️ Validation & Business Rules
Bcrypt hash with cost 12. Sets `force_password_change = 0`. Invalidates previous sessions if configured.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| currentPassword | string | YES | Existing password for confirmation. |
| newPassword | string | YES | New password (min 8 chars, uppercase, lowercase, digit, symbol). |
{
"currentPassword": "OldPassword123!",
"newPassword": "BrandNewSecurePassword2026!"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
| message | string | Confirmation message. |
{
"success": true,
"message": "Password changed successfully"
}
📍 Website Flow Placement
Forgot Password modal on login screen (`/forgot-password`).
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Timing-safe response: always returns 200 generic message to prevent account enumeration.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| string | YES | Account email address. |
{
"email": "student@example.com"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Always true to prevent email enumeration. |
| message | string | Generic instructions message. |
{
"success": true,
"message": "If an account exists with this email, an OTP code has been sent."
}
📍 Website Flow Placement
Step 2 of the Forgot Password dialog.
🔗 Dependencies & Prerequisites
Requires unexpired OTP issued by `/api/auth/send-forgot-password-otp`.
⚖️ Validation & Business Rules
Constant-time OTP hash check. OTP expires in 15 minutes. Clears `reset_otp` upon completion.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| string | YES | Account email address. | |
| otp | string | YES | 6-digit OTP code received via email. |
| newPassword | string | YES | New password. |
{
"email": "student@example.com",
"otp": "591820",
"newPassword": "RecoveredPassword2026!"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
| message | string | Confirmation notification. |
{
"success": true,
"message": "Password reset successfully"
}
📍 Website Flow Placement
Triggered when user clicks 'Send Verification Code' in Security Settings.
🔗 Dependencies & Prerequisites
Requires active session.
⚖️ Validation & Business Rules
Email must match authenticated user's email.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| string | YES | User email address. |
{
"email": "student@example.com"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Status. |
| message | string | Verification code sent notification. |
{
"success": true,
"message": "Verification code sent"
}
📍 Website Flow Placement
High-security password change verification step.
🔗 Dependencies & Prerequisites
Requires OTP sent via `/api/auth/send-otp-password-change`.
⚖️ Validation & Business Rules
Validates OTP with constant-time equality.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| otp | string | YES | 6-digit OTP code. |
| newPassword | string | YES | New password. |
{
"otp": "712934",
"newPassword": "NewSecurePassword2026!"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Status. |
| message | string | Confirmation. |
{
"success": true,
"message": "Account updated successfully"
}
📍 Website Flow Placement
Admin User Management -> Actions -> Reset Password.
🔗 Dependencies & Prerequisites
Target user must exist.
⚖️ Validation & Business Rules
Hashes password with bcrypt cost 12. College Admin cannot reset Superadmin or cross-college user passwords.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string (UUID) | YES | Target user ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| newPassword | string | YES | New password to set for the user. |
| forceChange | boolean | OPT | Whether user must change it upon next login (default true). |
{
"newPassword": "TemporaryPass2026!",
"forceChange": true
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
| message | string | Status. |
{
"success": true,
"message": "User password reset successfully."
}
4. Student Portal & Academic Records
Personal profile management, KYC documentation, academic year enrollment, assigned curriculum subjects, logbook entries, and annual appraisal self-ratings.
📍 Website Flow Placement
Primary initialization API invoked when Student logs into the portal (`/student`). Feeds student header bar, profile card, and active course metadata.
🔗 Dependencies & Prerequisites
Requires active record in `student_academic_enrollments`.
⚖️ Validation & Business Rules
Checks active enrollment where `enrollment_status = 'active'`. Returns `coordinator_name` without legacy single supervisor assumptions.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Student profile ID. |
| student_name | string | Full name. |
| roll_number | string | PNRC Roll / Enrollment number. |
| course_id | string | Course ID (e.g. GNM / ANM). |
| course_name | string | Course name. |
| college_id | string | College institution ID. |
| college_name | string | College name. |
| academic_year_number | number | Current active academic year (e.g. 1, 2, 3). |
| coordinator_name | string | null | Designated Year Coordinator name. |
| is_promoted | boolean | True if student has progressed beyond Year 1. |
| appraisal_status | string | null | Current annual appraisal status. |
{
"id": "sp-9901-4422",
"student_name": "Simran Kaur",
"roll_number": "155854",
"course_id": "c-gnm-4411-8899-0011",
"course_name": "General Nursing and Midwifery (GNM)",
"college_id": "col-1029-4411",
"college_name": "Government College of Nursing, Patiala",
"academic_year_number": 1,
"coordinator_name": "Dr. Jaswinder Kaur",
"is_promoted": false,
"appraisal_status": "pending_supervisor_review"
}
📍 Website Flow Placement
Student Dashboard -> Academic Progress card.
🔗 Dependencies & Prerequisites
Requires active enrollment.
⚖️ Validation & Business Rules
Filters by `student_id = req.user.id AND enrollment_status = 'active'`.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Enrollment record UUID. |
| student_id | string | Student user ID. |
| course_id | string | Enrolled course. |
| academic_year_number | number | Current year number (1, 2, 3). |
| enrollment_status | string | Status: 'active', 'completed', 'promoted'. |
| joining_date | string (Date) | Academic session start date. |
{
"id": "sae-1029-4411-8899",
"student_id": "u-94820f12-88aa-4e12-b231-104928adbeef",
"course_id": "c-gnm-4411-8899-0011",
"academic_year_number": 1,
"enrollment_status": "active",
"joining_date": "2025-08-01"
}
📍 Website Flow Placement
Clinical Logbook and Hospital Posting views.
🔗 Dependencies & Prerequisites
Requires active enrollment.
⚖️ Validation & Business Rules
Resolves hospital affiliation via student college hospital links.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Enrollment ID. |
| hospital_name | string | null | Assigned clinical hospital. |
| current_year | number | Academic year. |
{
"id": "sae-1029-4411-8899",
"hospital_name": "Rajindra Hospital, Patiala",
"current_year": 1
}
📍 Website Flow Placement
Student Portal -> Subjects & Teachers tab; Logbook entry creation modal (dropdown for subject selection).
🔗 Dependencies & Prerequisites
Requires active student academic year and subject teacher assignments.
⚖️ Validation & Business Rules
Enforces 1:1 mapping: each subject in an academic year is assigned to a dedicated teacher.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Subject master UUID. |
| [].name | string | Subject title (e.g. 'Bio-Sciences', 'Nursing Foundations'). |
| [].code | string | Course subject code. |
| [].academic_year_number | number | Academic year this subject belongs to. |
| [].teacher_id | string | null | Teacher user ID assigned to evaluate this subject. |
| [].teacher_name | string | null | Name of the dedicated subject teacher. |
[
{
"id": "sub-gnm1-bio",
"name": "Bio-Sciences (Anatomy & Physiology, Microbiology)",
"code": "GNM101",
"academic_year_number": 1,
"teacher_id": "u-prof-anand-001",
"teacher_name": "Prof. Anand Sharma"
},
{
"id": "sub-gnm1-found",
"name": "Fundamentals of Nursing",
"code": "GNM103",
"academic_year_number": 1,
"teacher_id": "u-dr-harpreet-002",
"teacher_name": "Dr. Harpreet Kaur"
}
]
📍 Website Flow Placement
Top alert banner on Student Portal notifying student if profile needs completion or verification.
🔗 Dependencies & Prerequisites
Student profile record.
⚖️ Validation & Business Rules
Locked from logbook submissions if status is 'rejected'.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| status | string | 'pending', 'verified', or 'rejected'. |
| is_complete | boolean | Whether all required profile fields are filled. |
| rejection_remark | string | null | Reason given by coordinator if rejected. |
| missing_fields | string[] | List of missing mandatory profile attributes. |
{
"status": "verified",
"is_complete": true,
"rejection_remark": null,
"missing_fields": []
}
📍 Website Flow Placement
Student Portal -> My Profile screen (`/student/profile`).
🔗 Dependencies & Prerequisites
Requires authenticated student.
⚖️ Validation & Business Rules
Aadhaar number masked except for last 4 digits in API response for privacy.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Profile UUID. |
| student_name | string | Full name. |
| father_name | string | Father's name. |
| mother_name | string | Mother's name. |
| date_of_birth | string (Date) | DOB (YYYY-MM-DD). |
| gender | string | Gender. |
| primary_mobile | string | Phone number. |
| email_id | string | Email address. |
| permanent_address | string | Permanent residential address. |
| correspondence_address | string | Correspondence address. |
| photo_url | string | null | URL to profile photograph. |
| aadhaar_number | string | null | Masked Aadhaar number. |
| pan_number | string | null | PAN number. |
| pmc_registration_number | string | null | Council registration number. |
| aadhaar_card_url | string | null | Document URL. |
| pan_card_url | string | null | Document URL. |
| pmc_certificate_url | string | null | Certificate URL. |
{
"id": "sp-9901-4422",
"student_name": "Simran Kaur",
"father_name": "Gurdev Singh",
"mother_name": "Kulwinder Kaur",
"date_of_birth": "2004-06-15",
"gender": "female",
"primary_mobile": "9876543210",
"email_id": "simran.kaur@example.com",
"permanent_address": "VPO Bhadson, Dist. Patiala, Punjab - 147202",
"correspondence_address": "Room 14, Girls Hostel, GCON Patiala",
"photo_url": "/uploads/u-94820f12/photo-avatar.jpg",
"aadhaar_number": "XXXXXXXX1234",
"pan_number": "ABCDE1234F",
"pmc_registration_number": "PNRC/GNM/2025/1102"
}
📍 Website Flow Placement
Student Portal -> Edit Profile -> Save Changes.
🔗 Dependencies & Prerequisites
Requires student profile record.
⚖️ Validation & Business Rules
Validates phone formats. Setting KYC values resets `verification_status` to 'pending' for coordinator audit.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| date_of_birth | string (YYYY-MM-DD) | OPT | Date of birth. |
| gender | string | OPT | Gender: male, female, other. |
| father_name | string | OPT | Father's name. |
| mother_name | string | OPT | Mother's name. |
| permanent_address | string | OPT | Full permanent address. |
| correspondence_address | string | OPT | Current mailing address. |
| primary_mobile | string | OPT | 10-digit mobile number. |
| secondary_mobile | string | OPT | Alternative emergency phone. |
| aadhaar_number | string | OPT | 12-digit Aadhaar number. |
| pan_number | string | OPT | 10-character PAN. |
| pmc_registration_number | string | OPT | State nursing council ID. |
| photo_url | string | OPT | Uploaded photo file path. |
{
"father_name": "Gurdev Singh",
"mother_name": "Kulwinder Kaur",
"date_of_birth": "2004-06-15",
"gender": "female",
"permanent_address": "VPO Bhadson, Dist. Patiala, Punjab - 147202",
"correspondence_address": "Room 14, Girls Hostel, GCON Patiala",
"primary_mobile": "9876543210"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Update status. |
| message | string | Success notification. |
{
"success": true,
"message": "Profile updated successfully"
}
📍 Website Flow Placement
Student Profile -> Upload Photo button.
🔗 Dependencies & Prerequisites
Requires authenticated student.
⚖️ Validation & Business Rules
Enforces max 5MB size limit. Replaces previous profile image.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| file | file (binary) | YES | Image file (JPEG/PNG up to 5MB). |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Upload outcome. |
| photo_url | string | Resolved photo path. |
{
"success": true,
"photo_url": "/uploads/u-94820f12/photo-avatar.jpg"
}
📍 Website Flow Placement
Student Portal -> Clinical Logbook tab.
🔗 Dependencies & Prerequisites
Requires active student profile.
⚖️ Validation & Business Rules
Restricted strictly to records where `student_id = req.user.id`.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| year | query | number | OPT | Filter by academic year (e.g. 1, 2, 3). |
| status | query | string | OPT | Filter by submission status ('submitted', 'approved', 'revision_requested'). |
| subject_id | query | string | OPT | Filter by specific subject ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Activity log UUID. |
| [].activity_date | string (Date) | Date procedure was performed. |
| [].subject_name | string | Curriculum subject. |
| [].competency_title | string | Specific clinical skill or procedure title. |
| [].status | string | Evaluation status. |
| [].supervisor_rating | number | null | Score given by evaluating teacher (1-5). |
| [].supervisor_feedback | string | null | Teacher remarks/critique. |
[
{
"id": "act-4411-8899",
"activity_date": "2026-09-20",
"subject_name": "Fundamentals of Nursing",
"competency_title": "Intravenous Cannulation & Infusion Setup",
"status": "approved",
"supervisor_rating": 5,
"supervisor_feedback": "Aseptic technique maintained throughout. Good patient rapport."
}
]
📍 Website Flow Placement
Student Portal -> Clinical Logbook -> 'New Entry' modal.
🔗 Dependencies & Prerequisites
Requires active academic enrollment and assigned subject teacher.
⚖️ Validation & Business Rules
Locks submission to the subject's 1:1 assigned teacher. Initial status set to 'submitted'.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| activity_date | string (YYYY-MM-DD) | YES | Date of procedure. |
| subject_id | string (UUID) | YES | Target subject identifier. |
| competency_id | string (UUID) | OPT | Competency being demonstrated. |
| activity_template_id | string (UUID) | OPT | Template form layout ID. |
| patient_type | string | OPT | Patient type (Adult, Pediatric, Geriatric, Antenatal). |
| clinical_notes | string | YES | Student's procedural summary and observations. |
| self_reflection | string | OPT | Student self-reflection on what went well and areas for improvement. |
| form_data | object | OPT | Dynamic procedure checklist values. |
{
"activity_date": "2026-09-29",
"subject_id": "sub-gnm1-found",
"competency_id": "comp-iv-cannula",
"patient_type": "Adult",
"clinical_notes": "Administered 500ml Normal Saline IV via 20G cannula in left cephalic vein under aseptic precautions.",
"self_reflection": "Found vein on first attempt; need to improve tape fixation speed."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Submission outcome. |
| id | string | Created activity record ID. |
| assigned_teacher | string | Teacher who will evaluate this entry. |
{
"success": true,
"id": "act-4411-8899",
"assigned_teacher": "Dr. Harpreet Kaur"
}
📍 Website Flow Placement
Student Portal -> Logbook -> 'Edit' or 'Resubmit' button.
🔗 Dependencies & Prerequisites
Existing logbook entry owned by student.
⚖️ Validation & Business Rules
Approved entries cannot be edited. Resubmission resets review status to pending.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string (UUID) | YES | Activity log ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| clinical_notes | string | OPT | Updated notes. |
| self_reflection | string | OPT | Updated reflection. |
| status | string | OPT | 'draft' or 'resubmitted'. |
{
"clinical_notes": "Updated documentation addressing teacher feedback on cannulation site care.",
"status": "resubmitted"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Logbook Entry Creation dropdown.
🔗 Dependencies & Prerequisites
Department ID in student profile.
⚖️ Validation & Business Rules
Filters to active types belonging to student's department.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Activity type ID. |
| [].name | string | Type title. |
| [].description | string | Clinical scope. |
[
{
"id": "at-clinical-ward",
"name": "Clinical Ward Procedure",
"description": "Routine inpatient nursing procedures and vital monitoring."
}
]
📍 Website Flow Placement
Student Portal -> Annual Appraisal tab.
🔗 Dependencies & Prerequisites
Requires active academic enrollment.
⚖️ Validation & Business Rules
Returns templates where `course_id` and `academic_year_number` match student's active enrollment.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Template UUID. |
| [].title | string | Appraisal template title (e.g. GNM 1st Year Annual Appraisal). |
| [].year_number | number | Academic year. |
[
{
"id": "tmpl-gnm-yr1",
"title": "GNM 1st Year Annual Appraisal & Competency Assessment",
"year_number": 1
}
]
📍 Website Flow Placement
Student Appraisal viewer modal.
🔗 Dependencies & Prerequisites
Template ID.
⚖️ Validation & Business Rules
Combines template headers with child question rows.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Template form ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Form ID. |
| title | string | Form title. |
| questions[].id | string | Question ID. |
| questions[].section | string | Domain section. |
| questions[].question_text | string | Evaluation criterion. |
{
"id": "tmpl-gnm-yr1",
"title": "GNM 1st Year Annual Appraisal",
"questions": [
{
"id": "q-prof-conduct",
"section": "Professional Demeanor",
"question_text": "Demonstrates punctuality, uniform adherence, and clinical ethics."
}
]
}
📍 Website Flow Placement
Appraisal form dynamic renderer.
🔗 Dependencies & Prerequisites
Form ID.
⚖️ Validation & Business Rules
Sorted by field display order.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Form ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].field_key | string | Key name. |
| [].label | string | Display label. |
| [].field_type | string | Input type (rating, text, number). |
[
{
"field_key": "attendance_percentage",
"label": "Total Clinical Attendance (%)",
"field_type": "number"
}
]
📍 Website Flow Placement
Student Portal -> Appraisal Records tab.
🔗 Dependencies & Prerequisites
Requires student identity.
⚖️ Validation & Business Rules
Read-only history view.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Appraisal submission ID. |
| [].year_number | number | Academic year evaluated. |
| [].status | string | Appraisal workflow state. |
| [].supervisor_rating | number | null | Overall supervisor score. |
| [].principal_approved_at | string | null | Final approval date. |
[
{
"id": "appr-2025-01",
"year_number": 1,
"status": "principal_approved",
"supervisor_rating": 4.8,
"principal_approved_at": "2026-09-15T11:00:00.000Z"
}
]
📍 Website Flow Placement
Student Portal -> Appraisal Details -> 'Acknowledge & Sign' button.
🔗 Dependencies & Prerequisites
Appraisal must be approved by Principal.
⚖️ Validation & Business Rules
Sets `student_signed_at = NOW()` and locks record against further modifications.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Appraisal record ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| student_comments | string | OPT | Optional student remarks. |
{
"student_comments": "I have reviewed my annual evaluation scores and feedback."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Sign-off outcome. |
| message | string | Confirmation notification. |
{
"success": true,
"message": "Appraisal signed successfully"
}
📍 Website Flow Placement
Student Portal -> Fees & Transactions tab.
🔗 Dependencies & Prerequisites
Student profile.
⚖️ Validation & Business Rules
Returns null if fee tracking is disabled or institutional direct-billing applies.
📥 Request Specification
📤 Expected Response
Status Codes & Schema5. Supervisor & Subject Teacher Portal
Subject teacher evaluation workflows, student logbook review queues, competency verification, and annual appraisal scoring.
📍 Website Flow Placement
Supervisor Dashboard -> 'My Students' roster.
🔗 Dependencies & Prerequisites
Requires active record in `subject_teacher_assignments`.
⚖️ Validation & Business Rules
Scopes students strictly to courses and academic years where the supervisor has an active subject assignment.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| academic_year | query | number | OPT | Filter by academic year number. |
| course_id | query | string | OPT | Filter by course. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Student user ID. |
| [].student_name | string | Student full name. |
| [].roll_number | string | Roll number. |
| [].course_name | string | Enrolled course. |
| [].academic_year_number | number | Year of study. |
| [].assigned_subjects | string[] | Subject(s) taught by this supervisor. |
[
{
"id": "u-94820f12-88aa-4e12-b231-104928adbeef",
"student_name": "Simran Kaur",
"roll_number": "155854",
"course_name": "GNM",
"academic_year_number": 1,
"assigned_subjects": [
"Fundamentals of Nursing"
]
}
]
📍 Website Flow Placement
Supervisor Student Detail Drawer.
🔗 Dependencies & Prerequisites
Supervisor-student relationship.
⚖️ Validation & Business Rules
Restricted to authorized teachers of the student.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| studentId | path | string | YES | Target student user ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| total_activities | number | Total logbook submissions. |
| approved | number | Approved submissions. |
| pending | number | Submissions awaiting evaluation. |
| revision_requested | number | Submissions sent back for correction. |
| average_rating | number | Mean competency rating (out of 5.0). |
{
"total_activities": 42,
"approved": 38,
"pending": 3,
"revision_requested": 1,
"average_rating": 4.6
}
📍 Website Flow Placement
Supervisor Dashboard -> 'Submissions Review Queue'.
🔗 Dependencies & Prerequisites
Assigned subjects.
⚖️ Validation & Business Rules
Only displays activities belonging to subjects the teacher is authorized to evaluate.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | string | OPT | Filter: 'submitted', 'resubmitted', 'approved', 'rejected'. |
| student_id | query | string | OPT | Filter by student. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Activity ID. |
| [].student_name | string | Student name. |
| [].subject_name | string | Subject title. |
| [].activity_date | string | Procedure date. |
| [].clinical_notes | string | Procedure notes. |
| [].status | string | Current status. |
[
{
"id": "act-4411-8899",
"student_name": "Simran Kaur",
"subject_name": "Fundamentals of Nursing",
"activity_date": "2026-09-29",
"clinical_notes": "Administered 500ml Normal Saline IV via 20G cannula.",
"status": "submitted"
}
]
📍 Website Flow Placement
Supervisor Review Queue -> Evaluate Modal -> Submit Review.
🔗 Dependencies & Prerequisites
Submission must belong to a subject assigned to this teacher.
⚖️ Validation & Business Rules
Strict authorization: verifies teacher assignment in `subject_teacher_assignments`.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string (UUID) | YES | Activity submission ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| status | string | YES | 'approved', 'rejected', or 'revision_requested'. |
| supervisor_rating | number | YES | Integer competency rating between 1 and 5. |
| supervisor_feedback | string | OPT | Constructive feedback and guidance. |
{
"status": "approved",
"supervisor_rating": 5,
"supervisor_feedback": "Demonstrated excellent aseptic technique. Log approved."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
| message | string | Confirmation notification. |
{
"success": true,
"message": "Activity submission marked as approved"
}
📍 Website Flow Placement
Profile Verification tab.
🔗 Dependencies & Prerequisites
Cohort assignment.
⚖️ Validation & Business Rules
Restricted to assigned students.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Profile ID. |
| [].student_name | string | Student name. |
| [].verification_status | string | Verification state. |
[
{
"id": "sp-9901-4422",
"student_name": "Simran Kaur",
"verification_status": "pending"
}
]
📍 Website Flow Placement
Profile Verification screen.
🔗 Dependencies & Prerequisites
Profile record.
⚖️ Validation & Business Rules
Sets `verified_at` and `verified_by` audit fields.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Student profile ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| status | string | YES | 'verified' | 'rejected'. |
| rejection_remark | string | OPT | Reason if rejected. |
{
"status": "verified"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Supervisor Dashboard -> Annual Appraisals tab.
🔗 Dependencies & Prerequisites
Appraisal cycle active.
⚖️ Validation & Business Rules
Scoped to teacher's academic cohort.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Appraisal ID. |
| [].student_name | string | Student name. |
| [].year_number | number | Academic year. |
| [].status | string | Workflow state. |
[
{
"id": "appr-2026-9901",
"student_name": "Simran Kaur",
"year_number": 1,
"status": "pending_supervisor_review"
}
]
📍 Website Flow Placement
Appraisal Archive view.
🔗 Dependencies & Prerequisites
Cohort linkage.
⚖️ Validation & Business Rules
Read-only access.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Supervisor Appraisal Scoring sheet.
🔗 Dependencies & Prerequisites
Appraisal submission.
⚖️ Validation & Business Rules
Teacher must supervise student's cohort.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | query | string | YES | Appraisal or enrollment ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Appraisal ID. |
| student_name | string | Student name. |
| responses | array | Detailed response questions and marks. |
{
"id": "appr-2026-9901",
"student_name": "Simran Kaur",
"responses": [
{
"question_id": "q-prof-conduct",
"rating": 5,
"remarks": "Exemplary attitude and attendance."
}
]
}
6. Year Coordinator Portal
Academic year cohort oversight, performance aggregation across all subjects, and intermediate review of annual appraisals.
📍 Website Flow Placement
Coordinator Dashboard overview.
🔗 Dependencies & Prerequisites
Requires coordinator assignment in `year_coordinator_assignments`.
⚖️ Validation & Business Rules
Scoped to coordinator's institution, course, and year.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].course_name | string | Course. |
| [].total_students | number | Enrolled students. |
| [].average_completion | number | Percentage of competencies completed. |
[
{
"course_name": "GNM 1st Year",
"total_students": 45,
"average_completion": 82.5
}
]
📍 Website Flow Placement
Coordinator Dashboard -> Annual Review tab.
🔗 Dependencies & Prerequisites
Teacher evaluation completed.
⚖️ Validation & Business Rules
Displays records where `status = 'supervisor_evaluated'`.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Appraisal ID. |
| [].student_name | string | Student name. |
| [].supervisor_rating | number | Score given by teacher. |
[
{
"id": "appr-2026-9901",
"student_name": "Simran Kaur",
"supervisor_rating": 4.8
}
]
📍 Website Flow Placement
Coordinator Appraisal Review Sheet.
🔗 Dependencies & Prerequisites
Appraisal in reviewable state.
⚖️ Validation & Business Rules
Moves status to `hod_verified` / `coordinator_approved`.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Appraisal ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| status | string | YES | 'coordinator_approved' or 'revision_requested'. |
| remarks | string | OPT | Coordinator comments. |
{
"status": "coordinator_approved",
"remarks": "All 1st year clinical mandates and classroom requirements fulfilled."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Coordinator Detailed Appraisal Inspection modal.
🔗 Dependencies & Prerequisites
Appraisal ID.
⚖️ Validation & Business Rules
Restricted to coordinator's cohort.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | query | string | YES | Submission ID. |
📤 Expected Response
Status Codes & Schema{}
7. Principal & Institutional Administration
College-wide institutional governance, comprehensive analytics, leave resolutions, and final annual appraisal sign-offs.
📍 Website Flow Placement
Principal Dashboard landing view (`/principal`).
🔗 Dependencies & Prerequisites
Principal role.
⚖️ Validation & Business Rules
Scoped strictly to `req.user.college_id`.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| totalStudents | number | Total enrolled students in college. |
| totalFaculty | number | Total faculty members. |
| pendingActivities | number | Activities awaiting faculty action. |
| pendingLeaves | number | Leave requests awaiting resolution. |
| pendingAppraisals | number | Appraisals awaiting principal approval. |
{
"totalStudents": 180,
"totalFaculty": 18,
"pendingActivities": 14,
"pendingLeaves": 3,
"pendingAppraisals": 12
}
📍 Website Flow Placement
Principal Dashboard -> Analytics tab.
🔗 Dependencies & Prerequisites
Principal role.
⚖️ Validation & Business Rules
Institutional scope enforced.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| departmentBreakdown | array | Enrollment by department. |
| activityTrends | array | Submission velocity trends. |
{
"departmentBreakdown": [
{
"department_name": "GNM",
"count": 120
},
{
"department_name": "ANM",
"count": 60
}
],
"activityTrends": [
{
"week": "W38",
"approved": 140,
"submitted": 155
}
]
}
📍 Website Flow Placement
Principal college management tabs.
🔗 Dependencies & Prerequisites
College ID.
⚖️ Validation & Business Rules
Scoped to college.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Department ID. |
| [].name | string | Department name. |
[
{
"id": "dept-gnm-01",
"name": "General Nursing & Midwifery"
},
{
"id": "dept-anm-01",
"name": "Auxiliary Nurse Midwifery"
}
]
📍 Website Flow Placement
Principal Staff Directory.
🔗 Dependencies & Prerequisites
College linkage.
⚖️ Validation & Business Rules
College scope.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Staff user ID. |
| [].full_name | string | Name. |
| [].role | string | Role. |
[
{
"id": "u-coord-01",
"full_name": "Dr. Jaswinder Kaur",
"role": "coordinator"
}
]
📍 Website Flow Placement
Principal Faculty Management view.
🔗 Dependencies & Prerequisites
College linkage.
⚖️ Validation & Business Rules
College scope.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Teacher user ID. |
| [].full_name | string | Teacher name. |
[
{
"id": "u-prof-anand-001",
"full_name": "Prof. Anand Sharma"
}
]
📍 Website Flow Placement
Principal Student Directory (`/principal/students`).
🔗 Dependencies & Prerequisites
College linkage.
⚖️ Validation & Business Rules
Restricted to principal's college.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| year | query | number | OPT | Filter by academic year. |
| search | query | string | OPT | Search by student name or roll number. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Student ID. |
| [].full_name | string | Student name. |
| [].roll_number | string | Roll number. |
| [].course_name | string | Course. |
| [].academic_year_number | number | Year of study. |
[
{
"id": "u-94820f12-88aa-4e12-b231-104928adbeef",
"full_name": "Simran Kaur",
"roll_number": "155854",
"course_name": "GNM",
"academic_year_number": 1
}
]
📍 Website Flow Placement
Top search bar on Principal Portal.
🔗 Dependencies & Prerequisites
College linkage.
⚖️ Validation & Business Rules
Minimum 2 characters.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| q | query | string | YES | Search keyword. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Entity ID. |
| [].title | string | Display label. |
| [].type | string | 'student', 'faculty', 'department'. |
[
{
"id": "u-94820f12",
"title": "Simran Kaur (155854)",
"type": "student"
}
]
📍 Website Flow Placement
Principal Clinical Audit tab.
🔗 Dependencies & Prerequisites
College linkage.
⚖️ Validation & Business Rules
College scope.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Principal Contested Submissions view.
🔗 Dependencies & Prerequisites
Activity record.
⚖️ Validation & Business Rules
Logs executive resolution audit.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Activity ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| action | string | YES | 'approve' | 'reject'. |
| remarks | string | YES | Resolution rationale. |
{
"action": "approve",
"remarks": "Verified with Clinical Instructor; procedure meets criteria."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
| message | string | Status. |
{
"success": true,
"message": "Activity approved successfully"
}
📍 Website Flow Placement
Principal Leaves Management panel.
🔗 Dependencies & Prerequisites
College linkage.
⚖️ Validation & Business Rules
Scoped to college.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Leave request ID. |
| [].applicant_name | string | Applicant. |
| [].reason | string | Leave reason. |
| [].start_date | string | Start date. |
| [].end_date | string | End date. |
[
{
"id": "l-4411-8899",
"applicant_name": "Simran Kaur",
"reason": "Medical Leave (Fever)",
"start_date": "2026-09-25",
"end_date": "2026-09-27"
}
]
📍 Website Flow Placement
Principal Leave Approval modal.
🔗 Dependencies & Prerequisites
Leave application.
⚖️ Validation & Business Rules
Notifies student/staff of approval.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Leave ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| action | string | YES | 'approve' | 'reject'. |
| remarks | string | OPT | Remarks. |
{
"action": "approve",
"remarks": "Approved as per medical certificate."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
| message | string | Status. |
{
"success": true,
"message": "Leave approved successfully"
}
📍 Website Flow Placement
Principal Dashboard -> Annual Appraisal Sign-offs.
🔗 Dependencies & Prerequisites
Coordinator endorsement completed.
⚖️ Validation & Business Rules
Approval unlocks student eligibility for Year Promotion (`POST /api/promotion/promote`).
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Appraisal ID. |
| [].student_name | string | Student name. |
| [].year_number | number | Academic year. |
| [].status | string | Workflow state. |
[
{
"id": "appr-2026-9901",
"student_name": "Simran Kaur",
"year_number": 1,
"status": "coordinator_approved"
}
]
8. Subject & Coordinator Assignments
Institutional governance enforcing 1:1 dedicated teacher assignments per subject in each academic year, and designated Year Coordinator assignments per cohort.
📍 Website Flow Placement
Invoked on Supervisor Dashboard load to filter submission queues, competencies, and student rosters.
🔗 Dependencies & Prerequisites
Requires active assignment in `subject_teacher_assignments` table.
⚖️ Validation & Business Rules
Filters by `teacher_id = req.user.id AND is_active = 1`.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Query success flag. |
| subjects[].id | string | Assignment ID. |
| subjects[].subject_id | string | Curriculum subject ID. |
| subjects[].subject_name | string | Subject title. |
| subjects[].subject_code | string | Subject code. |
| subjects[].course_id | string | Course ID. |
| subjects[].course_name | string | Course name. |
| subjects[].academic_year_number | number | Academic year (1, 2, 3). |
{
"success": true,
"subjects": [
{
"id": "sta-4411-8899",
"subject_id": "sub-gnm1-found",
"subject_name": "Fundamentals of Nursing",
"subject_code": "GNM103",
"course_id": "c-gnm-4411-8899-0011",
"course_name": "General Nursing and Midwifery (GNM)",
"academic_year_number": 1
}
]
}
📍 Website Flow Placement
College Admin / Principal / Coordinator -> Subject Assignments management page.
🔗 Dependencies & Prerequisites
Requires subjects and teachers registered in the college.
⚖️ Validation & Business Rules
Non-superadmins are restricted to viewing assignments for their own `college_id`.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| college_id | query | string | OPT | College filter (mandatory for superadmin if not specified). |
| course_id | query | string | OPT | Filter by course. |
| academic_year_number | query | number | OPT | Filter by academic year (1, 2, 3). |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
| data[].id | string | Assignment ID. |
| data[].teacher_id | string | Teacher ID. |
| data[].teacher_name | string | Teacher name. |
| data[].subject_id | string | Subject ID. |
| data[].subject_name | string | Subject title. |
| data[].course_name | string | Course name. |
| data[].academic_year_number | number | Year. |
{
"success": true,
"data": [
{
"id": "sta-4411-8899",
"teacher_id": "u-prof-anand-001",
"teacher_name": "Prof. Anand Sharma",
"subject_id": "sub-gnm1-bio",
"subject_name": "Bio-Sciences (Anatomy & Physiology, Microbiology)",
"course_name": "General Nursing and Midwifery (GNM)",
"academic_year_number": 1
}
]
}
📍 Website Flow Placement
Coordinator / Principal -> Subject Assignment -> 'Assign Teacher' modal.
🔗 Dependencies & Prerequisites
Requires subject in `subjects` table and teacher profile in `profiles` table.
⚖️ Validation & Business Rules
Architecture Constraint: Strictly 1:1 teacher per subject. Enforced via database unique check and service level validation.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| teacher_id | string (UUID) | YES | Faculty user ID to assign. |
| subject_id | string (UUID) | YES | Curriculum subject ID. |
| course_id | string (UUID) | YES | Course ID. |
| academic_year_number | number | YES | Academic year (1, 2, 3). |
| college_id | string (UUID) | OPT | College ID (required for superadmin). |
{
"teacher_id": "u-dr-harpreet-002",
"subject_id": "sub-gnm1-found",
"course_id": "c-gnm-4411-8899-0011",
"academic_year_number": 1,
"college_id": "col-1029-4411"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
| message | string | Status message. |
| assignment_id | string | Newly created assignment ID. |
{
"success": true,
"message": "Subject teacher assigned successfully",
"assignment_id": "sta-4411-8899-0012"
}
📍 Website Flow Placement
Subject Assignments table -> 'Remove Assignment' button.
🔗 Dependencies & Prerequisites
Existing assignment record.
⚖️ Validation & Business Rules
Soft-deletes by setting `is_active = 0`.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string (UUID) | YES | Assignment ID to deactivate. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
| message | string | Status. |
{
"success": true,
"message": "Assignment deactivated"
}
📍 Website Flow Placement
Principal Dashboard -> Coordinator Assignments tab.
🔗 Dependencies & Prerequisites
College linkage.
⚖️ Validation & Business Rules
Restricted to user's college scope.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| college_id | query | string | OPT | Filter by college ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
| data[].id | string | Assignment ID. |
| data[].coordinator_name | string | Coordinator name. |
| data[].course_name | string | Course title. |
| data[].academic_year_number | number | Year of study. |
{
"success": true,
"data": [
{
"id": "yca-1029-4411",
"coordinator_name": "Dr. Jaswinder Kaur",
"course_name": "General Nursing and Midwifery (GNM)",
"academic_year_number": 1
}
]
}
📍 Website Flow Placement
Principal Portal -> 'Assign Year Coordinator' modal.
🔗 Dependencies & Prerequisites
Requires coordinator profile.
⚖️ Validation & Business Rules
Inserts record into `year_coordinator_assignments` with `is_active = 1`.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| coordinator_id | string (UUID) | YES | Coordinator user ID. |
| course_id | string (UUID) | YES | Course ID. |
| academic_year_number | number | YES | Academic year (1, 2, 3). |
| college_id | string (UUID) | OPT | College ID. |
{
"coordinator_id": "u-coord-01",
"course_id": "c-gnm-4411-8899-0011",
"academic_year_number": 1,
"college_id": "col-1029-4411"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
| message | string | Status message. |
| assignment_id | string | Assignment ID. |
{
"success": true,
"message": "Coordinator assigned to year successfully",
"assignment_id": "yca-1029-4411"
}
📍 Website Flow Placement
Coordinator Assignments table -> 'Remove' action.
🔗 Dependencies & Prerequisites
Assignment record.
⚖️ Validation & Business Rules
Soft-deletes record (`is_active = 0`).
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Assignment ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
| message | string | Status. |
{
"success": true,
"message": "Coordinator assignment deactivated"
}
9. Annual Appraisal & Academic Promotion Workflow
Multi-tier annual competency appraisals (Supervisor Evaluation -> Coordinator Endorsement -> Principal Approval) and academic progression promotion from Year N to Year N+1.
📍 Website Flow Placement
Supervisor Portal -> Annual Appraisal Assessment tab.
🔗 Dependencies & Prerequisites
Active cohort students.
⚖️ Validation & Business Rules
Filters students in active enrollment.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Student ID. |
| [].student_name | string | Student name. |
| [].academic_year_number | number | Current year. |
| [].completed_logs | number | Total approved logbook entries. |
[
{
"id": "u-94820f12-88aa-4e12-b231-104928adbeef",
"student_name": "Simran Kaur",
"academic_year_number": 1,
"completed_logs": 45
}
]
📍 Website Flow Placement
Supervisor Appraisal Evaluation screen.
🔗 Dependencies & Prerequisites
Template seeded in `annual_appraisal_templates`.
⚖️ Validation & Business Rules
Matches student's `course_id` and `academic_year_number`.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| studentId | path | string (UUID) | YES | Student ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| form_title | string | Appraisal template name. |
| questions[].id | string | Question ID. |
| questions[].criterion | string | Competency criterion. |
| questions[].max_rating | number | Maximum score (e.g. 5). |
{
"form_title": "GNM 1st Year Annual Competency Assessment",
"questions": [
{
"id": "q-aseptic-technique",
"criterion": "Adherence to aseptic standards and infection control.",
"max_rating": 5
}
]
}
📍 Website Flow Placement
Supervisor Appraisal scoring -> 'Save Draft' button.
🔗 Dependencies & Prerequisites
Student enrollment.
⚖️ Validation & Business Rules
Status remains `draft`.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| studentId | string (UUID) | YES | Student ID. |
| responses | array | YES | Array of { question_id, score, remarks }. |
| remarks | string | OPT | Overall supervisor remarks. |
{
"studentId": "u-94820f12-88aa-4e12-b231-104928adbeef",
"responses": [
{
"question_id": "q-aseptic-technique",
"score": 5,
"remarks": "Excellent compliance"
}
],
"remarks": "Progressing very well in clinical fundamentals."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
| appraisalId | string | Draft appraisal ID. |
{
"success": true,
"appraisalId": "appr-2026-9901"
}
📍 Website Flow Placement
Supervisor Appraisal sheet -> 'Submit Evaluation' button.
🔗 Dependencies & Prerequisites
Draft appraisal record.
⚖️ Validation & Business Rules
Sets status to `supervisor_evaluated` and timestamps submission.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string (UUID) | YES | Appraisal record ID. |
{}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
| message | string | Status. |
{
"success": true,
"message": "Appraisal submitted to Coordinator for review."
}
📍 Website Flow Placement
Coordinator Appraisal Review panel -> 'Verify & Forward' button.
🔗 Dependencies & Prerequisites
Appraisal in `supervisor_evaluated` status.
⚖️ Validation & Business Rules
Sets status to `hod_verified`.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string (UUID) | YES | Appraisal ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| remarks | string | OPT | Coordinator comments. |
{
"remarks": "Verified against clinical logbook attendance criteria."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Coordinator Review panel -> 'Request Revision' action.
🔗 Dependencies & Prerequisites
Appraisal record.
⚖️ Validation & Business Rules
Sets status to `revision_requested` and notifies supervisor.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Appraisal ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| remarks | string | YES | Mandatory revision instructions. |
{
"remarks": "Please verify cannulation competency logs before rating section 2."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Principal Dashboard -> Appraisal Approval queue -> 'Approve' button.
🔗 Dependencies & Prerequisites
Appraisal must be in `hod_verified` status.
⚖️ Validation & Business Rules
Sets status to `principal_approved`, records `principal_approved_at = NOW()`, unlocking promotion.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Appraisal ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| remarks | string | OPT | Principal final remarks. |
{
"remarks": "Approved for progression to Year 2."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Principal Appraisal Review queue -> 'Return' button.
🔗 Dependencies & Prerequisites
Appraisal record.
⚖️ Validation & Business Rules
Sets status to `revision_requested`.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Appraisal ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| remarks | string | YES | Return reason. |
{
"remarks": "Discrepancy in clinical ward hours. Please re-audit."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Principal / Coordinator Promotion panel -> Select Student -> View Eligibility card.
🔗 Dependencies & Prerequisites
Requires active enrollment and appraisal records.
⚖️ Validation & Business Rules
Course duration check: ANM max 2 years, GNM max 3 years. Rejects promotion if appraisal is not in `principal_approved` state.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| studentId | path | string (UUID) | YES | Student user ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| eligible | boolean | True if student can be promoted to next year. |
| currentYear | number | Active year (e.g. 1). |
| nextYear | number | null | Proposed next year (e.g. 2), or null if graduating. |
| isFinalYear | boolean | True if student is in final course year (GNM Year 3, ANM Year 2). |
| appraisalApproved | boolean | Whether principal-approved appraisal exists. |
| reason | string | null | Explanation if not eligible. |
{
"eligible": true,
"currentYear": 1,
"nextYear": 2,
"isFinalYear": false,
"appraisalApproved": true,
"reason": null
}
📍 Website Flow Placement
Principal Portal -> Academic Promotion panel -> 'Promote Student' action button.
🔗 Dependencies & Prerequisites
Verified eligibility via `/api/promotion/eligibility/:studentId`.
⚖️ Validation & Business Rules
Atomic transaction. Previous enrollment status set to 'completed'. New enrollment created with status 'active'. Links to Year N+1 Coordinator. Promotion audit record saved in `student_promotion_history`.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| studentId | string (UUID) | YES | Student user ID to promote. |
| remarks | string | OPT | Promotion endorsement notes. |
{
"studentId": "u-94820f12-88aa-4e12-b231-104928adbeef",
"remarks": "Successfully cleared GNM Year 1 exams and annual clinical appraisal."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Promotion outcome. |
| message | string | Confirmation details. |
| previousYear | number | Archived academic year. |
| newYear | number | New active academic year. |
| newEnrollmentId | string | Newly created enrollment UUID. |
{
"success": true,
"message": "Student promoted to Year 2 successfully",
"previousYear": 1,
"newYear": 2,
"newEnrollmentId": "sae-yr2-1029-4411"
}
📍 Website Flow Placement
Student Profile -> Academic Progression tab; Principal Audit view.
🔗 Dependencies & Prerequisites
Promotion history table.
⚖️ Validation & Business Rules
Ordered chronologically by `promoted_at` DESC.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| studentId | path | string (UUID) | YES | Student ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | History record ID. |
| [].from_year | number | Previous year. |
| [].to_year | number | New year. |
| [].promoted_by_name | string | Principal who authorized promotion. |
| [].promoted_at | string (ISO Date) | Date of promotion. |
| [].remarks | string | null | Endorsement remarks. |
[
{
"id": "ph-2026-001",
"from_year": 1,
"to_year": 2,
"promoted_by_name": "Dr. K. S. Mann (Principal)",
"promoted_at": "2026-09-29T10:00:00.000Z",
"remarks": "Successfully cleared GNM Year 1 exams and annual clinical appraisal."
}
]
10. Clinical Activities, Logbook & Competencies
Clinical procedure tracking, competency rubrics, dynamic procedure forms, category hierarchies, and submission evaluation lifecycles.
📍 Website Flow Placement
Student Activity Logbook; Supervisor review grid.
🔗 Dependencies & Prerequisites
Student enrollment.
⚖️ Validation & Business Rules
Students view own records; supervisors view assigned cohort.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | string | OPT | Filter: 'draft', 'submitted', 'approved', 'rejected'. |
| year | query | number | OPT | Academic year. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Activity ID. |
| [].activity_date | string | Date performed. |
| [].status | string | Review status. |
[
{
"id": "act-01",
"activity_date": "2026-09-28",
"status": "approved"
}
]
📍 Website Flow Placement
New Log Entry modal.
🔗 Dependencies & Prerequisites
Active subject teacher.
⚖️ Validation & Business Rules
Sets initial status to 'submitted'.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| activity_date | string | YES | Procedure date (YYYY-MM-DD). |
| subject_id | string | YES | Subject ID. |
| competency_id | string | OPT | Competency ID. |
| clinical_notes | string | YES | Observations. |
{
"activity_date": "2026-09-29",
"subject_id": "sub-gnm1-found",
"clinical_notes": "Nasogastric tube insertion under sterile technique."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Created ID. |
{
"id": "act-9912"
}
📍 Website Flow Placement
Activity details drawer.
🔗 Dependencies & Prerequisites
Record ID.
⚖️ Validation & Business Rules
Must be owner or authorized teacher.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Activity ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | ID. |
{
"id": "act-9912",
"status": "approved",
"clinical_notes": "NG tube insertion."
}
📍 Website Flow Placement
Edit activity screen.
🔗 Dependencies & Prerequisites
Owned activity.
⚖️ Validation & Business Rules
Cannot update once approved.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Activity ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| clinical_notes | string | OPT | Updated notes. |
{
"clinical_notes": "Corrected procedure notes."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Delete button on draft log.
🔗 Dependencies & Prerequisites
Draft entry.
⚖️ Validation & Business Rules
Only draft entries may be deleted by students.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Activity ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Status. |
{
"success": true
}
📍 Website Flow Placement
Rejected Activity -> 'Reattempt' action.
🔗 Dependencies & Prerequisites
Rejected activity.
⚖️ Validation & Business Rules
Links parent activity ID in audit trail.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Previous activity ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| clinical_notes | string | YES | New procedure documentation. |
{
"clinical_notes": "Repeat attempt at catheterization under direct observation."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Status. |
| new_activity_id | string | New ID. |
{
"success": true,
"new_activity_id": "act-9913"
}
📍 Website Flow Placement
Activity History drawer.
🔗 Dependencies & Prerequisites
Activity record.
⚖️ Validation & Business Rules
Read-only timeline.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Activity ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].status | string | State transition. |
| [].created_at | string | Timestamp. |
[
{
"status": "submitted",
"created_at": "2026-09-29T09:00:00Z"
}
]
📍 Website Flow Placement
Supervisor Review Table.
🔗 Dependencies & Prerequisites
Subject assignment.
⚖️ Validation & Business Rules
Authorized subjects only.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Supervisor Evaluation modal.
🔗 Dependencies & Prerequisites
Authorized subject.
⚖️ Validation & Business Rules
Rating must be 1 to 5.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Activity ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| status | string | YES | 'approved' | 'rejected' | 'revision_requested'. |
| supervisor_rating | number | YES | Score (1-5). |
| supervisor_feedback | string | OPT | Feedback notes. |
{
"status": "approved",
"supervisor_rating": 4,
"supervisor_feedback": "Well executed."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Faculty Review screen.
🔗 Dependencies & Prerequisites
Activity record.
⚖️ Validation & Business Rules
Faculty permissions required.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Activity ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| status | string | YES | 'approved' | 'rejected'. |
{
"status": "approved"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Logbook form builder.
🔗 Dependencies & Prerequisites
Master templates.
⚖️ Validation & Business Rules
Active templates only.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Template ID. |
| [].title | string | Title. |
[
{
"id": "tmpl-01",
"title": "Vital Signs Recording Form"
}
]
📍 Website Flow Placement
Admin Form Builder.
🔗 Dependencies & Prerequisites
Admin rights.
⚖️ Validation & Business Rules
Unique title.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| title | string | YES | Template name. |
{
"title": "Pediatric Immunization Record"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Created ID. |
{
"id": "tmpl-02"
}
📍 Website Flow Placement
Form Renderer.
🔗 Dependencies & Prerequisites
Template ID.
⚖️ Validation & Business Rules
Read-only.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Template ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Template ID. |
{
"id": "tmpl-01",
"title": "Vital Signs"
}
📍 Website Flow Placement
Form Editor.
🔗 Dependencies & Prerequisites
Template ID.
⚖️ Validation & Business Rules
Admin check.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Template ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| title | string | YES | New title. |
{
"title": "Updated Template Title"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Form Builder Delete.
🔗 Dependencies & Prerequisites
Template ID.
⚖️ Validation & Business Rules
Cannot delete if referenced by existing student submissions.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Template ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Clone Template button.
🔗 Dependencies & Prerequisites
Source template.
⚖️ Validation & Business Rules
Appends '(Copy)' to title.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Template ID. |
{}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Cloned ID. |
{
"id": "tmpl-01-copy"
}
📍 Website Flow Placement
Form Renderer.
🔗 Dependencies & Prerequisites
Template ID.
⚖️ Validation & Business Rules
Ordered by sequence.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| templateId | path | string | YES | Template ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].field_key | string | Field key. |
[
{
"field_key": "systolic_bp"
}
]
📍 Website Flow Placement
Form Builder -> Add Field.
🔗 Dependencies & Prerequisites
Template ID.
⚖️ Validation & Business Rules
Field key must be unique per template.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| templateId | path | string | YES | Template ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| field_key | string | YES | Slug. |
| field_type | string | YES | 'text', 'number', 'select'. |
{
"field_key": "pulse_rate",
"field_type": "number"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Created field ID. |
{
"id": "f-101"
}
📍 Website Flow Placement
Global fields browser.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Read-only.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Field settings.
🔗 Dependencies & Prerequisites
Field ID.
⚖️ Validation & Business Rules
Admin only.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Field ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| label | string | YES | Updated label. |
{
"label": "Pulse Rate (bpm)"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Field delete action.
🔗 Dependencies & Prerequisites
Field ID.
⚖️ Validation & Business Rules
Checks for existing response dependencies.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Field ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Logbook Category selector.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Sorted alphabetically.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Category ID. |
| [].name | string | Name. |
[
{
"id": "cat-01",
"name": "Labor & Delivery"
}
]
📍 Website Flow Placement
Admin Category management.
🔗 Dependencies & Prerequisites
Admin role.
⚖️ Validation & Business Rules
Unique title.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | YES | Category title. |
{
"name": "Neonatal Intensive Care"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Created ID. |
{
"id": "cat-02"
}
📍 Website Flow Placement
Edit category modal.
🔗 Dependencies & Prerequisites
Category ID.
⚖️ Validation & Business Rules
Admin check.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Category ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | YES | Name. |
{
"name": "NICU & Special Care Nursery"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Delete category.
🔗 Dependencies & Prerequisites
Category ID.
⚖️ Validation & Business Rules
Cannot delete if activities link to it.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Category ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Logbook Entry Competency dropdown.
🔗 Dependencies & Prerequisites
Subject link.
⚖️ Validation & Business Rules
Active competencies only.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| subject_id | query | string | OPT | Filter by subject. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Competency ID. |
| [].code | string | Code. |
| [].title | string | Title. |
[
{
"id": "comp-01",
"code": "N-101",
"title": "Vital Signs Assessment"
}
]
📍 Website Flow Placement
Activity classification.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Read-only.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Type ID. |
| [].name | string | Title. |
[
{
"id": "at-01",
"name": "Inpatient Ward Practice"
}
]
📍 Website Flow Placement
Admin Activity Types panel.
🔗 Dependencies & Prerequisites
Admin role.
⚖️ Validation & Business Rules
Unique title.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | YES | Title. |
{
"name": "Community Outreach Health Camp"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Created ID. |
{
"id": "at-02"
}
📍 Website Flow Placement
Admin Edit Type.
🔗 Dependencies & Prerequisites
Type ID.
⚖️ Validation & Business Rules
Admin check.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Type ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | YES | Title. |
{
"name": "Community Health Nursing Fieldwork"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Admin Delete Type.
🔗 Dependencies & Prerequisites
Type ID.
⚖️ Validation & Business Rules
Blocked if referenced.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Type ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Admin Clone Type.
🔗 Dependencies & Prerequisites
Type ID.
⚖️ Validation & Business Rules
Deep copies child categories.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Type ID. |
{}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | New ID. |
{
"id": "at-02-copy"
}
📍 Website Flow Placement
Legacy Logbook view.
🔗 Dependencies & Prerequisites
Student profile.
⚖️ Validation & Business Rules
Maps to activities table.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Legacy submission.
🔗 Dependencies & Prerequisites
Active enrollment.
⚖️ Validation & Business Rules
Routes to activity insertion.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| notes | string | YES | Notes. |
{
"notes": "Wound dressing performed."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | ID. |
{
"id": "lb-01"
}
📍 Website Flow Placement
Legacy edit.
🔗 Dependencies & Prerequisites
Entry ID.
⚖️ Validation & Business Rules
Unapproved only.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Entry ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| notes | string | OPT | Notes. |
{
"notes": "Updated wound notes."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Status. |
{
"success": true
}
📍 Website Flow Placement
Legacy delete.
🔗 Dependencies & Prerequisites
Entry ID.
⚖️ Validation & Business Rules
Ownership check.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Entry ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Status. |
{
"success": true
}
11. Clinical Cohort Assignments, Geofencing & Reviews
Scheduled cohort task assignments, GPS location geofence enforcement, multi-step drafts and multi-tier evaluation queues.
📍 Website Flow Placement
Supervisor -> 'Assign Task to Cohort' modal.
🔗 Dependencies & Prerequisites
Teacher subject assignment.
⚖️ Validation & Business Rules
Students must belong to teacher's academic cohort.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| title | string | YES | Duty / procedure assignment title. |
| subject_id | string | YES | Subject ID. |
| due_date | string | YES | Due date (YYYY-MM-DD). |
| student_ids | string[] | YES | List of student IDs to assign. |
{
"title": "Night Duty Ward Vitals & Intake/Output Charting",
"subject_id": "sub-gnm1-found",
"due_date": "2026-10-05",
"student_ids": [
"u-94820f12-88aa-4e12-b231-104928adbeef"
]
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Assignment ID. |
{
"id": "asgn-01"
}
📍 Website Flow Placement
Clinical Tasks list view.
🔗 Dependencies & Prerequisites
Enrollment.
⚖️ Validation & Business Rules
Scoped to user's college.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | ID. |
| [].title | string | Title. |
[
{
"id": "asgn-01",
"title": "Ward Duty Vitals"
}
]
📍 Website Flow Placement
Assignment monitor drawer.
🔗 Dependencies & Prerequisites
Assignment ID.
⚖️ Validation & Business Rules
Supervisor check.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Assignment ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].student_name | string | Name. |
| [].has_submitted | boolean | Submitted status. |
[
{
"student_name": "Simran Kaur",
"has_submitted": true
}
]
📍 Website Flow Placement
Assign Task student picker.
🔗 Dependencies & Prerequisites
Cohort linkage.
⚖️ Validation & Business Rules
Filters active students.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| department_id | query | string | YES | Department ID. |
| year | query | number | YES | Academic year. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Student ID. |
| [].full_name | string | Name. |
[
{
"id": "u-94820f12",
"full_name": "Simran Kaur"
}
]
📍 Website Flow Placement
Assignment delete action.
🔗 Dependencies & Prerequisites
Assignment ID.
⚖️ Validation & Business Rules
Only creator or admin.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Assignment ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Student submission GPS check.
🔗 Dependencies & Prerequisites
College / hospital location.
⚖️ Validation & Business Rules
Haversine formula validation.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| latitude | number | Center latitude. |
| longitude | number | Center longitude. |
| radius | number | Radius in meters (e.g. 500m). |
{
"latitude": 30.3398,
"longitude": 76.3869,
"radius": 500
}
📍 Website Flow Placement
Task preparation modal.
🔗 Dependencies & Prerequisites
Assignment ID.
⚖️ Validation & Business Rules
Checks assignment configuration.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| assignmentId | path | string | YES | Assignment ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| has_location_restriction | boolean | Whether GPS required. |
{
"has_location_restriction": true,
"latitude": 30.3398,
"longitude": 76.3869,
"radius": 500
}
📍 Website Flow Placement
Student submission geocheck.
🔗 Dependencies & Prerequisites
Assignment location.
⚖️ Validation & Business Rules
Must be within radius tolerance.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| assignmentId | string | YES | Task ID. |
| latitude | number | YES | Device GPS latitude. |
| longitude | number | YES | Device GPS longitude. |
| accuracy | number | YES | Device accuracy in meters. |
{
"assignmentId": "asgn-01",
"latitude": 30.3399,
"longitude": 76.3868,
"accuracy": 12
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| verified | boolean | Whether within boundary. |
| distance_meters | number | Distance to center. |
{
"verified": true,
"distance_meters": 24.5
}
📍 Website Flow Placement
Supervisor Geofence Exemption dialog.
🔗 Dependencies & Prerequisites
Assignment ID.
⚖️ Validation & Business Rules
Audit trail recorded.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| assignmentId | string | YES | Assignment ID. |
| studentId | string | YES | Student ID. |
| reason | string | YES | Exemption rationale. |
{
"assignmentId": "asgn-01",
"studentId": "u-94820f12",
"reason": "Authorized rural health outreach."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Task Form -> 'Save Draft'.
🔗 Dependencies & Prerequisites
Assignment ID.
⚖️ Validation & Business Rules
Status set to 'draft'.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| assignmentId | path | string | YES | Task ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| form_data | object | YES | Form fields. |
{
"form_data": {
"bp_reading": "120/80"
}
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Draft submission ID. |
{
"id": "subm-01"
}
📍 Website Flow Placement
Task Form -> 'Submit Task'.
🔗 Dependencies & Prerequisites
Assignment ID.
⚖️ Validation & Business Rules
Status set to 'submitted'.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| assignmentId | path | string | YES | Task ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| form_data | object | YES | Final responses. |
{
"form_data": {
"bp_reading": "120/80",
"pulse": 74,
"clinical_notes": "Routine check"
}
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Resubmission modal.
🔗 Dependencies & Prerequisites
Submission in revision requested state.
⚖️ Validation & Business Rules
Resets review status.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| submissionId | path | string | YES | Previous submission ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| form_data | object | YES | Revised fields. |
{
"form_data": {
"clinical_notes": "Added medication charting."
}
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Submission Audit trail.
🔗 Dependencies & Prerequisites
Assignment ID.
⚖️ Validation & Business Rules
Read-only.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| assignmentId | path | string | YES | Assignment ID. |
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Submission viewer.
🔗 Dependencies & Prerequisites
Submission ID.
⚖️ Validation & Business Rules
Access check.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| submissionId | path | string | YES | Submission ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | ID. |
| form_data | object | Data. |
{
"id": "subm-01",
"form_data": {
"bp_reading": "120/80"
}
}
📍 Website Flow Placement
Teacher Review Dashboard.
🔗 Dependencies & Prerequisites
Teacher assignment.
⚖️ Validation & Business Rules
Restricted to authorized cohorts.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].submission_id | string | Submission ID. |
| [].student_name | string | Student name. |
[
{
"submission_id": "subm-01",
"student_name": "Simran Kaur"
}
]
📍 Website Flow Placement
Teacher Review Queue -> Action buttons.
🔗 Dependencies & Prerequisites
Submission ID.
⚖️ Validation & Business Rules
Notifies student.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| submissionId | path | string | YES | Submission ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| action | string | YES | 'approve' | 'reject' | 'revise'. |
| remarks | string | OPT | Feedback notes. |
{
"action": "approve",
"remarks": "Vital charting correctly completed."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Clinical Authority Setup.
🔗 Dependencies & Prerequisites
Hospital link.
⚖️ Validation & Business Rules
Hospital Admin check.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| authority_id | string | YES | Preceptor user ID. |
| hospital_id | string | YES | Hospital ID. |
{
"authority_id": "u-prec-01",
"hospital_id": "hosp-01"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Status. |
{
"success": true
}
📍 Website Flow Placement
Preceptor directory.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Institutional scope.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Routing check during submission.
🔗 Dependencies & Prerequisites
Student ID.
⚖️ Validation & Business Rules
Resolves via subject assignments.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| studentId | path | string | YES | Student ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| evaluating_authority | string | Resolved preceptor or teacher. |
{
"evaluating_authority": "Subject Dedicated Teachers"
}
📍 Website Flow Placement
Authority audit screen.
🔗 Dependencies & Prerequisites
Student ID.
⚖️ Validation & Business Rules
Read-only.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| studentId | path | string | YES | Student ID. |
📤 Expected Response
Status Codes & Schema[]
12. Leaves & Absences
Student and staff leave application, supervisor/coordinator recommendations, and executive institutional approvals.
📍 Website Flow Placement
Student Portal -> Leaves tab; Coordinator / Principal -> Leave Approvals view.
🔗 Dependencies & Prerequisites
Requires active user profile.
⚖️ Validation & Business Rules
Students view own leave applications; staff view leaves within their college/department.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| status | query | string | OPT | Filter: 'pending', 'approved', 'rejected'. |
| student_id | query | string | OPT | Filter by student (for staff). |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Leave request UUID. |
| [].student_name | string | Applicant full name. |
| [].start_date | string (Date) | First day of leave. |
| [].end_date | string (Date) | Last day of leave. |
| [].reason | string | Reason for absence. |
| [].status | string | Current status: 'pending', 'approved', 'rejected'. |
[
{
"id": "lv-1029-4411",
"student_name": "Simran Kaur",
"start_date": "2026-10-01",
"end_date": "2026-10-03",
"reason": "Attending sister39;s wedding in home town.",
"status": "pending"
}
]
📍 Website Flow Placement
Student Portal -> 'Apply Leave' modal.
🔗 Dependencies & Prerequisites
Student active enrollment.
⚖️ Validation & Business Rules
Sets initial status to 'pending'. Dates must be valid and chronologically correct.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| start_date | string (YYYY-MM-DD) | YES | Start date. |
| end_date | string (YYYY-MM-DD) | YES | End date. |
| reason | string | YES | Detailed justification. |
| leave_type | string | OPT | Type: 'medical', 'casual', 'duty'. |
| document_url | string | OPT | Uploaded certificate file path. |
{
"start_date": "2026-10-01",
"end_date": "2026-10-03",
"reason": "Attending sister39;s wedding in home town.",
"leave_type": "casual"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
| id | string | Created leave record ID. |
{
"success": true,
"id": "lv-1029-4411"
}
📍 Website Flow Placement
Leave Approvals table -> 'Approve' / 'Reject' button.
🔗 Dependencies & Prerequisites
Leave application ID.
⚖️ Validation & Business Rules
Notifies student via internal notifications.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string (UUID) | YES | Leave request ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| status | string | YES | 'approved' | 'rejected'. |
| remarks | string | OPT | Reviewer comments. |
{
"status": "approved",
"remarks": "Leave sanctioned. Student must make up clinical hours upon return."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
My Leaves list -> 'Cancel Request' button.
🔗 Dependencies & Prerequisites
Pending leave request owned by user.
⚖️ Validation & Business Rules
Only pending leaves can be deleted by student.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string (UUID) | YES | Leave request ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
13. Payments & Fee Processing
Razorpay payment gateway integration, order generation, cryptographic signature validation, and institutional financial audit trails.
📍 Website Flow Placement
Student Portal initialization; Payment banner / barrier modal.
🔗 Dependencies & Prerequisites
Requires active student academic enrollment.
⚖️ Validation & Business Rules
Evaluates fee settlement in `payment_orders` or `payment_bypass` flag in `users`.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| paid | boolean | True if annual fee is settled. |
| orderId | string | null | Razorpay order ID if pending. |
| amount | number | Fee amount in paise (e.g. 50000 = ₹500). |
| currency | string | Currency code (INR). |
| bypass | boolean | True if student has institutional fee waiver. |
{
"paid": true,
"orderId": "order_Pnrc2026_9901",
"amount": 50000,
"currency": "INR",
"bypass": false
}
📍 Website Flow Placement
Student Portal -> 'Pay Annual Fee' button -> Razorpay modal initialization.
🔗 Dependencies & Prerequisites
Requires active enrollment and Razorpay credentials configured in environment.
⚖️ Validation & Business Rules
Amount locked to official PNRC fee schedule.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| academicYear | number | OPT | Academic year (default active year). |
{
"academicYear": 1
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| orderId | string | Razorpay order ID (e.g. order_xxx). |
| amount | number | Amount in INR paise. |
| currency | string | 'INR'. |
| keyId | string | Public Razorpay API key for frontend checkout. |
{
"orderId": "order_Nsq1829dks91",
"amount": 50000,
"currency": "INR",
"keyId": "rzp_live_example123"
}
📍 Website Flow Placement
Razorpay Checkout callback (`onSuccess`).
🔗 Dependencies & Prerequisites
Valid order created via `/api/payments/create-order`.
⚖️ Validation & Business Rules
Cryptographically verifies signature using `RAZORPAY_KEY_SECRET`. Sets order status to 'paid'.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| razorpay_order_id | string | YES | Order ID from gateway. |
| razorpay_payment_id | string | YES | Transaction ID from gateway. |
| razorpay_signature | string | YES | HMAC signature string. |
{
"razorpay_order_id": "order_Nsq1829dks91",
"razorpay_payment_id": "pay_Nsq2981ka99",
"razorpay_signature": "9283749823749823749823749823749823749823749823749823749823749823"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Verification outcome. |
| message | string | Confirmation notification. |
{
"success": true,
"message": "Payment verified successfully. Account fully unlocked."
}
📍 Website Flow Placement
Superadmin / College Admin Financial Reports panel.
🔗 Dependencies & Prerequisites
Admin credentials.
⚖️ Validation & Business Rules
College Admin restricted to own college transactions.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| college_id | query | string | OPT | College filter. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| payments[].id | string | Payment ID. |
| payments[].student_name | string | Student name. |
| payments[].amount | number | Amount. |
| payments[].status | string | Status. |
{
"payments": [
{
"id": "pay-01",
"student_name": "Simran Kaur",
"amount": 500,
"status": "captured"
}
]
}
14. File Storage & Document Delivery
Multi-part document uploads (Aadhaar, PAN, PMC certificates, clinical images), file validation, secure multi-tenant access control, and authenticated streaming.
📍 Website Flow Placement
Triggered whenever documents (Aadhaar, PAN, PMC certificate, activity evidence) are uploaded across the application.
🔗 Dependencies & Prerequisites
Requires active session.
⚖️ Validation & Business Rules
Magic-byte header inspection; strictly disallows executable scripts or SVG files. Saves record in `file_uploads`.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| file | file (binary) | YES | File attachment (JPEG, PNG, or PDF up to 10MB). |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string (UUID) | Unique file identifier. |
| url | string | Relative proxy URL to retrieve the document (e.g. /uploads/userId/fileId.pdf). |
| mime_type | string | Verified MIME type. |
| size | number | Size in bytes. |
{
"id": "f-9988-1122-3344",
"url": "/uploads/u-94820f12/f-9988-1122-3344.pdf",
"mime_type": "application/pdf",
"size": 412984
}
📍 Website Flow Placement
Document removal / re-upload button.
🔗 Dependencies & Prerequisites
File ID.
⚖️ Validation & Business Rules
Soft-deletes metadata in DB and purges storage object.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string (UUID) | YES | File upload ID to delete. |
📤 Expected Response
Status Codes & Schema📍 Website Flow Placement
Document replacement.
🔗 Dependencies & Prerequisites
File URL.
⚖️ Validation & Business Rules
Ownership verification.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| url | string | YES | Relative file path URL to delete. |
{
"url": "/uploads/u-94820f12/f-9988-1122-3344.pdf"
}
📤 Expected Response
Status Codes & Schema📍 Website Flow Placement
Document preview modal, PDF viewer, or image avatar display.
🔗 Dependencies & Prerequisites
Active authenticated session.
⚖️ Validation & Business Rules
Tenancy authorization: user must either own the file, supervise the student (via active enrollment or subject assignment), be college principal, or superadmin. Serves locally or proxies via S3 GetObjectCommand.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| filename | path | string | YES | File path reference. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| binary stream | image/png, image/jpeg, application/pdf | Direct file stream with security headers. |
15. Dashboards & Real-time Metrics
Role-specific statistical rollups, activity velocity counters, competency completion progress, and operational indicators.
📍 Website Flow Placement
Student Dashboard top summary stat cards.
🔗 Dependencies & Prerequisites
Student profile.
⚖️ Validation & Business Rules
Scoped to `student_id = req.user.id`.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| total_activities | number | Total logs created. |
| approved | number | Approved procedures. |
| pending | number | Pending review. |
| revision_requested | number | Revisions needed. |
| competencies_achieved | number | Accredited competencies completed. |
{
"total_activities": 38,
"approved": 34,
"pending": 3,
"revision_requested": 1,
"competencies_achieved": 22
}
📍 Website Flow Placement
Supervisor Dashboard top summary cards.
🔗 Dependencies & Prerequisites
Assigned subjects.
⚖️ Validation & Business Rules
Restricted to teacher's subjects.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| total_students | number | Students in cohort. |
| pending_reviews | number | Logs waiting for teacher review. |
| reviewed_today | number | Procedures evaluated today. |
{
"total_students": 45,
"pending_reviews": 7,
"reviewed_today": 12
}
📍 Website Flow Placement
Year Coordinator Dashboard header.
🔗 Dependencies & Prerequisites
Coordinator assignment.
⚖️ Validation & Business Rules
Scoped to year cohort.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| cohort_students | number | Students in coordinator's year. |
| pending_registrations | number | Unverified staff/students. |
| pending_appraisals | number | Appraisals awaiting endorsement. |
{
"cohort_students": 45,
"pending_registrations": 2,
"pending_appraisals": 5
}
📍 Website Flow Placement
Faculty Portal overview.
🔗 Dependencies & Prerequisites
Department link.
⚖️ Validation & Business Rules
Department scope.
📥 Request Specification
📤 Expected Response
Status Codes & Schema{
"active_classes": 4,
"evaluated_students": 38
}
📍 Website Flow Placement
Hospital Admin Portal overview.
🔗 Dependencies & Prerequisites
Hospital link.
⚖️ Validation & Business Rules
Hospital scope.
📥 Request Specification
📤 Expected Response
Status Codes & Schema{
"active_interns": 28,
"affiliated_colleges": 2
}
16. Notifications & Institutional Notices
In-app notifications, badge unread counters, institutional council bulletins, and college notices.
📍 Website Flow Placement
Header Bell Icon dropdown.
🔗 Dependencies & Prerequisites
User profile.
⚖️ Validation & Business Rules
Ordered by `created_at` DESC.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| limit | query | number | OPT | Max count (default 20). |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Notification UUID. |
| [].title | string | Title. |
| [].message | string | Body text. |
| [].is_read | boolean | Read status. |
| [].created_at | string | Timestamp. |
[
{
"id": "notif-01",
"title": "Activity Approved",
"message": "Dr. Harpreet Kaur approved your 39;Fundamentals of Nursing39; logbook entry.",
"is_read": false,
"created_at": "2026-09-29T11:00:00Z"
}
]
📍 Website Flow Placement
System events and staff announcements.
🔗 Dependencies & Prerequisites
Recipient user ID.
⚖️ Validation & Business Rules
Inserts into notifications table.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| userId | string | YES | Target recipient user ID. |
| title | string | YES | Notification title. |
| message | string | YES | Message body. |
{
"userId": "u-94820f12-88aa-4e12-b231-104928adbeef",
"title": "Appraisal Signed",
"message": "Your Year 1 Annual Appraisal has been approved by the Principal."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Notification item click.
🔗 Dependencies & Prerequisites
Notification ID.
⚖️ Validation & Business Rules
Must belong to authenticated user.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Notification ID. |
{}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Sidebar Navigation badges.
🔗 Dependencies & Prerequisites
Active user.
⚖️ Validation & Business Rules
Dynamic aggregation.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| unread_notifications | number | Unread notifications. |
| pending_reviews | number | Items needing review. |
{
"unread_notifications": 3,
"pending_reviews": 5
}
📍 Website Flow Placement
Dashboard Noticeboard widget.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Active notices only (`is_active = 1`).
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Notice ID. |
| [].title | string | Notice title. |
| [].content | string | Notice text. |
| [].created_at | string | Date published. |
[
{
"id": "ntc-01",
"title": "PNRC Annual Clinical Examination Schedule 2026",
"content": "Examinations for GNM and ANM will commence from 15th October 2026.",
"created_at": "2026-09-25T10:00:00Z"
}
]
📍 Website Flow Placement
Noticeboard Manager.
🔗 Dependencies & Prerequisites
Admin rights.
⚖️ Validation & Business Rules
College scope.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Create Notice modal.
🔗 Dependencies & Prerequisites
Admin role.
⚖️ Validation & Business Rules
Records publisher ID.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| title | string | YES | Notice headline. |
| content | string | YES | Detailed bulletin text. |
{
"title": "Holiday Announcement - Gandhi Jayanti",
"content": "The college and clinical wards will observe holiday on 2nd October."
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Created ID. |
{
"id": "ntc-02"
}
📍 Website Flow Placement
Notice manager toggle switch.
🔗 Dependencies & Prerequisites
Notice ID.
⚖️ Validation & Business Rules
Flips `is_active`.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Notice ID. |
{}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Delete notice action.
🔗 Dependencies & Prerequisites
Notice ID.
⚖️ Validation & Business Rules
Admin check.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Notice ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
17. Master Data & Academic Hierarchy
Curricular lookup entities (hospitals, colleges, courses, academic years, terms, subjects, competencies, dynamic tables) and academic structure trees.
📍 Website Flow Placement
Hospital dropdowns across student posting and supervisor setups.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Active facilities only.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Hospital ID. |
| [].name | string | Hospital name. |
[
{
"id": "hosp-01",
"name": "Rajindra Hospital, Patiala"
}
]
📍 Website Flow Placement
Registration, onboarding, and superadmin filters.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Alphabetical order.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | College ID. |
| [].name | string | College name. |
[
{
"id": "col-1029-4411",
"name": "Government College of Nursing, Patiala"
}
]
📍 Website Flow Placement
Course selectors.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Returns active courses.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Course ID. |
| [].name | string | Course title. |
[
{
"id": "c-gnm-4411-8899-0011",
"name": "General Nursing and Midwifery (GNM)"
}
]
📍 Website Flow Placement
Staff registration and assignments.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Active records.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Year selectors.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Standardized.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Term filters.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Active terms.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Curriculum mapping.
🔗 Dependencies & Prerequisites
Course / year.
⚖️ Validation & Business Rules
Enforces year linkage.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| year_id | query | string | OPT | Year filter. |
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Competency library.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Official syllabus.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Master data view.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Active.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Faculty selectors.
🔗 Dependencies & Prerequisites
College link.
⚖️ Validation & Business Rules
College scope.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Geofencing.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Validated coordinates.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Superadmin Master Table Manager.
🔗 Dependencies & Prerequisites
Superadmin role.
⚖️ Validation & Business Rules
Whitelisted tables only.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| table | path | string | YES | Allowed master table. |
| Field | Type | Required | Description |
|---|---|---|---|
| payload | object | YES | Record attributes. |
{
"name": "Community Health Nursing - II",
"code": "GNM201"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Created ID. |
{
"id": "sub-102"
}
📍 Website Flow Placement
Master Table Editor.
🔗 Dependencies & Prerequisites
Superadmin role.
⚖️ Validation & Business Rules
Whitelisted tables.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| table | path | string | YES | Table name. |
| id | path | string | YES | Record ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| payload | object | YES | Updated fields. |
{
"name": "Updated Title"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Master Table Delete.
🔗 Dependencies & Prerequisites
Superadmin role.
⚖️ Validation & Business Rules
Foreign key checks.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| table | path | string | YES | Table name. |
| id | path | string | YES | Record ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Admin user picker.
🔗 Dependencies & Prerequisites
Admin role.
⚖️ Validation & Business Rules
College scope.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Academic tree navigation.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Hierarchical.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Department tree.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Active.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Course year picker.
🔗 Dependencies & Prerequisites
Course ID.
⚖️ Validation & Business Rules
Filters by course.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| courseId | path | string | YES | Course ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].year_number | number | Year (1, 2, 3). |
[
{
"year_number": 1
},
{
"year_number": 2
},
{
"year_number": 3
}
]
📍 Website Flow Placement
Curriculum viewer.
🔗 Dependencies & Prerequisites
Year ID.
⚖️ Validation & Business Rules
Year linkage.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| yearId | path | string | YES | Year ID. |
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Term viewer.
🔗 Dependencies & Prerequisites
Year ID.
⚖️ Validation & Business Rules
Term linkage.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| yearId | path | string | YES | Year ID. |
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Batch picker.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Chronological.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Session picker.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Active sessions.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Student Academic Progression sheet.
🔗 Dependencies & Prerequisites
Student ID.
⚖️ Validation & Business Rules
Access check.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| studentId | path | string | YES | Student ID. |
📤 Expected Response
Status Codes & Schema[]
18. Superadmin & System Administration
System-wide user administration, bulk provisioning, appraisal template configuration builder, fee bypass overrides, and enrollment repair utilities.
📍 Website Flow Placement
User Management table (`/admin/users`).
🔗 Dependencies & Prerequisites
Admin role.
⚖️ Validation & Business Rules
College admin restricted to own college.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| role | query | string | OPT | Filter by role. |
| search | query | string | OPT | Search by email or name. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| users[].id | string | User ID. |
| users[].email | string | Email. |
| users[].full_name | string | Name. |
| users[].role | string | Role. |
| users[].is_active | boolean | Active state. |
{
"users": [
{
"id": "u-94820f12",
"email": "student@example.com",
"full_name": "Simran Kaur",
"role": "student",
"is_active": true
}
]
}
📍 Website Flow Placement
Create User modal.
🔗 Dependencies & Prerequisites
Admin permissions.
⚖️ Validation & Business Rules
Hashes password with bcrypt 12.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| string | YES | Email. | |
| full_name | string | YES | Name. |
| role | string | YES | Role. |
| password | string | YES | Initial password. |
{
"email": "prof.gurpreet@college.edu",
"full_name": "Prof. Gurpreet Singh",
"role": "supervisor",
"password": "InitialPassword123!"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Created user ID. |
{
"id": "u-prof-01"
}
📍 Website Flow Placement
User status toggle switch.
🔗 Dependencies & Prerequisites
User ID.
⚖️ Validation & Business Rules
Cannot deactivate own account.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | User ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| is_active | boolean | YES | Active state. |
{
"is_active": false
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Student Troubleshooting drawer.
🔗 Dependencies & Prerequisites
Student ID.
⚖️ Validation & Business Rules
Admin audit logged.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Student user ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| academic_year_number | number | YES | Target year (1, 2, 3). |
{
"academic_year_number": 1
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Edit User modal.
🔗 Dependencies & Prerequisites
User ID.
⚖️ Validation & Business Rules
Admin check.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | User ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| full_name | string | OPT | New name. |
{
"full_name": "Simran Kaur Sandhu"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Delete user action.
🔗 Dependencies & Prerequisites
User ID.
⚖️ Validation & Business Rules
Soft-delete.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | User ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Bulk Upload CSV tool.
🔗 Dependencies & Prerequisites
Admin role.
⚖️ Validation & Business Rules
Rate limited.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| users | array | YES | Array of user objects. |
{
"users": [
{
"email": "student1@college.edu",
"full_name": "Student 1",
"role": "student"
}
]
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| created_count | number | Created count. |
{
"created_count": 1
}
📍 Website Flow Placement
Bulk Edit tool.
🔗 Dependencies & Prerequisites
Admin role.
⚖️ Validation & Business Rules
Batch processed.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| updates | array | YES | Updates array. |
{
"updates": []
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| updated_count | number | Updated count. |
{
"updated_count": 0
}
📍 Website Flow Placement
Global Registrations queue.
🔗 Dependencies & Prerequisites
Admin credentials.
⚖️ Validation & Business Rules
Superadmin sees all.
📥 Request Specification
📤 Expected Response
Status Codes & Schema[]
📍 Website Flow Placement
Admin Appraisal Config Manager.
🔗 Dependencies & Prerequisites
None.
⚖️ Validation & Business Rules
Active templates.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| [].id | string | Config ID. |
| [].form_name | string | Template title. |
| [].year_number | number | Year. |
[
{
"id": "cfg-01",
"form_name": "GNM 1st Year Annual Appraisal",
"year_number": 1
}
]
📍 Website Flow Placement
Appraisal Form Builder.
🔗 Dependencies & Prerequisites
Course ID.
⚖️ Validation & Business Rules
Superadmin only.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| form_name | string | YES | Form title. |
| course_id | string | YES | Course ID. |
| year_number | number | YES | Academic year. |
{
"form_name": "GNM 3rd Year Appraisal",
"course_id": "c-gnm-01",
"year_number": 3
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Created ID. |
{
"id": "cfg-03"
}
📍 Website Flow Placement
Appraisal Editor.
🔗 Dependencies & Prerequisites
Config ID.
⚖️ Validation & Business Rules
Superadmin only.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Config ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| form_name | string | OPT | Title. |
{
"form_name": "Updated Form Name"
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Clone Appraisal Template button.
🔗 Dependencies & Prerequisites
Source Config.
⚖️ Validation & Business Rules
Deep copies questions.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Source Config ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| target_year_number | number | YES | Target year number. |
{
"target_year_number": 2
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| id | string | Cloned Config ID. |
{
"id": "cfg-02"
}
📍 Website Flow Placement
Delete appraisal template.
🔗 Dependencies & Prerequisites
Config ID.
⚖️ Validation & Business Rules
Checks for existing submissions.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Config ID. |
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Student Batch Importer.
🔗 Dependencies & Prerequisites
Admin role.
⚖️ Validation & Business Rules
Enforces password hashing.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| users | array | YES | User list. |
{
"users": []
}
📤 Expected Response
Status Codes & Schema{
"created": 0
}
📍 Website Flow Placement
Profile batch updater.
🔗 Dependencies & Prerequisites
Admin role.
⚖️ Validation & Business Rules
Batch audit.
📥 Request Specification
| Field | Type | Required | Description |
|---|---|---|---|
| profiles | array | YES | Profile data. |
{
"profiles": []
}
📤 Expected Response
Status Codes & Schema{
"updated": 0
}
📍 Website Flow Placement
Student Record -> 'Waive Subscription Fee' toggle.
🔗 Dependencies & Prerequisites
Student ID.
⚖️ Validation & Business Rules
Sets `payment_bypass` in `users`.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Student user ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| bypass | boolean | YES | True to waive fee, false to require payment. |
{
"bypass": true
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
📍 Website Flow Placement
Troubleshooting panel.
🔗 Dependencies & Prerequisites
Student ID.
⚖️ Validation & Business Rules
Administrative audit.
📥 Request Specification
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | YES | Student ID. |
| Field | Type | Required | Description |
|---|---|---|---|
| year | number | YES | Year (1, 2, 3). |
{
"year": 1
}
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| success | boolean | Outcome. |
{
"success": true
}
19. System Health & Infrastructure
Database connectivity probes, server uptime heartbeats, and cluster liveness checks.
📍 Website Flow Placement
Load balancer liveness probe, Kubernetes health check, and internal watchdog.
🔗 Dependencies & Prerequisites
MySQL database pool.
⚖️ Validation & Business Rules
Runs fast `SELECT 1` ping.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| status | string | 'ok' or 'error'. |
| database | string | 'connected' or 'unavailable'. |
| timestamp | string (ISO Date) | Server timestamp. |
{
"status": "ok",
"database": "connected",
"timestamp": "2026-09-29T10:15:00.000Z"
}
📍 Website Flow Placement
Monitoring.
🔗 Dependencies & Prerequisites
Database pool.
⚖️ Validation & Business Rules
Same handler as `/health`.
📥 Request Specification
📤 Expected Response
Status Codes & Schema| Field | Type | Description |
|---|---|---|
| status | string | 'ok' or 'error'. |
| database | string | 'connected' or 'unavailable'. |
| timestamp | string | ISO timestamp. |
{
"status": "ok",
"database": "connected",
"timestamp": "2026-09-29T10:15:00.000Z"
}