# School Admin Module

Documentation for the **School Admin** area of the CMM School application: the admin panel used by **Administrators** and **School Owners** after logging in at `admin/home/login`. Business logic and UI are aligned with the legacy CI3 application; the upgrade uses CodeIgniter 4 and PHP 8.x.

---

## 1. Overview

| Aspect | Description |
|--------|-------------|
| **Purpose** | Central back-office for managing schools, users, prospects, enrollments, teachers, classrooms, students, events, portals, and internal messaging. |
| **Users** | **Admin** (role_id = 1): can switch school context and access all schools. **School Owner** (role_id = SCHOOL_OWNER_ROLE_ID): sees only their assigned school. |
| **Base URL** | All routes live under the `admin` group, e.g. `admin/home/dashboard`, `admin/schools/index`. |
| **Namespace** | Controllers: `App\Controllers\Admin`. |

---

## 2. Access & Roles

- **Allowed roles** for the admin panel: `ADMIN_ROLE_ID` (1) and `SCHOOL_OWNER_ROLE_ID` (config in `Config\CmmConstants`).
- Each controller method that serves a page or AJAX typically calls `$this->ensureAllowed()` (from `AdminController`). If the user is not allowed, a redirect to login or a 403-style response is returned.
- **Session keys** (after login):
  - **Admin:** `school_id` = `"admin"` (can change school via dashboard dropdown).
  - **School Owner:** `school_id` = numeric (their school); `school_owner_user_id`, `school_owner_time_zone` may also be set.
- **Data scoping:** Queries filter by `session('school_id')`: admin sees all schools when `school_id === 'admin'`; school owner sees only rows where `school_id` equals their session value.

---

## 3. Entry & Layout

### 3.1 Entry

| URL | Method | Description |
|-----|--------|-------------|
| `admin/home` / `admin/home/index` | GET | Redirect: logged in → dashboard; else → login. |
| `admin/home/login` | GET | Login form. |
| `admin/home/login` | POST | Process login (Home::loginPost). |
| `admin/home/logout` | GET | Logout; redirect to login. |
| `admin/home/dashboard` | GET | Main dashboard (both roles). |
| `admin/home/dashboard_ajax_data` | POST | Dashboard content (school filter, date range, summary). |
| `admin/home/school_change` | POST | Change session `school_id` (admin only). |
| `admin/home/changePassword` | GET/POST | Change passcode (logged in). |

### 3.2 Layout Components

- **Includes:** `admin/include/headScripts`, `admin/include/navbar`, `admin/include/sidebar`, `admin/include/breadcrumbs`, `admin/include/footerScripts`.
- **Layout helper:** Controllers use `$this->layoutView('admin/viewName')` to merge `tourInfo`, `loginUser`, and pass data to the view.
- **Sidebar:** Rendered from `app/Views/admin/include/sidebar.php`. Menu items are shown/hidden by `$isAdmin`, `$schoolId === 'admin'`, and `$isSchoolOwnerView` (school owner context).

---

## 4. Sidebar Menu & Modules

| Menu | Sub-items | Main URLs | Access |
|------|-----------|-----------|--------|
| **Dashboard** | — | `admin/home/dashboard` | Both |
| **Prospects** | Calendar, All Prospects, Add a Prospect, Prospects Report, Summary Report | `admin/prospects/calendar`, `index`, `addEdit`, `report`, `prospectEnrolledReport` | Both |
| **Email Templates** | All, Add | `admin/emailTemplate/index`, `addEdit` | Admin only |
| **Registrations** | All Registrations, Register a Prospect | `admin/enrollment/index`, `addEdit` | Both |
| **Schools** | All Schools, Add a School, Summary Report | `admin/schools/index`, `addEdit`, `schoolSummaryReport` | All Schools / Add: Admin only; Summary Report: Both |
| **Users** | All Users, Add a User | `admin/users/index`, `addEdit` | Both |
| **Teachers** | All Teachers, Add a Teacher, Class Assignments | `admin/teachers/index`, `addEdit`, `teacherClassRoom` | Add + Class Assignments: School owner only |
| **Classrooms** | All Classroom, Add a Classroom | `admin/classRooms/index`, `addEdit` | Add: School owner only |
| **Students** | All Students, Student & Parent, Add a Student, Withdraws, Concerns, Export, Attendance Summary | `admin/students/index`, `admin/studentParent/index`, `addEdit`, `admin/withdraws/*`, `admin/parentConcerns/*`, `exportStudentdata`, `admin/prospects/studentreport` | Add/Withdraws: School owner; Export/Attendance: Admin |
| **Class Roster** | Class List | `admin/classroster/class_list` | Both |
| **School Maint** | All Activities, Add Activity, All Requests, Add Request | `admin/activities/index`, `addEdit`, `admin/requests/index`, `addEdit` | Add: School owner only |
| **Internal Messaging** | — | `admin/internalMessage/index` | Both |
| **Portal** | Admin Announcement, Program Announcement, Newsletter, Documents, Notifications | `admin/portals/adminAnnouncement`, `programAnnouncement`, `newsletter`, `documents`, `sendNotification` | Both |
| **Events** | Event Calendar | `admin/events/eventsData` | Both |
| **Teacher Messages** | Teacher Messages List, Teacher Admin Report | `admin/teacherMessage/index`, `teacherAdminReport` | Both |

