# 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).*
