161 lines
12 KiB
Markdown
161 lines
12 KiB
Markdown
# Africa Alert - Screen & Navigation Documentation
|
|
|
|
## Overview
|
|
|
|
Africa Alert is a Progressive Web App (PWA) for school management. The application features a dynamic, role-aware architecture adapting to **15 distinct user roles**, each with a custom dashboard and navigation menu.
|
|
|
|
**Core Roles:**
|
|
* 👔 **Systems Admin** (`systems_admin`) - System settings, logs, and synchronization (14 items)
|
|
* 🏫 **School Admin** (`school_admin`) - Complete school operation management (22 items)
|
|
* 🎓 **Principal** (`principal`) - Overall educational and administrative oversight (19 items)
|
|
* 💼 **HR Manager** (`hr`) - Staff payroll, attendance, and HR logs (6 items)
|
|
* 💳 **Bursar** (`bursar`) - Finance, payroll, fee logs, and inventory (8 items)
|
|
* 👩🏫 **Teacher** (`teacher`) - Attendance, grades, courses, and assignments (19 items)
|
|
* 🏆 **Clubs Head** (`clubs_head`) - Club and extracurricular control (5 items)
|
|
* 📚 **Librarian** (`librarian`) - Library books and issue registries (6 items)
|
|
* 👨🎓 **Student** (`student`) - Personal portal, grades, assignments, and exam taking (11 items)
|
|
* 👨👩👧 **Parent** (`parent`) - Monitor student progress and make payment transfers (9 items)
|
|
* 🚍 **Support Staff** (`driver`, `groundsman`, `matron`, `boarding_master`, `security`) - Notices, messages, and schedules (3 items)
|
|
|
|
---
|
|
|
|
## Navigation Architecture
|
|
|
|
### Role-Based Sidebar Navigation
|
|
The navigation sidebar adapts dynamically using the logged-in user's role configuration. Active links are highlighted, and color systems alter dynamically depending on the active portal theme.
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ 🏫 [Dynamic School Logo] [School Name] │
|
|
│ ───────────────────────────────────────────────────────────────────────── │
|
|
│ [Role-Specific Sidebar Menu Item 1] │
|
|
│ [Role-Specific Sidebar Menu Item 2] │
|
|
│ ... │
|
|
│ ───────────────────────────────────────────────────────────────────────── │
|
|
│ [Theme Toggle] [Notice Bell] │
|
|
│ [User Initials Avatar] [Full Name] │
|
|
│ [Logout Button] │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Dynamic Brand Identification
|
|
Rather than a static logo, the branding header components (configured in [Nav.tsx](file:///E:/nextgen/next-gen/client/src/components/Nav.tsx#L225-L247)) dynamically load values from the `/settings` endpoint:
|
|
* **School Name:** Defaults to `NextGen` unless modified in settings.
|
|
* **School Logo:** Dynamically retrieves from `/logo.svg` or uploaded files.
|
|
|
|
---
|
|
|
|
## Role Navigation Configurations
|
|
|
|
### 1. Administrative Roles
|
|
|
|
| Role | Key Nav Items | Route | Description |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **Systems Admin** | Settings, Audit Logs, Sync Logs, Academic Rollover, Users | `/settings`, `/audit-logs`, `/sync-logs`, `/admin/academic-rollover`, `/users` | System stability, backup syncs, global parameters |
|
|
| **School Admin** | Users, Departments, HR, Visitor Log, Hostels, Transport, Library, Marks | `/users`, `/departments`, `/hr/management`, `/front-office/visitors`, `/hostels`, `/transport`, `/library`, `/marks/bulk` | Core day-to-day administrative panels |
|
|
| **Principal** | Curriculum, Users, Departments, Staff Attendance, Library, Bulk Marks | `/teacher-tools`, `/users`, `/departments`, `/hr/attendance`, `/library`, `/marks/bulk` | Academic oversight and staff performance monitoring |
|
|
| **HR** | HR Dashboard, HR Center, Leave Approval, Staff Directory, Staff Attendance, Payslips, Notice Board, Messages | `/dashboard/hr`, `/hr/management`, `/hr/leave-approval`, `/hr/staff`, `/hr/attendance`, `/finance/payslips`, `/notice-board`, `/messages` | Recruitment, salaries, and staff leaves |
|
|
| **Bursar** | Finance Dashboard, Invoices, Expenses, Suppliers, Chart of Accounts, Banking, School Trips, Payroll, Payslips, Fees, Inventory, Finance Reports, Messages | `/dashboard/finance`, `/finance/invoices`, `/finance/expenses`, `/finance/suppliers`, `/finance/chart-of-accounts`, `/finance/banking`, `/finance/trips`, `/finance/payroll/runs`, `/finance/payslips`, `/fees`, `/inventory`, `/reports`, `/messages` | Fees collection, billing, reconciliation, and accounts audits |
|
|
| **Accountant** | Accountant Dashboard, Finance Dashboard, Invoices, Expenses, Suppliers, Chart of Accounts, Banking, School Trips, Payslips, Fees, Reports, Notice Board, Messages | `/dashboard/accountant`, `/dashboard/finance`, `/finance/invoices`, `/finance/expenses`, `/finance/suppliers`, `/finance/chart-of-accounts`, `/finance/banking`, `/finance/trips`, `/finance/payslips`, `/fees`, `/reports`, `/notice-board`, `/messages` | Billing, bank reconciliation, nominal ledger, trip billing |
|
|
|
|
---
|
|
|
|
### 2. Academic & Student Roles
|
|
|
|
| Role | Key Nav Items | Route | Description |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **Teacher** | My Courses, Assignments, My Students, Take Attendance, Bulk Marks, Front Office | `/my-courses`, `/assignments`, `/students`, `/attendance/take`, `/marks/bulk`, `/front-office/visitors` | Complete classroom, evaluation, and logging tools |
|
|
| **Librarian** | Book Catalog, Issue & Return, Notice Board, Extracurriculars | `/library/books`, `/library/issues`, `/notice-board`, `/extracurriculars` | Managing books, reservations, and reading lists |
|
|
| **Clubs Head** | Extracurriculars Management, My Extracurriculars, Messages | `/clubs-management`, `/extracurriculars`, `/messages` | Managing school clubs, registrations, and club logs |
|
|
| **Student** | Exam Portal, Online Exams, Grades, Assignments, My Courses, Enrollments | `/exams`, `/exams/take`, `/grades`, `/assignments`, `/my-courses`, `/enrollments` | Daily school materials and exam completions |
|
|
| **Parent** | Progress, Schedule, Attendance History, Fees, Extracurriculars | `/academic-progress`, `/calendar`, `/attendance/history`, `/fees`, `/extracurriculars` | Children tracking dashboard |
|
|
|
|
---
|
|
|
|
### 3. Support & Service Roles
|
|
*(Includes `driver`, `groundsman`, `matron`, `boarding_master`, `security`)*
|
|
* **Notice Board** (`/notice-board`) - Viewing school announcements.
|
|
* **Messages** (`/messages`) - Chat with administration and teaching staff.
|
|
* **Schedule** (`/events`) - School activity calendar.
|
|
|
|
---
|
|
|
|
## Screen Profiles & Interface Specifications
|
|
|
|
### 🔑 Authentication (`/login`)
|
|
Provides interactive forms matching email and password. Includes dynamic **Quick-Select Buttons** corresponding to roles (`Admin`, `Teacher`, `Student`, `Parent`) that auto-fill demo credentials. Redirects authenticated requests with JWT tokens stored locally.
|
|
|
|
### 📊 Dashboard Panels
|
|
1. **School/Sys Admin Dashboard (`/dashboard/admin`):** Analytics panels displaying active enrollments, staff attendance summaries, platform sync status, and system audit actions.
|
|
2. **Teacher Dashboard (`/dashboard/teacher`):** Integrates lesson timetables, task lists, assignments due, and classes shortcut list.
|
|
3. **Student Dashboard (`/dashboard/student`):** Shows student profile badge, exam reminders, homework tasks, and latest grades.
|
|
4. **Parent Dashboard (`/dashboard/parent`):** Lists children details side-by-side with individual attendance progress and pending fees.
|
|
|
|
### 🏆 Extracurriculars Portal (`/extracurriculars` & `/clubs-management`)
|
|
* **Teacher/Clubs Head View:** Extracurricular lists showing active club names, assigned supervisors, student rosters, and schedules. Can create new clubs or edit details.
|
|
* **Student/Parent View:** Provides catalogs of available clubs. Students can request join enrollment, while parents approve registrations.
|
|
|
|
### 🏢 Front Office Module
|
|
* **Visitor Log (`/front-office/visitors`):** Log incoming guest details, purpose of visit, host name, and check-in/out timestamps.
|
|
* **Admission Enquiry (`/front-office/enquiries`):** Record prospective student enquiries, phone details, status, and follow-up notes.
|
|
* **Complaints (`/front-office/complaints`):** Capture complaints, assign severity, write descriptions, and update resolution states.
|
|
* **Phone Calls (`/front-office/phone-calls`):** Call log registries capturing caller names, duration, and summary.
|
|
* **Postal Dispatch (`/front-office/postal`):** Logs sent and received physical letters, tracking reference numbers and addresses.
|
|
|
|
### 📝 Exam & Grade Portals
|
|
* **Exam Editor (`/exams/edit/:id`):** Interface for teachers to build online exams, configuring questions, multiple-choice options, and point weights.
|
|
* **Take Exam (`/exams/take`):** Student testing interface featuring question timers, progress meters, and immediate autosave backup.
|
|
* **Bulk Marks (`/marks/bulk`):** Allows administrative staff and teachers to upload/import student grades in bulk via CSV files or spreadsheets.
|
|
|
|
---
|
|
|
|
## Role Permissions Matrix
|
|
|
|
| Module Path | Sys Admin | School Admin | Principal | Bursar | Teacher | Student | Parent | Clubs Head | Support |
|
|
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
|
|
| `/settings` | **CRUD** | - | - | - | - | - | - | - | - |
|
|
| `/audit-logs` | **View** | - | - | - | - | - | - | - | - |
|
|
| `/users` | **CRUD** | **CRUD** | **View** | - | - | - | - | - | - |
|
|
| `/departments` | **CRUD** | **CRUD** | **View** | - | - | - | - | - | - |
|
|
| `/hr/management` | - | **CRUD** | **CRUD** | **View** | - | - | - | - | - |
|
|
| `/finance/payroll` | - | - | - | **CRUD** | - | - | - | - | - |
|
|
| `/fees` | **View** | **CRUD** | - | **CRUD** | - | **View** | **Pay** | - | - |
|
|
| `/front-office/*` | **CRUD** | **CRUD** | **CRUD** | - | **CRUD** | - | - | - | - |
|
|
| `/attendance/take` | **CRUD** | **CRUD** | **CRUD** | - | **CRUD** | - | - | - | - |
|
|
| `/my-courses` | - | - | - | - | **CRUD** | **View** | - | - | - |
|
|
| `/exams/take` | - | - | - | - | - | **Execute** | - | - | - |
|
|
| `/clubs-management` | - | - | - | - | - | - | - | **CRUD** | - |
|
|
| `/extracurriculars` | **View** | **View** | **View** | **View** | **View** | **View** | **View** | **View** | - |
|
|
| `/notice-board` | **CRUD** | **CRUD** | **CRUD** | **View** | **View** | **View** | **View** | **View** | **View** |
|
|
| `/sanatorium` | **CRUD** | **CRUD** | **CRUD** | - | - | - | - | - | - |
|
|
| `/dining-hall` | **View** | **View** | **View** | - | - | - | - | - | - |
|
|
| `/medical/class/:classId` | - | - | - | - | **View** | - | - | - | - |
|
|
| `/medical` | - | - | - | - | - | **R** | **R/W** | - | - |
|
|
|
|
> Note: `/medical/hub-access` for nurse and dining_staff is gated by the new `nurse` and
|
|
> `dining_staff` roles (now in the `users.role` CHECK). These columns are omitted
|
|
> above to preserve the existing matrix width — see `.harness/changelogs/2026-07-09-student-medical-records.md`
|
|
> for the per-route role tables.
|
|
|
|
|
|
*Legend: CRUD = Create, Read, Update, Delete; View = Read-only access; Pay = Financial payment triggers; Execute = Run interactive exams.*
|
|
|
|
---
|
|
|
|
## Route & Navigation Security Flow
|
|
1. **JWT Verification:** Reads token from `localStorage` under keys managed in [auth.ts](file:///E:/nextgen/next-gen/client/src/store/auth.ts).
|
|
2. **Allowed Role Check:** The `ProtectedRoute` component intercepts navigation and evaluates `user.role` against `allowedRoles`.
|
|
3. **Intelligent Redirect:** If validation fails, users are rerouted back to their matching role dashboard (defined in [App.tsx](file:///E:/nextgen/next-gen/client/src/App.tsx#L109-L123)).
|
|
|
|
---
|
|
|
|
*Document Version: 4.0*
|
|
*Last Updated: July 2026*
|
|
*Features: 15 active roles, dynamic brand identity, extracurricular modules, front office tracking.*
|
|
|
|
*Document Version: 4.1 — Student Medical Records added*
|
|
*Last Updated: July 2026 (feature/student-medical-records)*
|
|
*New: 3 tables (student_medical_profiles, student_medication_logs, student_medical_history),
|
|
new role `dining_staff`, full UI for existing `nurse` role (Sanatorium Portal,
|
|
Dining Hall alerts, teacher class flags, parent + student self-view).*
|