---

## 5. Controllers & Key Methods

| Controller | Key methods | Notes |
|------------|-------------|--------|
| **Home** | index, login, loginPost, logout, dashboard, dashboardAjaxData, schoolChange, changePassword | Entry, dashboard, school switcher. |
| **Prospects** | index, calendar, addEdit, viewProspects, report, prospectEnrolledReport, studentreport, ajaxDatatables, ajaxDataProspects, ajaxReport, deleteProspect, hotProspect, sendBulkEmail, exportCSV | Server-side DataTables, calendar date-range feed. |
| **EmailTemplate** | index, addEdit, viewTemplate, ajaxDatatables, ajaxTemplateDelete, checkTemplateName, emailTemplatePreview | Admin only. |
| **Enrollment** | index, addEdit, viewEnrollment, enrollmentAdminListing, subscriptionDetailsLocationWise, sendBulkEmail | Registrations. |
| **Schools** | index, addEdit, schoolSummaryReport, ajaxDatatables, ajaxSchoolDelete, ajaxSchoolSummaryReport, exportSchoolSummaryReport, getClassAccordingToProgram, checkEmail | Summary report: filter + AJAX HTML + CSV export. |
| **Users** | index, addEdit, viewUserDetails, ajaxDatatables, ajaxUserFranchiseDatatables, deleteUser, resetPassword, userName, checkEmail, getGeneratedUserName | School-scoped for school owner. |
| **Teachers** | index, addEdit, teacherClassRoom, ajaxGetTeacherClass, ajaxTeachersSuperAdminListing, ajaxTeachersFranchiseeListing, deleteTeacher, views | Class assignments for school owner. |
| **ClassRooms** | index, addEdit, ajaxDatatables, delete | School-scoped. |
| **Students** | index, addEdit, views, studentSuperAdminListing, studentFranchiseeListing, exportStudentdata, exportStudentCSVData, ajaxActivityInfo, ajaxMedicationInfo, ajaxBehaviorInfo, ajaxMessageInfo, ajaxQuestInfo, loadAttendanceView, attend, loadFormView | Listing and export. |
| **StudentParent** | index, studentParentListing | Student & Parent list. |
| **Withdraws** | index, addEdit, ajaxStudentParentInfo, deleteWithdraw | School owner add. |
| **ParentConcerns** | index, addEdit, concernListing, ajaxStudentParentInfo, deleteConcern | Concerns. |
| **Classroster** | class_list, rosterSuperAdminListingCurrent, month_year, class_student, location_student, select_student, clear_filters | Class roster. |
| **Activities** | index, addEdit, delete, ajaxGetStudentsClass | School Maint. |
| **Requests** | index, addEdit, deleteRequest | School Maint. |
| **InternalMessage** | index, compose, sentItems, getRecieverData | Inbox, compose, sent. |
| **Portals** | adminAnnouncement, addEditAnnouncement, programAnnouncement, newsLetter, documents, sendNotification, ajaxNotificationDatatables, notificationAddEdit, delete* | Announcements, newsletter, documents, notifications (server-side DataTables where applicable). |
| **Events** | eventsData, getdata, getFilterData, addEvent, getEventData, viewEvents, updateEvent, deleteEvent, deleteEventredirection, setTimeZone | Event calendar (FullCalendar), add/edit/view/delete. |
| **TeacherMessage** | index, viewData, deleteTeacherMessage, teacherAdminReport, ajaxTeacheradminReport, ajaxDatatables | Teacher messages list (server-side DataTables), report. |

