System Architecture

Decoupled API-First Layered Architecture with Offline-First Client Shell

Architectural Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                           CLIENT LAYER (PWA)                            │
│                                                                         │
│  ┌───────────────────────┐  ┌────────────────────────────────────────┐  │
│  │    Service Worker     │  │           Application Shell            │  │
│  │ (Cache Storage Assets)│  │      (Responsive Single Page App)      │  │
│  └───────────────────────┘  └────────────────────────────────────────┘  │
│                                                 │                       │
│  ┌──────────────────────────────────────────────┴────────────────────┐  │
│  │                     Client Storage & State Engine                 │  │
│  │  - IndexedDB: Cached lessons, syllabus metadata, quiz questions   │  │
│  │  - Local Sync Queue: Pending offline mutations + UUID keys         │  │
│  │  - Network State Monitor: Automatic reconnection & sync flush     │  │
│  └──────────────────────────────────────┬────────────────────────────┘  │
└─────────────────────────────────────────┼───────────────────────────────┘
                                          │ HTTPS JSON API (REST)
                                          ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    APPLICATION LAYER (PHP 8.2 MVC)                      │
│                                                                         │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Middleware Pipeline: Auth (Session/Bearer), RBAC, Rate Limiting   │  │
│  └──────────────────────────────────┬────────────────────────────────┘  │
│                                     ▼                                   │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Controllers (Route dispatching, Input validation, JSON Responses) │  │
│  └──────────────────────────────────┬────────────────────────────────┘  │
│                                     ▼                                   │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Domain & Service Logic:                                           │  │
│  │  - Server-Authoritative Auto-Scoring Engine                       │  │
│  │  - Idempotent Sync Processor (UUID de-duplication)                │  │
│  │  - Parent-Child / Teacher-Learner Boundary Authorization          │  │
│  │  - Curriculum Coverage & Compliance Computation                   │  │
│  │  - Comprehensive Audit Logger                                     │  │
│  └──────────────────────────────────┬────────────────────────────────┘  │
│                                     ▼                                   │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Models & Data Layer (PDO Prepared Statements, ACID Transactions)  │  │
│  └──────────────────────────────────┬────────────────────────────────┘  │
└─────────────────────────────────────┼───────────────────────────────────┘
                                      ▼
                      ┌───────────────────────────────┐
                      │    MySQL 8.0 (InnoDB, JSON)    │
                      └───────────────────────────────┘

Key Backend Design Patterns

• Front Controller & Dynamic Router: All requests route through index.php and Router.php with parameter extraction.
• Singleton Database Connection: Enforces strict PDO prepared statements, UTF-8 charset, and Kampala (+03:00) session timezone.
• Standard Response Formatter: Unified JSON envelopes with proper HTTP status codes.
• Layered Middleware: Enforces authentication, role barriers, and rate-limiting before requests reach business logic.

PWA Offline Mode & Sync Protocol

Ensuring uninterrupted home education during power and internet outages

1. Service Worker & Application Shell

The Service Worker (sw.js) intercepts all asset requests. It uses a Cache-First with Network Fallback strategy for UI assets (HTML, CSS, JS, fonts) and a Network-First with Offline JSON fallback for API endpoints.

2. IndexedDB Client Storage

While offline, the application stores:

• Downloaded P1–P7 lesson text, worksheets, and teacher notes.
• Assessment quizzes and questions.
• Learner answers and offline attempt progress.
• Local FIFO Synchronization Queue.

3. Idempotent Synchronization Algorithm

1. Client detects internet restoration via window.addEventListener('online').
2. Sync lock is acquired to prevent concurrent sync races.
3. Client sends oldest pending queue mutation to /api/sync.
4. Server checks UUID in sync_log table:
   • If processed previously: returns stored ACK immediately.
   • If new: validates payload, verifies authorization, recalculates scores, and commits in an ACID transaction.
5. Client receives ACK and removes item from local IndexedDB queue.

