geocrop-platform./apps/nextgen/SCREENS.md

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

---

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