---

## 6. Models (admin-related)

| Model | Use |
|-------|-----|
| **SecuritiesModel** | authenticateLogin, sessionExistRedirect, getLoginUserDetail, allowedRoles, adminLogout, schoolOwnerLogout. |
| **AdminModel** | Login/forgot/new password rules and auth. |
| **UtilityModel** | getRowByField, getRowsByField, setUserTimeZone, GmDateTime, insert_user_login_detail, update_user_login_detail, pluck, limit, order, filter (DataTables). |
| **ProspectModel** | Prospects CRUD, getRecordsDatatable, getReportTourInfoPaginated, etc. |
| **SchoolModel** | Schools CRUD (used by Schools controller). |
| **EventModel** | getEvents, getEventData, getFilterEvents, storeEventData, updateEventData, getProgramData, updateSyncStatus. |
| **EventSyncModel** | event_sync table. |
| **TeacherMessageModel** | showTeacherMessageListing, showTeacherMessageById, getTeacherMessageListingDatatable, getTeachersFranchiseeData, getTeacherClassInfo, getTeacherDailyReport, etc. |
| **PortalModel** | Notifications, announcements, etc. (e.g. getNotificationListingDatatable). |
| **InternalMessageModel** | Internal messaging. |
| Others | Enrollment, Users, Teachers, ClassRooms, Students, Withdraws, ParentConcerns, Activities, Requests, Classroster as per each controller. |

---

## 7. Data Scoping (school_id)

- **Admin:** `session('school_id') === 'admin'` → no school filter (or optional school filter from dashboard).
- **School owner:** `session('school_id')` = numeric → all listings and forms restrict to `WHERE school_id = ?` (or equivalent).
- Controllers typically read `session()->get('school_id')` and pass it to models or build queries accordingly.

---

## 8. Routes (admin group)

All routes below are inside `$routes->group('admin', ['namespace' => 'App\Controllers\Admin'], ...)` in `app/Config/Routes.php`. Only the main path patterns are listed; optional segments like `(:segment)` or `(:num)` are omitted for brevity.