Database Schema & Dictionary

MySQL 8.0 Relational Design with 40 Tables, Foreign Keys, and Views

REST API Reference

Standardized JSON endpoints with role authorization

Standard Response Envelope

{
  "success": true,
  "data": { ... },
  "message": "Operation completed successfully.",
  "errors": []
}

Authentication Endpoints

Administration Endpoints

Module 01: Authentication, Users & RBAC

Status: Completed & Tested

Implementation Summary

• Multi-role Login & Routing: Authenticates all 5 roles (Administrator, Curriculum Officer, Teacher, Parent, Learner) and routes to their dedicated dashboards.
• Unified Full Name & Profile Management: Direct full_name column in users table synchronized with actor profile tables (parents, teachers, officers, learners) and editable live from the Profile view.
• Administrative User Editing & Overrides: Full administrative privileges to inspect user profiles, edit full names, emails, contact details, reset passwords immediately, and unlock locked accounts.
• Avatar & Photo Uploads: Multi-part file upload (JPG, PNG, WEBP, GIF $\le 4$MB) with server-side MIME verification and fallback to dynamic UI avatars.
• Role Badge Styling: Color-coded visual tags for distinct role recognition across user pills, dropdown headers, and tables.
• Parent Self-Registration: Transaction-safe creation of user credentials and linked parent profile.
• Security Hardening:
  • Bcrypt password hashing with salt generation.
  • Account lockout after 5 consecutive failed attempts (15 minutes).
  • IP Rate-limiting on authentication routes.
  • Single-use, 1-hour time-expiring reset tokens.
• Client SPA Route Guards: Automatically redirects authenticated users to their dashboards and shields private screens.
• Audit Trail Logging: Logs every login, logout, password change, profile update, admin user edit, admin password reset, and status alteration.

Verification & Test Suite

Run the automated test runner to verify all 19 foundation, authentication, and administrative test assertions:

php tests/test_sprint0_sprint1.php

Module 02: Parent, Family & Learner Management

Status: Completed & Tested

1. Implementation Summary

• Ugandan Primary Curriculum (NCDC P1–P7) Subjects Seeding: All 53 national standard subjects for Primary 1 through Primary 7 seeded into database with weekly hours, instruction language, and subject codes.
• Automatic Subject Allocation: When a child is registered into any class (P1–P7), all active syllabus subjects for that class are automatically enrolled in learner_subjects in a single database transaction.
• Religious Education Customization: Supports selecting Christian Religious Education (CRE) vs. Islamic Religious Education (IRE) tracks upon enrollment.
• Duplicate Learner Guard: Strict multi-column uniqueness check on (parent_id, full_name, date_of_birth) preventing accidental duplicate registrations while permitting same names under different families.
• Special Learning Needs Accommodations: Structured capture of accommodations (extra quiz time, high-contrast visual aids, dyscalculia support) to automatically feed downstream lesson delivery and assessment timers.
• Class Level Promotion & Realignment: Promoting a child from e.g. P3 to P4 seamlessly deactivates old subjects and auto-enrolls new class subjects while preserving historical records.
• Optional Standalone Student Login: Parents can provision independent login credentials (role: learner) for upper primary children (P4–P7) to complete quizzes and read lessons independently.
• Multi-Tenant Data Isolation: Parents are strictly restricted to their own children; teachers access assigned cohorts; administrators maintain global audit oversight.
• Parent Extended Profile: Management of Ugandan National ID (NIN), District, Household Size, and Homeschooling Experience level.
• Offline Caching (PWA): Service worker shell updated to tmhis-shell-v11 ensuring learner profiles and timetables remain accessible offline.

2. Verification & Automated Test Suite

Run the Module 02 automated test runner (14/14 tests passing):

php tests/test_sprint2_learners.php

Sprint & Module Roadmap (01 – 13)

Master Development Plan sequence for TMHIS

Demo & Administrative Credentials

Seeded accounts for system evaluation and testing