- **Home:** home, home/index, home/login (GET/POST), home/logout, home/dashboard, home/changePassword (GET/POST), home/dashboard_ajax_data (POST), home/school_change (POST).
- **TeacherMessage:** teacherMessage/index, teacherMessage, teacherMessage/ajaxDatatables (POST), teacherMessage/getStudentlist, teacherMessage/viewData, teacherMessage/deleteTeacherMessage, teacherMessage/teacherAdminReport, teacherMessage/ajaxTeacheradminReport (POST).
- **Prospects:** prospects/index, prospects, prospects/calendar, prospects/addEdit, prospects/viewProspects/(:segment), prospects/report, prospects/prospectEnrolledReport, prospects/studentreport, prospects/ajaxDatatables (POST), prospects/ajaxDataProspects (GET), prospects/deleteProspect, prospects/hotProspect, prospects/sendBulkEmail, prospects/ajaxReport, prospects/ajaxReportProspectEnrolled, prospects/exportCSV, prospects/exportCSVStudent, prospects/getStudentsAccordingToProgramAndLocation (POST), prospects/ajaxreportDatatables (POST).
- **Enrollment:** enrollment/index, enrollment, enrollment/addEdit, enrollment/viewEnrollment/(:num), enrollment/enrollmentAdminListing (POST), enrollment/subscription_details_location_wise (POST), enrollment/sendBulkEmail.
- **Schools:** schools/index, schools, schools/addEdit, schools/schoolSummaryReport, schools/ajaxSchoolSummaryReport (POST), schools/exportSchoolSummaryReport (POST), schools/getClassAccordingToProgram (POST), schools/ajaxDatatables (POST), schools/ajaxschooldelete/(:segment) (POST), schools/checkEmail (POST).
- **Users:** users/index, users, users/addEdit, users/viewUserDetails/(:num), users/ajaxDatatables (POST), users/ajaxUserFranchiseDatatables (POST), users/deleteUser/(:num) (POST), users/resetPassword/(:num) (POST), users/userName (POST), users/checkEmail (POST), users/getGeneratedUserName/(:num)/(:segment)/(:segment).
- **Teachers:** teachers/index, teachers, teachers/addEdit, teachers/teacherClassRoom, teachers/ajaxGetTeacherClass (POST), teachers/ajaxTeachersSuperAdminListing (POST), teachers/ajaxTeachersFranchiseeListing (POST), teachers/deleteTeacher (POST), teachers/views/(:segment).
- **ClassRooms:** classRooms/index, classRooms, classRooms/addEdit, classRooms/ajaxDatatables (POST), classRooms/delete/(:segment) (POST).
- **Students:** students/index, students, students/addEdit, students/views/(:segment), students/studentSuperAdminListing (POST), students/studentFranchiseeListing (POST), students/exportStudentdata, students/exportStudentCSVData, students/ajaxActivityInfo, students/ajaxMedicationInfo, students/ajaxBehaviorInfo, students/ajaxMessageInfo, students/ajaxQuestInfo (POST), students/loadAttendanceView/(:segment), students/attend/(:segment) (POST), students/loadFormView/(:segment).
- **Withdraws:** withdraws/index, withdraws, withdraws/addEdit, withdraws/ajaxStudentParentInfo (POST), withdraws/deleteWithdraw (POST).
- **StudentParent:** studentParent/index, studentParent, studentParent/studentParentListing (POST).
- **ParentConcerns:** parentConcerns/index, parentConcerns/addEdit, parentConcerns/concernListing (POST), parentConcerns/ajaxStudentParentInfo (POST), parentConcerns/deleteConcern (POST).
- **Classroster:** classroster/class_list, classroster, classroster/rosterSuperAdminListingCurrent (GET/POST), classroster/month_year (POST), classroster/class_student (POST), classroster/location_student (POST), classroster/select_student (POST), classroster/clear_filters (POST).
- **Activities:** activities/index, activities, activities/addEdit, activities/delete/(:segment)/(:segment) (POST), activities/ajaxGetStudentsClass (POST).
- **Requests:** requests/index, requests, requests/addEdit, requests/deleteRequest/(:segment) (POST).
- **InternalMessage:** internalMessage/index, internalMessage, internalMessage/compose (GET/POST), internalMessage/getRecieverData (POST), internalMessage/sent_items.
- **Portals:** portals, portals/adminAnnouncement, portals/addEditAnnouncement, portals/programAnnouncement, portals/addEditProgramAnnouncement, portals/newsLetter, portals/newsLetterAddEdit, portals/documents, portals/documentAddEdit, portals/sendNotification, portals/ajaxNotificationDatatables (POST), portals/notificationAddEdit, portals/delete* (POST as defined).
- **Events:** events/eventsData, events, events/getdata (GET), events/addEvent (POST), events/getEventData (POST), events/viewEvents (POST), events/updateEvent (POST), events/deleteEvent (POST), events/deleteEventredirection (GET), events/getFilterData (POST), events/setTimeZone (POST).
- **EmailTemplate:** emailTemplate/index, emailTemplate, emailTemplate/addEdit, emailTemplate/ajaxDatatables (POST), emailTemplate/ajaxTemplateDelete (POST), emailTemplate/viewTemplate/(:segment), emailTemplate/checkTemplateName (POST), emailTemplate/emailTemplatePreview (POST).

Unmatched admin paths may fall through to `Placeholder::index` (e.g. `schools/(:any)`, `users/(:any)`) to show an “under migration” or placeholder page.

---

## 9. File Locations

| Type | Path |
|------|------|
| **Controllers** | `app/Controllers/Admin/*.php` |
| **Base controller** | `app/Controllers/Admin/AdminController.php` |
| **Models** | `app/Models/*.php` |
| **Views** | `app/Views/admin/*.php` and `app/Views/admin/include/*.php` |
| **Routes** | `app/Config/Routes.php` (admin group) |
| **Constants** | `app/Config/CmmConstants.php` (e.g. ADMIN_ROLE_ID, SCHOOL_ROLE_ID, SCHOOL_OWNER_ROLE_ID) |

---

## 10. Related Docs

- **admin-school-owner-post-login-analysis.md** – Post-login flow, session, and route analysis for school owner.
- **admin-sidebar-modules-migration.md** – Migration status of sidebar modules (CI3 → CI4).
- **admin-home-login-migration-ci4.md** – Login and home migration details.