# CMMSchool Management System
## Enterprise Migration Case Study
### CodeIgniter 3 → CodeIgniter 4 | PHP 8.4 | Full-Stack Architectural Modernisation

**Prepared by:** Senior Engineering Team
**Engagement Type:** Framework Migration & Platform Modernisation
**Delivery Model:** Fixed-scope, milestone-based
**Total Engineering Investment:** 505 Hours
**Delivery Timeline:** 2 Weeks (Structured Sprint Execution)

---

## Table of Contents

1. [Executive Summary](#1-executive-summary)
2. [Client & System Background](#2-client--system-background)
3. [Problem Statement & Risk Assessment](#3-problem-statement--risk-assessment)
4. [Scope of Engagement](#4-scope-of-engagement)
5. [Engineering Methodology](#5-engineering-methodology)
6. [Phase 1 — Discovery, Audit & Architecture Planning](#6-phase-1--discovery-audit--architecture-planning)
7. [Phase 2 — Project Scaffold & Environment Setup](#7-phase-2--project-scaffold--environment-setup)
8. [Phase 3 — Model Layer Migration](#8-phase-3--model-layer-migration)
9. [Phase 4 — Controller Layer Migration](#9-phase-4--controller-layer-migration)
10. [Phase 5 — View Layer Conversion](#10-phase-5--view-layer-conversion)
11. [Phase 6 — Routing Architecture & Filter System](#11-phase-6--routing-architecture--filter-system)
12. [Phase 7 — Payment Gateway Rebuild](#12-phase-7--payment-gateway-rebuild)
13. [Phase 8 — Security Architecture & Authentication](#13-phase-8--security-architecture--authentication)
14. [Phase 9 — Test Suite Engineering](#14-phase-9--test-suite-engineering)
15. [Phase 10 — QA, UI Alignment & Bug Resolution](#15-phase-10--qa-ui-alignment--bug-resolution)
16. [Phase 11 — Code Review, Refactoring & Documentation](#16-phase-11--code-review-refactoring--documentation)
17. [System Architecture: Before & After](#17-system-architecture-before--after)
18. [Full Module Inventory](#18-full-module-inventory)
19. [Database Schema Analysis](#19-database-schema-analysis)
20. [Technology Stack Delivered](#20-technology-stack-delivered)
21. [Engineering Hours Summary](#21-engineering-hours-summary)
22. [Results & Outcomes](#22-results--outcomes)
23. [Conclusion](#23-conclusion)

---

## 1. Executive Summary

| Field | Detail |
|---|---|
| **Client** | CMMSchool — Multi-School Montessori Operations Platform |
| **Engagement** | Full Framework Migration & Platform Modernisation |
| **Source Framework** | CodeIgniter 3 · PHP 5.x / 7.x · MySQL |
| **Target Framework** | CodeIgniter 4 · PHP 8.4 · MySQL |
| **Engineering Investment** | **505 Hours** |
| **Delivery Duration** | **2 Weeks** |
| **Assets Migrated** | 131+ Models · 30+ Controllers · 219 Views · 127+ DB Tables |
| **Production Data Loss** | **Zero** |
| **Schema Modifications** | **None** |
| **Downtime** | **Zero** |

CMMSchool operated a large-scale, multi-role school management platform built on CodeIgniter 3 — a framework that had formally reached end-of-life. The platform served three distinct user groups (Administrators, Teachers, and Parents) across multiple concurrent school deployments, processing live student records, daily classroom workflows, and Stripe-based payment transactions.

The engagement required a complete, production-grade migration from CodeIgniter 3 to CodeIgniter 4 — a fundamentally different framework architecture, not a version increment. This involved the systematic re-engineering of every application layer: configuration, models, controllers, views, routing, security, and payment integration. Simultaneously, a PHPUnit test suite was engineered from the ground up to validate every migrated component.

The migration was executed under strict constraints:

- **No business logic modifications** — all application behaviour had to be preserved exactly.
- **No database schema changes** — the production MySQL schema (127+ tables) had to remain structurally identical.
- **No user-facing disruption** — the platform had to remain operational throughout.

The total engineering investment was **505 hours**, executed across a structured 2-week sprint by a senior engineering team.

---

## 2. Client & System Background

CMMSchool is a **Montessori-focused, multi-school operational platform** that manages the complete administrative and academic lifecycle of one or more schools from a single system. The platform was purpose-built around Montessori education principles, incorporating domain-specific workflows — including Montessori Record-keeping & Assessment (RA), Baseline Assessments (BA), and Quest-based lesson planning — that are not available in off-the-shelf school management software.

### User Groups & Portal Structure

The platform serves three distinct user groups, each operating through a dedicated portal with isolated session contexts, role-based access controls, and workflow-specific views:

| Portal | User Group | Core Responsibilities |
|---|---|---|
| **Admin Portal** (`admin/*`) | Administrators & School Owners | School configuration, user management, enrollment pipeline, financial oversight, reporting, communications |
| **TP Portal** (`tp/*`) | Teachers & Parents | Daily classroom operations, lesson planning, student assessments, parent-teacher communication, enrollment, payments |
| **Public / System** | Unauthenticated users | Registration form access, Stripe webhook endpoint |

### System Scale

| Metric | Value |
|---|---|
| Active user roles | Admin, School Owner, Teacher, Parent, Student |
| Module groups | 3 (Admin, TP Portal, Public) |
| Application controllers | 30+ |
| View templates | 219 |
| Domain models | 131+ |
| Production database tables | 127+ |
| Third-party integrations | Stripe, SMTP Email, Google Calendar OAuth |
| Specialist subsystems | Montessori RA, Baseline Assessment, Quest Lesson Planning, Multi-school Roster |

---

## 3. Problem Statement & Risk Assessment

### 3.1 Framework End-of-Life

CodeIgniter 3 reached end-of-life in October 2022 and no longer receives security patches, bug fixes, or compatibility updates. The client's production application — handling personally identifiable student data, parent financial records, and payment processing — was running on an unmaintained framework. This represented a direct compliance risk and an increasing liability exposure with each passing month.

### 3.2 PHP Version Incompatibility

CodeIgniter 3 is architecturally incompatible with PHP 8.x. PHP 7.4 itself reached end-of-life in November 2022. The client's hosting environment was locked to an aging PHP version because upgrading the runtime would break the application entirely. This blocked:

- OS-level security patch application (PHP runtime is tightly coupled to OS update cycles)
- Access to PHP 8.x performance improvements (JIT compilation, typed properties, match expressions)
- Adoption of any modern PHP library requiring PHP 8+

### 3.3 Technical Debt Profile

A pre-migration audit of the codebase revealed deeply embedded CI3-specific patterns across every layer of the application:

**Controller layer:**
- `$this->load->model(...)` in every controller method — no dependency injection
- `$this->input->post(...)` — untyped, unsanitised input access throughout
- `$this->input->get(...)` — no type coercion or validation at the request layer
- `redirect(base_url().'path')` — string concatenation redirects, no named routes

**Model layer:**
- All models extending `CI_Model` — no schema introspection, no built-in validation
- Raw `$this->db->query(...)` calls mixed with query builder patterns
- Validation rules defined as flat arrays in controller methods, not models
- No `$allowedFields` — mass-assignment risk throughout

**View layer:**
- `$this->load->view('path', $data)` — CI3 loader syntax in all 219 templates
- `$this->session->flashdata('key')` — CI3 session API in every form response view
- `$this->config->item('base_url')` — CI3 config access for every asset URL
- `set_value()` / `form_error()` — CI3 form helpers in all form templates
- `base_path()` / custom URL helpers — non-standard, non-portable patterns

**Infrastructure:**
- No PSR-4 namespacing — all classes loaded by file-path convention
- No Composer autoloading for application code
- No environment-based configuration — credentials partially hardcoded
- No test suite whatsoever — zero automated coverage
- Global constants (`TEACHER_ROLE_ID`, `ADMIN_ROLE_ID`, etc.) defined without namespacing

### 3.4 The Rebuild vs. Migration Decision

A complete application rebuild was evaluated and rejected on the following grounds:

- **Business logic risk:** Montessori-specific workflows (RA assessments, Quest lesson planning, multi-school roster management) had years of domain refinement embedded in existing code. Rebuilding risked introducing subtle behavioural differences that would require weeks of domain-expert validation.
- **Data continuity risk:** The production database with 127+ tables and live school data could not be altered. A new application would require a parallel data migration strategy — adding significant complexity and risk.
- **Timeline:** A rebuild would require 6–12 months minimum for a system of this scale and domain complexity.

The decision: **migrate the framework layer; preserve the application layer intact.**

---

## 4. Scope of Engagement

### Deliverables

| Deliverable | Description |
|---|---|
| CI4 application structure | PSR-4 namespaced, Composer-managed, environment-driven |
| Migrated models | 131+ models — CI4 `CodeIgniter\Model`, `$validationRules`, `$allowedFields` |
| Migrated controllers | 30+ controllers — namespaced, CI4 request/response lifecycle |
| Converted views | 219 templates — CI4 `view()`, `old()`, `base_url()`, `session()` |
| Routing architecture | All routes explicitly registered in `app/Config/Routes.php` |
| Authentication filters | CI4 Filter-based auth guards per route group and user type |
| Stripe integration | Full rebuild — Checkout Sessions, Payment Intents, signed Webhooks |
| PHPUnit test suite | 9 feature/integration test files covering all major flows |
| Environment configuration | `.env`-driven config for all secrets and environment values |
| Technical documentation | Architecture docs, migration patterns, environment reference |

### Explicit Exclusions

- No new feature development
- No database schema alterations
- No UI redesign or frontend library upgrades
- No changes to Montessori domain business rules

---

## 5. Engineering Methodology

### 5.1 Layered Migration Strategy

The migration was executed bottom-up: infrastructure and configuration were stabilised first, then models, then controllers, then views. This sequencing ensured that each layer could be tested in isolation before the layer above it was migrated.

```
Layer Order (bottom → top):
  1. Config & Constants
  2. Models (data layer)
  3. Controllers (application logic layer)
  4. Views (presentation layer)
  5. Routes & Filters (request routing layer)
  6. Integrations (Stripe, Email)
  7. Tests (validation layer)
```

### 5.2 Guiding Constraints

**Constraint 1 — Business Logic Parity**
Every piece of application logic was required to behave identically in CI4 as in CI3. This was enforced through line-by-line comparison during controller migration, not assumption-based conversion.

**Constraint 2 — Schema Immutability**
No DDL statements were executed against the production database at any point during the migration. All 127+ tables, column definitions, indexes, and foreign key relationships were treated as immutable.

**Constraint 3 — Progressive Validation**
No module was considered complete until its corresponding feature tests passed against a real database, real HTTP routes, and — where applicable — real Stripe test-mode API responses.

**Constraint 4 — Zero Regression Policy**
Every behavioural change, even one correcting a pre-existing defect, required explicit documentation and client sign-off before being included in the migration scope.

### 5.3 CI3 → CI4 Conversion Reference

Before any file was modified, a complete CI3-to-CI4 pattern mapping was documented and agreed upon. This reference governed every conversion decision made throughout the engagement:

| Domain | CI3 Pattern | CI4 Equivalent | Notes |
|---|---|---|---|
| Model loading | `$this->load->model('name')` | `model(NameModel::class)` | Constructor injection preferred |
| View rendering | `$this->load->view('path', $data)` | `return view('path', $data)` | Return keyword required in CI4 |
| POST input | `$this->input->post('x')` | `$this->request->getPost('x')` | Type-safe alternative available |
| GET input | `$this->input->get('x')` | `$this->request->getGet('x')` | — |
| Base URL | `$this->config->item('base_url')` | `base_url()` | Helper pre-loaded in BaseController |
| Session set | `$this->session->set_userdata('k','v')` | `session()->set('k', 'v')` | — |
| Session get | `$this->session->userdata('k')` | `session()->get('k')` | — |
| Flash data set | `$this->session->set_flashdata('k','v')` | `session()->setFlashdata('k', 'v')` | — |
| Flash data get | `$this->session->flashdata('k')` | `session()->getFlashdata('k')` | — |
| Redirect | `redirect(base_url().'path')` | `return redirect()->to(base_url('path'))` | Must be returned |
| Form old value | `set_value('field')` | `old('field')` | — |
| Form error | `form_error('field')` | `$validation->getError('field')` | Passed from controller |
| Global constants | `TEACHER_ROLE_ID` | `CmmConstants::TEACHER_ROLE_ID` | Namespaced config class |
| Auth check | `$this->securities->AllowedRoles(…)` | CI4 Filter (before hook) | Decoupled from controller |
| AJAX | `$.get()` / `$.post()` / `$.ajax()` | `fetch()` (native) | JSON response headers set |
| DB query | `$this->db->query(…)` | `$this->db->query(…)` | Identical — CI4 retains this |
| Query builder | `$this->db->select(…)->get(…)` | `$this->db->table(…)->select(…)->get()` | Table reference required |

---

## 6. Phase 1 — Discovery, Audit & Architecture Planning

**Engineering Hours: 40 hours**

### 6.1 Codebase Audit (20 hours)

Before any migration work could begin, a structured audit of the legacy CI3 codebase was conducted across all layers. This was not a surface-level review — each file was opened, read, and catalogued with its complexity classification, dependency map, and CI4 conversion requirements.

**Audit deliverables:**

- Complete inventory of all CI3 controllers, mapped to their route groups, dependencies, and session contexts
- Complete inventory of all 131+ models: table bindings, custom query methods, validation rule locations, and cross-model dependencies
- Inventory of all 219 view files: CI3 syntax usage frequency, asset dependencies, include graph
- Map of all global constants and their usage across the codebase
- Map of all session variables set and read across all user portals (Teacher, Parent PA, Parent Portal PP, Admin)
- Identification of all database query patterns: raw query, query builder, stored-procedure-equivalent methods
- Stripe integration audit: endpoint mapping, payload structure, callback handling, database write patterns
- Identification of all jQuery AJAX calls requiring fetch() conversion and their expected response contracts

**Complexity classification system used:**

| Classification | Criteria | Count |
|---|---|---|
| Low | Table binding only, no custom methods, no custom validation | ~80 models |
| Medium | 2–6 custom query methods, some cross-model calls | ~35 models |
| High | Complex auth logic, multi-join queries, file handling, Stripe interaction, session management | ~16 models |

### 6.2 Architecture Planning (12 hours)

Based on the audit findings, the CI4 application architecture was designed before a single file was written. Key architectural decisions made during this phase:

**Namespace structure:**
```
App\Controllers\Admin\      — all admin module controllers
App\Controllers\Tp\         — all teacher/parent portal controllers
App\Controllers\Webhook\    — payment webhook handlers
App\Models\                 — all domain models (flat namespace, 131+ files)
App\Libraries\              — shared service classes (EnrollmentStripeHelper, etc.)
App\Filters\                — CI4 Filter classes for authentication guards
Config\                     — all typed configuration classes
```

**Session isolation design:**
Four independent session context patterns were designed to handle the multi-portal authentication requirements:
- `tp_te` context — Teacher portal session
- `tp_pa` context — Parent portal session
- `tp_pp` context — Parent iframe portal session
- `admin` context — Administrator / School Owner session

Each context required its own session key namespace, guard logic, and redirect target — all of which had to be precisely replicated from CI3 behaviour.

**Filter architecture:**
CI4 Filters were designed as a replacement for the inline `$this->securities->sessionExistRedirect()` calls that appeared in CI3 controllers. A Filter matrix was designed mapping each route group prefix to its required authentication context.

### 6.3 CI3-to-CI4 Pattern Documentation (8 hours)

The conversion reference table (Section 5.3) was compiled and validated against representative samples from the actual codebase — not from documentation alone. Edge cases were identified and documented:

- Methods that returned `void` in CI3 but must `return redirect()` in CI4
- Flash data patterns that used CI3's combined set+redirect in a single call
- Custom `MY_` helper functions that needed to be ported to `app/Helpers/`
- Query builder calls that used CI3's implicit table scope vs CI4's explicit `->table()` requirement

---

## 7. Phase 2 — Project Scaffold & Environment Setup

**Engineering Hours: 15 hours**

### 7.1 CI4 Project Initialisation (3 hours)

The CI4 application was initialised using `codeigniter4/appstarter` via Composer, establishing the base directory structure. The public web root was configured to `public/index.php` maintaining identical URL behaviour to the CI3 deployment.

```
composer create-project codeigniter4/appstarter cmmschoolupgrade
```

All legacy asset directories (`public/admin/`, `public/tp/`, `public/registration_paper_form/`) were mapped to the new public root with path equivalency verified against the CI3 deployment.

### 7.2 Composer Dependency Configuration (2 hours)

`composer.json` was configured with all required production and development dependencies:

**Production (`require`):**
- `codeigniter4/framework: ^4.0` — framework core
- `phpoffice/phpspreadsheet: ^5.5` — spreadsheet export (existing functionality)
- `stripe/stripe-php: ^16.0` — rebuilt Stripe integration

**Development (`require-dev`):**
- `phpunit/phpunit: ^10.5.16` — test runner
- `fakerphp/faker: ^1.9` — test data generation
- `mikey179/vfsstream: ^1.6` — virtual filesystem for file-handling tests

**PHP platform pin:** `"platform": {"php": "8.4.18"}` — lockfile generated against the production PHP runtime version.

**PSR-4 autoload map:**
```json
"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Config\\": "app/Config/"
    }
}
```

### 7.3 Configuration Class Migration (6 hours)

All CI3 configuration was converted from PHP array files to CI4 typed configuration classes:

**`app/Config/App.php`** — base URL, environment, charset, timezone, session parameters. The session configuration required particular care: CI3 stored sessions in files by default; CI4 was configured for database-backed sessions to match the existing `ci_sessions` table in production.

**`app/Config/Database.php`** — MySQL connection parameters migrated from `database.php` array config to CI4's typed class. A `tests` database group was added for PHPUnit isolation. The `DBDebug` flag was set to `false` in production config to suppress database error exposure.

**`app/Config/Stripe.php`** — a new typed config class (no CI3 equivalent) was designed to encapsulate Stripe API keys and webhook secrets. All values were wired to `env()` calls, not hardcoded:

```php
public string $secretKey     = '';
public string $publishableKey = '';
public string $webhookSecret  = '';
public bool   $testMode       = true;

public function __construct() {
    parent::__construct();
    $this->secretKey      = (string) env('stripe.secretKey', '');
    $this->publishableKey = (string) env('stripe.publishableKey', '');
    $this->webhookSecret  = (string) env('stripe.webhookSecret', '');
    $this->testMode       = filter_var(env('stripe.testMode', 'true'), FILTER_VALIDATE_BOOLEAN);
}
```

**`app/Config/CmmConstants.php`** — the CI3 `constants.php` global definitions were converted to a namespaced class with `public const` declarations. Every reference across 131+ models and 30+ controllers was updated to use `CmmConstants::CONSTANT_NAME`.

**`app/Config/Email.php`** — SMTP parameters migrated from CI3 config array to CI4 Email config class. UTF-8 charset enforced.

**`app/Config/Migrations.php`** — migration config preserved; existing migration history files carried forward.

### 7.4 BaseController Setup (2 hours)

`app/Controllers/BaseController.php` was configured with helpers loaded for all controllers:

```php
protected $helpers = ['url', 'form', 'text'];
```

This eliminated the need for `$this->load->helper(...)` calls that appeared in CI3 controllers — replacing one line of code per controller method with a single inherited configuration.

### 7.5 `.env` Configuration (2 hours)

The `.env` file structure was documented with all required variables and their expected formats, covering: application, database, email, Stripe, and encryption key configuration. Separate `.env.example` was created for onboarding documentation.

---

## 8. Phase 3 — Model Layer Migration

**Engineering Hours: 125 hours**

The model layer was the foundation of the migration. All 131+ domain models had to be individually converted from `CI_Model` to `CodeIgniter\Model` before any controller work could proceed — controllers depend on models, not the reverse.

### 8.1 Migration Pattern Applied to All Models

For every model, the following systematic conversion was applied:

**Step 1 — Namespace declaration:**
```php
// CI3
class TeacherModel extends CI_Model { ... }

// CI4
namespace App\Models;
use CodeIgniter\Model;
class TeacherModel extends Model { ... }
```

**Step 2 — Schema property declaration:**
CI4 models require explicit schema binding. Every model was given:
```php
protected $table      = 'teachers';
protected $primaryKey = 'id';
protected $allowedFields = ['user_id', 'school_id', 'status', ...];
protected $useTimestamps = false; // set true only where created_at/updated_at existed
```

`$allowedFields` was derived by reading the actual table schema — not inferred from existing query patterns. This eliminated mass-assignment vulnerabilities that existed in the CI3 codebase.

**Step 3 — Query builder modernisation:**
CI3 used an implicit table scope: `$this->db->select(…)->get()`. CI4 requires explicit table reference: `$this->db->table('teachers')->select(…)->get()`. Every database call was updated.

**Step 4 — Validation migration:**
Validation rules that were defined as arrays in CI3 controller methods were moved into model `$validationRules` and `$validationMessages` properties.

**Step 5 — Custom method preservation:**
All business-logic methods were carried forward line-by-line. Return types and parameter signatures were preserved exactly.

### 8.2 Model Complexity Breakdown & Hours

#### Low-Complexity Models (~80 models · ~48 hours)

These models contained primarily `$table` binding and standard CRUD operations with minimal custom logic. Typical examples: `CountryModel`, `GenderModel`, `PhoneTypeModel`, `StaffTypeModel`, `EthnicityModel`, `DayModel`, `MonthModel`, `LeavingReasonModel`.

Work per model: read legacy file, declare namespace, update extends, declare schema properties, update any query builder calls, verify `$allowedFields`, write.

**Average per model: 36 minutes · 80 models = ~48 hours**

#### Medium-Complexity Models (~35 models · ~52 hours)

These models contained 2–8 custom query methods, join operations, or cross-model calls. Examples: `ClassRoomModel`, `EnrollmentStatusModel`, `ActivityModel`, `ProspectModel`, `EventModel`, `TeacherScheduleModel`, `StudentSiblingModel`, `FamilyModel`.

Additional work over low-complexity: validating join syntax for CI4, ensuring `->table()` is used as the base for all builder chains, verifying subquery patterns, testing return structures against controller expectations.

**Average per model: 90 minutes · 35 models = ~52.5 hours**

#### High-Complexity Models (~16 models · ~25 hours)

These models contained deep business logic, multi-join queries, file handling, Stripe integration, multi-role session logic, or served as the foundation for other models. Each required careful line-by-line review.

| Model | Hours | Reason for Complexity |
|---|---|---|
| `SecuritiesModel` | 3.5 hrs | Auth logic for 4 user types, session guard methods, sanitisation, `authenticateLogin()` across all portals |
| `UtilityModel` | 3.0 hrs | Timezone setting, front-end school/class selection, session-based config, `fronEndChooseSchool()` with parent branch |
| `QuestModel` | 2.0 hrs | Lesson plan validation rules, file path config for documents/thumbs/images, CI4 validation migration |
| `AssessmentModel` | 2.0 hrs | Montessori RA + Baseline Assessment rules, `studentAssessmentRules()`, `baAddEditRules()`, multi-table inserts |
| `EnrollmentModel` | 2.0 hrs | Registration pipeline logic, Stripe session handoff, status transition rules |
| `StudentEnrollmentModel` | 1.5 hrs | Parallel model to EnrollmentModel with TP-facing methods |
| `LessonplanModel` | 1.5 hrs | Monthly lesson plan add/edit rules, login rules, program linking |
| `PortalModel` | 1.5 hrs | Newsletter/announcement config, document handling, program-level scoping |
| `ProspectRequestTourModel` | 1.5 hrs | Tour request + child prospect + notes + program linking, multi-table coordination |
| `AdminModel` | 1.5 hrs | Admin-specific login rules, forgot-password rules, cross-portal auth |
| `ClassRosterModel` | 1.5 hrs | Future class assignment logic, thumbnail/image/document config, maps to `student_class_future` |
| `CommonModel` | 1.0 hr | Pagination `load_default_configuration()`, shared lookup queries |
| `StripePaymentModel` | 1.0 hr | Payment record schema, `stripe_payment` table insert/update |
| `TeacherModel` | 1.0 hr | Cross-table profile queries, school-teacher linkage |
| `StudentModel` | 1.0 hr | Multi-join student profile queries, family linkage |
| `UserModel` | 1.0 hr | User + role + access level joins, login detail tracking |

**Total high-complexity: ~25.5 hours**

**Phase 3 Total: ~125 hours**

---

## 9. Phase 4 — Controller Layer Migration

**Engineering Hours: 95 hours**

Controllers required the most intensive per-file effort of the entire migration. Unlike models — which follow a predictable structural pattern — each controller encodes unique application logic, session interactions, redirect flows, and AJAX response contracts that had to be individually validated.

### 9.1 Migration Pattern Applied to All Controllers

**Step 1 — Namespace & class declaration:**
```php
// CI3
class Students extends CI_Controller { ... }

// CI4
namespace App\Controllers\Admin;
use App\Controllers\BaseController;
class Students extends BaseController { ... }
```

**Step 2 — Constructor injection:**
CI3 used `$this->load->model(…)` in constructors and methods. CI4 uses typed constructor injection or `model()` helper:

```php
// CI3
public function __construct() {
    parent::__construct();
    $this->load->model('student_model');
}

// CI4
protected StudentModel $studentModel;

public function __construct() {
    $this->studentModel = model(StudentModel::class);
}
```

**Step 3 — Request input:**
Every `$this->input->post('field')` was replaced with `$this->request->getPost('field')`. Where type coercion was required, typed variants were used: `getPost('id', FILTER_VALIDATE_INT)`.

**Step 4 — Session access:**
All CI3 session patterns replaced with CI4 equivalents. Particular care was taken with flash data — CI3 allowed `set_flashdata` and redirect in separate calls; CI4 requires the flash data to be set before the redirect response is returned.

**Step 5 — Response patterns:**
All `redirect()` calls converted to `return redirect()->to()`. All view renders converted to `return view('path', $data)`. AJAX JSON responses converted to `return $this->response->setJSON($data)`.

**Step 6 — Auth guard removal:**
Inline auth checks (`$this->securities->sessionExistRedirect('te')`) were removed from controller methods and replaced with CI4 Filter declarations in `app/Config/Filters.php`.

### 9.2 Controller Complexity Breakdown & Hours

#### Admin Controllers (18 controllers · ~58 hours)

Admin controllers were the most complex in the system. Each manages multiple CRUD operations, DataTables AJAX endpoints, file upload handling, cross-model data assembly, and role-based conditional logic.

| Controller | Hours | Key Complexity |
|---|---|---|
| `Admin\Students` | 5.0 hrs | Student CRUD, siblings, forms, withdrawals, medical notes, behavioral data — multi-model orchestration |
| `Admin\Teachers` | 4.5 hrs | Teacher profiles, school assignment, schedule management, class linking |
| `Admin\Enrollment` | 4.5 hrs | Registration pipeline, status transitions, Stripe payment recording (Cash/Cheque admin flow) |
| `Admin\Prospects` | 4.0 hrs | Tour request CRUD, prospect children, tour notes, program assignment, status tracking |
| `Admin\ClassRooms` | 3.5 hrs | Room-program linking, activity schedules, capacity management |
| `Admin\Classroster` | 3.5 hrs | Future class roster management, DataTables integration, class-student assignment |
| `Admin\Users` | 3.5 hrs | User + role + access level management, password handling |
| `Admin\Schools` | 3.0 hrs | Multi-school config, school category, staff linkage |
| `Admin\InternalMessage` | 3.0 hrs | Staff messaging, attachment handling, read/unread state |
| `Admin\TeacherMessage` | 3.0 hrs | Teacher message threads, webcam attachment handling |
| `Admin\Portals` | 2.5 hrs | Announcement, newsletter, document, notification management per program |
| `Admin\Events` | 2.5 hrs | Calendar event CRUD, Google Calendar sync structure |
| `Admin\Withdraws` | 2.0 hrs | Withdrawal processing, reason recording, student status update |
| `Admin\ParentConcerns` | 2.0 hrs | Concern logging, category, priority, resolution workflow |
| `Admin\Activities` | 1.5 hrs | Activity CRUD, type and program linking |
| `Admin\EmailTemplate` | 1.5 hrs | Template CRUD, variable placeholder handling |
| `Admin\Requests` | 1.5 hrs | Request tracking, status management |
| `Admin\StudentParent` | 1.5 hrs | Student-parent relationship management, family linking |

**Admin subtotal: ~57.5 hours**

#### TP Controllers (13 controllers · ~33 hours)

TP controllers handle the teacher/parent portal workflows. They are characterised by session-context sensitivity (different behaviour based on which user type is logged in), AJAX-heavy DataTables integrations, and real-time roster operations.

| Controller | Hours | Key Complexity |
|---|---|---|
| `Tp\Ur` | 4.0 hrs | Unified role dashboard, `chooseSchool`, `getClass`, `signin_out` — multi-role session management, JSON feed endpoints |
| `Tp\Quests` | 4.0 hrs | Montessori lesson plan CRUD, assignment management, file upload, record-keeping views |
| `Tp\Rosters` | 3.5 hrs | Real-time check-in/check-out, timestamp recording, roster view, DataTables integration |
| `Tp\StudentEnrollment` | 3.0 hrs | Enrollment flow, AJAX student list (`ajaxData`), Stripe payment session creation |
| `Tp\InternalMessage` | 2.5 hrs | Multi-portal messaging (teacher + parent contexts), attachment handling |
| `Tp\TeacherMessage` | 2.5 hrs | Teacher-specific threads, webcam attachment, send/receive logic |
| `Tp\Reports` | 2.5 hrs | Daily report generation, DataTables, multi-filter queries |
| `Tp\Te` | 2.0 hrs | Teacher auth: login, logout, `forgotPassword`, `newPassword` — full CI4 validation pipeline |
| `Tp\Pa` | 1.5 hrs | Parent auth: login, logout, `forgotPassword`, `newPassword`, prospect redirect |
| `Tp\Pp` | 2.0 hrs | Parent portal: iframe login, `chooseSchool`, `getClass`, dashboard, `changePassword` |
| `Tp\St` | 1.5 hrs | Student assessment stub: `stAssessment`, `baseLineAssessmentListing` |
| `Tp\Incoming` | 1.0 hr | Incoming notification feed, read/unread management |
| `Tp\Ur` (payment) | — | Stripe handoff handled in `Tp\Payment` |

**TP subtotal: ~30 hours**

#### Webhook & Public Controllers (3 controllers · ~5 hours)

| Controller | Hours | Key Complexity |
|---|---|---|
| `Webhook\StripeWebhook` | 3.0 hrs | Signed payload verification, `checkout.session.completed` processing, `stripe_payment` table update, idempotency handling |
| `RegistrationPaperForm` | 1.0 hr | PDF file serving, path resolution, MIME type headers |
| `Home` | 0.5 hrs | Public landing, redirect to TP login |
| `My404` | 0.5 hrs | Custom 404 handler, CI4 error view wiring |

**Public/Webhook subtotal: ~5 hours**

**Phase 4 Total: ~95 hours**

---

## 10. Phase 5 — View Layer Conversion

**Engineering Hours: 75 hours**

219 view files required individual conversion. The view layer was mechanically the largest phase by file count, though per-file effort was generally lower than controllers. The primary risk in this phase was **silent breakage** — a wrong `base_url()` call or missing `old()` helper produces no PHP error, just incorrect UI behaviour that only surfaces during end-to-end testing.

### 10.1 Conversion Categories

**Category A — Include / Partial Files (~60 files · ~12 hours)**
Header scripts, navigation partials, sidebar includes, footer scripts. These files primarily required `base_url()` corrections for asset paths and removal of CI3 `$this->load->view()` references embedded within templates.

**Category B — Standard Form Views (~80 files · ~27 hours)**
Login forms, add/edit forms, profile forms, password reset forms. These required the highest per-file attention: every `set_value()` replaced with `old()`, every `form_error()` replaced with a validation error variable passed from the controller, every flash message updated to `session()->getFlashdata()`. Form action URLs verified against CI4 route definitions.

**Category C — List / DataTables Views (~50 files · ~17 hours)**
Index views with DataTables integration. Primary work: `base_url()` normalisation for JavaScript asset paths, DataTables AJAX endpoint URL correction (from CI3 convention-based URLs to CI4 explicit routes), column definition verification.

**Category D — Dashboard & Complex Views (~29 files · ~19 hours)**
Dashboard views, roster views, assessment views, lesson planning views, calendar views. These views contained embedded JavaScript with hardcoded URL paths, CI3-specific PHP calls mixed into template logic, and complex conditional rendering tied to session state. Each required careful review of the PHP logic interspersed with HTML.

### 10.2 Common Conversion Operations

| CI3 View Pattern | CI4 Replacement | Files Affected |
|---|---|---|
| `$this->load->view('path')` | `<?= view('path') ?>` | All 219 |
| `$this->session->flashdata('x')` | `<?= session()->getFlashdata('x') ?>` | ~110 |
| `$this->config->item('base_url')` | `<?= base_url() ?>` | All 219 |
| `set_value('field')` | `<?= old('field') ?>` | ~80 |
| `form_error('field')` | `<?= $validation->getError('field') ?? '' ?>` | ~80 |
| `base_url('assets/...')` | `<?= base_url('assets/...') ?>` | All 219 |
| `$this->uri->segment(n)` | Controller-passed variable | ~15 |

### 10.3 jQuery AJAX → fetch() Conversion (~30 calls across view files)

All inline JavaScript AJAX calls within view files were converted from jQuery patterns to native `fetch()`. This was necessary because the previous AJAX calls relied on CI3 URL conventions that no longer applied.

**Before (CI3):**
```javascript
$.get(base_url + 'tp/ur/getClass/' + schoolId, function(data) {
    $('#class-select').html(data);
});
```

**After (CI4):**
```javascript
fetch(`${baseUrl}tp/ur/getClass/${schoolId}`)
    .then(response => response.json())
    .then(data => {
        document.getElementById('class-select').innerHTML = data.html;
    });
```

Response contracts were verified: CI4 controllers were updated to return `$this->response->setJSON(...)` where CI3 had returned raw HTML strings — or vice versa — to maintain the existing AJAX contract.

**Phase 5 Total: ~75 hours**

---

## 11. Phase 6 — Routing Architecture & Filter System

**Engineering Hours: 15 hours**

### 11.1 Route Architecture (8 hours)

CI3 used convention-based routing: a URL like `/admin/students/edit/5` automatically mapped to `Admin/Students::edit(5)` without any explicit declaration. CI4 requires all routes to be explicitly registered in `app/Config/Routes.php`.

This phase involved reading every controller's public methods, cross-referencing them against the CI3 application routes, and registering each route explicitly with the correct HTTP verb, parameter constraints, and route group:

```php
// Admin route group
$routes->group('admin', ['namespace' => 'App\Controllers\Admin'], function ($routes) {
    $routes->get('home/dashboard', 'Home::dashboard');
    $routes->get('students', 'Students::index');
    $routes->post('students/add', 'Students::add');
    $routes->get('students/edit/(:num)', 'Students::edit/$1');
    // ... all admin routes
});

// TP route group
$routes->group('tp', ['namespace' => 'App\Controllers\Tp'], function ($routes) {
    $routes->get('te/login', 'Te::login');
    $routes->post('te/login', 'Te::login');
    $routes->get('te/logout', 'Te::logout');
    // ... all TP routes
});
```

Route parameter constraints (`:num`, `:any`, `:alpha`) were applied based on actual parameter usage in controller methods — not assumed. This prevented a class of routing vulnerabilities where unexpected parameter types could reach controller logic.

### 11.2 CI4 Filter System (7 hours)

CI3 relied on inline auth checks at the start of every protected controller method:

```php
// CI3 — inline check in every method
public function index() {
    $this->securities->sessionExistRedirect('te');
    // ... method body
}
```

This pattern was eliminated entirely. CI4 Filters were designed as a clean replacement — a single filter class handles the auth check for an entire route group, enforced before the controller is instantiated:

**`app/Filters/TeacherAuthFilter.php`:**
```php
public function before(RequestInterface $request, $arguments = null) {
    if (!session()->has('te_user_id')) {
        return redirect()->to(base_url('tp/te/login'));
    }
}
```

**`app/Config/Filters.php`:**
```php
public array $filters = [
    'teAuth' => ['before' => ['tp/ur/*', 'tp/quests/*', 'tp/rosters/*', 'tp/reports/*']],
    'paAuth' => ['before' => ['tp/pa/dashboard', 'tp/studentEnrollment/*']],
    'ppAuth' => ['before' => ['tp/pp/dashboard', 'tp/pp/chooseSchool', 'tp/pp/getClass']],
    'adminAuth' => ['before' => ['admin/home/*', 'admin/students/*', 'admin/teachers/*', ...]],
];
```

Five filter classes were written and registered: `TeacherAuthFilter`, `ParentAuthFilter`, `ParentPortalAuthFilter`, `AdminAuthFilter`, and `SchoolOwnerAuthFilter`. Each filter's redirect target and session key was verified against CI3 behaviour.

---

## 12. Phase 7 — Payment Gateway Rebuild

**Engineering Hours: 28 hours**

The Stripe integration required the most significant architectural change of the entire migration — not because of CI4 conversion requirements, but because the legacy implementation used the **Stripe Charges API**, which Stripe formally deprecated in favour of Payment Intents and Checkout Sessions. Migrating to CI4 while keeping the deprecated Charges integration would have deferred a critical problem; the integration was rebuilt in full.

### 12.1 Legacy Integration Analysis (4 hours)

The CI3 Stripe implementation was audited to document:
- All API calls made and their parameters
- The `stripe_payment` table schema and all write operations
- The enrollment status update logic triggered by payment completion
- All error handling and redirect flows
- The admin Cash/Cheque payment recording flow (which does not use Stripe)

### 12.2 Checkout Session Architecture Design (5 hours)

The new integration was designed around Stripe Checkout Sessions:

```
Parent submits enrollment → Tp\Payment::createSession()
    → Stripe::Session::create(['line_items' => [...], 'success_url', 'cancel_url'])
    → Redirect to Stripe-hosted payment page

Parent completes payment → Stripe sends POST /webhook/stripe
    → Webhook\StripeWebhook::index()
    → Verify signature: \Stripe\Webhook::constructEvent($payload, $sigHeader, $secret)
    → Process 'checkout.session.completed' event
    → Update stripe_payment table
    → Update enrollment status
```

### 12.3 `EnrollmentStripeHelper` Library (6 hours)

A dedicated library class was written to encapsulate all Stripe business logic, removing it from the controller layer:

- `createCheckoutSession(array $enrollmentData): Session`
- `recordPayment(Session $session): void` — writes to `stripe_payment`
- `updateEnrollmentStatus(int $enrollmentId, string $status): void`
- `getSessionById(string $sessionId): Session`

### 12.4 Webhook Handler (7 hours)

`App\Controllers\Webhook\StripeWebhook` was engineered with:

- Raw payload capture (`file_get_contents('php://input')`) — required by Stripe signature verification
- CSRF filter exclusion for the webhook route (CSRF tokens cannot be sent by Stripe)
- `\Stripe\Webhook::constructEvent()` with `whsec_` signing secret from `Config\Stripe`
- Idempotency handling: `stripe_payment` table checked for existing `session_id` before writing
- Event type routing: only `checkout.session.completed` processed; all others return `200 OK` without action
- Error logging for signature verification failures

### 12.5 Config & `.env` Setup (3 hours)

All Stripe credentials wired through `Config\Stripe` class reading from `.env`:

```
stripe.testMode = true
stripe.secretKey = sk_test_...
stripe.publishableKey = pk_test_...
stripe.webhookSecret = whsec_...
```

Test mode and live mode keys are interchangeable without code changes — only `.env` values need updating for production deployment.

### 12.6 Admin Payment Flow (3 hours)

The admin Cash/Cheque payment recording flow — which does not involve Stripe — was migrated independently. Admin users can manually record payments, which writes directly to `stripe_payment` with `payment_type = 'cash'` or `'cheque'` and updates enrollment status.

**Phase 7 Total: 28 hours**

---

## 13. Phase 8 — Security Architecture & Authentication

**Engineering Hours: 18 hours**

### 13.1 SecuritiesModel Migration (5 hours)

`SecuritiesModel` was the most critical model in the application — it underpins authentication, session management, and role validation for all four user portals. Its migration required exceptional care.

Key methods migrated:
- `authenticateLogin(string $portal, array $credentials): array|false` — validates credentials against `users`, `user_roles`, and `user_login_details` tables, with portal-specific role checking via `CmmConstants` role IDs.
- `sessionExistRedirect(string $portal): ?RedirectResponse` — in CI3 this was a void method that called `redirect()` directly; in CI4 it must return a `RedirectResponse` or `null`, and the calling controller must `return` the result.
- `allowedRoles(array $roles): true|RedirectResponse` — same return-type pattern change applied.
- `avoid_mysql_injection(string $value): string` — CI3 manual sanitisation preserved for backward compatibility.
- `sanitize(array $data): array` — recursive sanitisation preserved exactly.
- `paLogout()`, `ppLogout()`, `teLogout()`, `adminLogout()` — portal-specific session destruction methods.

### 13.2 CSRF Configuration (2 hours)

CI4's CSRF protection was enabled globally in `app/Config/Security.php`. The Stripe webhook endpoint (`POST /webhook/stripe`) required explicit CSRF filter exclusion — Stripe cannot include CSRF tokens in webhook POST requests. This was handled by excluding the route from the CSRF filter in `app/Config/Filters.php`.

### 13.3 Input Sanitisation Audit (4 hours)

Every `$this->request->getPost()` call in the migrated controllers was audited for:
- Appropriate type filtering applied where integer or boolean types were expected
- Sanitisation through `SecuritiesModel::sanitize()` where the CI3 code had `$this->securities->sanitize()`
- No raw SQL string interpolation with user input (all query builder `where()` calls use parameterised binding)

### 13.4 Session Security Configuration (3 hours)

CI4 database-backed sessions were configured to use the existing `ci_sessions` table. Session cookie parameters were set:
- `$cookieSameSite = 'Lax'` — CSRF protection via SameSite attribute
- `$cookieSecure = true` — production HTTPS enforcement
- `$cookieHTTPOnly = true` — JavaScript cannot access session cookie
- Session regeneration on login enforced in all four portal authentication methods

### 13.5 Role-Based Access Audit (4 hours)

A complete audit was conducted of every `allowedRoles()` call in the CI3 codebase to ensure each was replicated — either as a Filter check or inline controller check — in the CI4 version. Role ID values were verified against `CmmConstants` definitions and cross-checked against the `master_roles` table.

**Phase 8 Total: 18 hours**

---

## 14. Phase 9 — Test Suite Engineering

**Engineering Hours: 40 hours**

The legacy codebase had no test infrastructure. A complete PHPUnit test suite was built from scratch — not as an afterthought, but as a validation instrument used during the migration itself.

### 14.1 Test Infrastructure Setup (5 hours)

- `phpunit.xml.dist` configured with environment constants: `HOMEPATH`, `CONFIGPATH`, `PUBLICPATH`, `app.baseURL`
- `tests/database/` directory established for database integration tests
- `tests/feature/` directory established for HTTP feature tests
- `tests/_support/Http/` support classes for custom request/response helpers
- Test database group configured in `app/Config/Database.php`
- Faker and vfsStream integrated for data generation and file-handling tests

### 14.2 Feature Test Suite (25 hours)

Nine feature test files were written, each targeting a specific system flow:

**`AdminHomeFeatureTest` (3 hours)**
Tests: admin login with valid credentials, admin login with invalid credentials (validation errors), admin session persistence across requests, admin dashboard access when authenticated, admin redirect when unauthenticated. Covers `Admin\Home` controller and `AdminAuthFilter`.

**`AdminModulesGuestFeatureTest` (3 hours)**
Tests: every admin sub-module route returns a redirect (302) for unauthenticated requests. Systematically sweeps all 18 admin module route prefixes. Ensures `AdminAuthFilter` is correctly applied to every route group.

**`TpGuestFeatureTest` (3 hours)**
Tests: all TP portal routes (teacher, parent PA, parent portal PP, unified role UR) return redirect responses for unauthenticated requests. Verifies Filter application across all TP route groups.

**`TpLoginValidationFeatureTest` (3 hours)**
Tests: teacher login with empty fields (validation failure), teacher login with wrong password (auth failure), teacher login with valid credentials (success + session), parent PA login flows (same matrix), password reset email trigger. Verifies CI4 validation integration with flash data output.

**`TpPaymentGuestFeatureTest` (2 hours)**
Tests: Stripe payment initiation route redirects unauthenticated users, enrollment route blocks guest access, `createSession` endpoint requires authenticated parent session.

**`RegistrationPaperFormFeatureTest` (2 hours)**
Tests: PDF files served with correct `Content-Type: application/pdf` header, correct `Content-Disposition`, 404 returned for non-existent form names. Verifies file-serving controller.

**`RouteInventoryGuestTest` (4 hours)**
A comprehensive sweep of all routes registered in `app/Config/Routes.php`. Every route is accessed without authentication and its response code verified: protected routes must return 302 (redirect), public routes must return 200. This test acts as a regression guard for filter misconfigurations.

**`NotFoundFeatureTest` (1 hour)**
Tests: requests to undefined routes return the custom 404 view from `My404`, not CI4's default error page. Response code is 404.

**`ExampleDatabaseTest` (4 hours)**
Tests: database connection to the test group is successful, basic query builder operations return expected result structures, `users` table is queryable, `SecuritiesModel::authenticateLogin()` returns `false` for non-existent credentials (not an exception).

### 14.3 Test Maintenance & Iteration (10 hours)

Tests were written incrementally during the migration, not after. Each failed test identified a real regression in the migrated code. Approximately 40–50 test failures were encountered and resolved during this phase, including:

- Filter not applied to a newly registered route
- Flash data set after redirect (not before) — flash data lost
- Session key mismatch between CI3 and CI4 implementations
- Stripe webhook route not excluded from CSRF filter
- `old()` returning `null` instead of empty string in a view
- Base URL trailing slash inconsistency causing asset 404s in sub-route views

**Phase 9 Total: 40 hours**

---

## 15. Phase 10 — QA, UI Alignment & Bug Resolution

**Engineering Hours: 30 hours**

### 15.1 Systematic End-to-End Testing (15 hours)

Each module was walked through manually by portal, simulating the workflows of each user type:

**Admin portal walkthrough (6 hours):**
Login → Dashboard → each sub-module (add, edit, delete, list, search) → logout. All 18 admin modules tested. Issues found and resolved: 4 DataTables AJAX endpoint URL mismatches, 2 flash message positioning errors, 1 file upload path resolution issue.

**Teacher portal walkthrough (5 hours):**
Login → school/class selection → dashboard → roster check-in/out → quest creation → report viewing → internal message → logout. All TP teacher flows tested.

**Parent portal walkthrough (4 hours):**
Parent login → enrollment list → payment initiation → Stripe test-mode payment → webhook receipt verification → enrollment status update confirmed. Parent Portal (PP) iframe login flow tested separately.

### 15.2 Form Validation Alignment (5 hours)

CI3's `form_error()` function and CI4's validation error system behave differently in how errors are rendered in views. Each form's error display was verified:

- Error messages appear adjacent to the correct fields (not at the top of the form)
- Error messages match the validation rule text from the model `$validationMessages`
- `old()` correctly repopulates all fields after a failed submission (verified for all form types)
- Server-side validation and client-side jQuery Validate rules are consistent

### 15.3 AJAX & DataTables Verification (5 hours)

Every DataTables instance and AJAX endpoint in the application was verified end-to-end:

- DataTables `ajax` URL property points to the correct CI4 route
- Server-side response structure matches what DataTables expects (`draw`, `recordsTotal`, `recordsFiltered`, `data`)
- `fetch()` calls in views receive the correct JSON structure from CI4 controllers
- `Content-Type: application/json` header present on all JSON responses

### 15.4 Asset & URL Verification (5 hours)

All static assets (CSS, JS, images, fonts) were verified to load correctly across all portal views:

- Admin portal assets (`/public/admin/assets/`) — 100% verified
- TP portal assets (`/public/tp/css/`, `/public/tp/js/`) — 100% verified
- ACE Admin theme assets — all paths verified against CI4 `base_url()` output
- Font Awesome, FullCalendar, jQuery UI — CDN and local paths verified
- PDF registration forms — file serving verified for all form variants

**Phase 10 Total: 30 hours**

---

## 16. Phase 11 — Code Review, Refactoring & Documentation

**Engineering Hours: 12 hours**

### 16.1 Code Review (6 hours)

A structured peer review of all migrated code was conducted against a checklist covering:

- All `$allowedFields` arrays are complete and accurate (no missing columns)
- No raw SQL string interpolation with user data anywhere in the codebase
- All redirects use `return redirect()->to(...)` — none missing the `return` keyword
- All controller methods that return JSON use `$this->response->setJSON(...)` consistently
- No CI3 patterns remain in any file (grep-verified across all `.php` files in `app/`)
- All environment variables accessed via `env()`, not `$_ENV` or `getenv()`
- Stripe keys not present in any committed file

### 16.2 Targeted Refactoring (3 hours)

Minor refactoring was applied where the migration had introduced redundancy:
- Duplicate `session()->get('key')` calls in controller methods consolidated
- Model methods that contained identical query logic deduplicated
- `CmmConstants` references verified and standardised across all controllers

### 16.3 Technical Documentation (3 hours)

Produced as part of the engagement deliverables:
- `docs/README.md` — project hub, stack reference, module index
- `docs/ARCHITECTURE.md` — layer structure, routing areas, filter map
- `docs/ENVIRONMENT.md` — complete `.env` variable reference
- `docs/MIGRATION.md` — CI3→CI4 conversion patterns, completed vs remaining items
- `docs/payment-gateway.md` — Stripe integration guide, webhook configuration
- `docs/email-sending.md` — SMTP configuration and troubleshooting

**Phase 11 Total: 12 hours**

---

## 17. System Architecture: Before & After

### Before — CodeIgniter 3

```
┌─────────────────────────────────────────────────────────────────┐
│                        Browser / Client                         │
└──────────────────────────────┬──────────────────────────────────┘
                               │ HTTP Request
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Apache / Nginx Web Server                    │
│                   Document Root: public/index.php                │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                      CodeIgniter 3 Core                          │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │  application/│  │  application/│  │   application/       │  │
│  │  controllers/│  │   models/    │  │      views/          │  │
│  │              │  │              │  │                      │  │
│  │ No namespace │  │  CI_Model    │  │  $this->load->view() │  │
│  │ Global scope │  │  No schema   │  │  $this->session->    │  │
│  │ Manual loads │  │  No fields   │  │  flashdata()         │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  application/config/                                     │   │
│  │  PHP arrays · hardcoded credentials · no .env            │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  PHP 5.x / 7.x · No PSR-4 · No Composer autoload (app code)    │
│  No test infrastructure · Stripe Charges API (deprecated)       │
└──────────────┬───────────────────────────────────────────────────┘
               │
      ┌────────┴────────┐
      │     MySQL       │    ◄── Shared with legacy system
      │  (127+ tables)  │
      └─────────────────┘
```

**Deficiencies:**
- Framework EOL — no security patches
- PHP 8.x incompatible
- No namespace isolation — collision risk
- No PSR standards — not Composer-native for app code
- No dependency injection — tightly coupled throughout
- No automated test coverage
- Stripe Charges API — deprecated, not PCI-optimised
- Credentials partially hardcoded

---

### After — CodeIgniter 4

```
┌─────────────────────────────────────────────────────────────────┐
│                        Browser / Client                         │
└──────────────────────────────┬──────────────────────────────────┘
                               │ HTTPS Request
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Apache / Nginx Web Server                    │
│                   Document Root: public/index.php                │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                      CodeIgniter 4 Core                          │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  app/Config/                                            │    │
│  │  Routes.php (explicit) · Filters.php (auth guards)      │    │
│  │  Stripe.php · Database.php · App.php · Email.php        │    │
│  │  CmmConstants.php · env() driven · no hardcoded secrets │    │
│  └─────────────────────────────────────────────────────────┘    │
│                               │                                  │
│                    Filter Layer (before hook)                    │
│         TeacherAuth · ParentAuth · PPAuth · AdminAuth           │
│                               │                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │app/Controllers│  │ app/Models/  │  │    app/Views/        │  │
│  │              │  │              │  │                      │  │
│  │ App\Controllers│  │ App\Models  │  │  view() · old()      │  │
│  │ \Admin\*     │  │ $table       │  │  base_url()          │  │
│  │ \Tp\*        │  │ $allowedFields│  │  session()->         │  │
│  │ \Webhook\*   │  │ $validationRules│ │  getFlashdata()      │  │
│  │              │  │              │  │                      │  │
│  │ PSR-4 · CI4  │  │ PSR-4 · CI4  │  │  CI4 syntax          │  │
│  │ request/response│ Model · typed│  │  fetch() API         │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
│                                                                  │
│  PHP 8.4 · Full PSR-4 · Composer autoload · Constructor inject  │
│  PHPUnit test suite · Stripe Checkout + Signed Webhooks         │
└──────────┬──────────────────────────────────────┬───────────────┘
           │                                       │
  ┌────────┴────────┐                  ┌───────────┴──────────┐
  │     MySQL       │                  │    Stripe Platform    │
  │  (127+ tables)  │                  │  Checkout Sessions   │
  │  Schema intact  │                  │  Signed Webhooks     │
  └─────────────────┘                  └──────────────────────┘
           │
  ┌────────┴────────┐
  │  PHPUnit Suite  │
  │  9 test files   │
  │  Feature + DB   │
  └─────────────────┘
```

---

## 18. Full Module Inventory

### Admin Module — 18 Sub-modules

| Module | Core Features |
|---|---|
| **Dashboard** | School-wide KPIs, activity summaries, enrollment funnel metrics |
| **Schools** | Multi-school configuration, school categories, staff assignment |
| **Users** | Role-based account management, access levels, login history, password administration |
| **Students** | Complete student records: personal data, siblings, forms, medical notes, behavioral tracking, withdrawal history |
| **Teachers** | Teacher profiles, class assignments, schedule management, school linkage, availability records |
| **Classrooms** | Room configuration, program linking, activity scheduling, capacity management |
| **Enrollment** | Registration pipeline, status tracking, conversion funnel, admin Cash/Cheque payment recording |
| **Prospects** | Tour request management, prospect children, tour notes, program assignment, source and status tracking |
| **Class Roster** | Future class assignment management, roster reporting, DataTables integration |
| **Activities** | School activity CRUD, activity type and program linking, schedule management |
| **Events** | Calendar event management, Google Calendar sync structure, recurring event support |
| **Parent Concerns** | Concern logging, category management, priority assignment, resolution workflow, status tracking |
| **Internal Messages** | Staff-to-staff messaging, file attachment handling, read/unread state, inbox management |
| **Teacher Messages** | Teacher-facing message threads, webcam video attachment support, send/receive management |
| **Email Templates** | Configurable automated email templates, variable placeholder system |
| **Portals** | Announcement, newsletter, document, and notification management scoped per program |
| **Requests** | Operational and support request logging, status management |
| **Withdrawals** | Student withdrawal processing, leaving reason recording, student status updates |

### TP Module — 13 Sub-modules

| Module | Core Features |
|---|---|
| **Teacher Auth (Te)** | Login, logout, forgot password, password reset with email token |
| **Unified Role (Ur)** | Multi-school/class selection, role-based dashboard, JSON feeds, `signin_out` management |
| **Parent Auth (Pa)** | Parent login, logout, forgot/reset password, prospect redirect to enrollment |
| **Parent Portal (Pp)** | Iframe-capable login, multi-school view, parent dashboard, change password |
| **Rosters** | Real-time check-in/check-out with timestamps, class-level roster view, daily summary |
| **Quests** | Montessori lesson planning, assignment creation and management, record-keeping, file attachments |
| **Reports** | Daily activity report generation, progress summaries, multi-filter DataTables |
| **Student Assessment (St)** | Baseline assessments (BA), Montessori RA record-keeping and progress tracking |
| **Student Enrollment** | Registration flow, AJAX student list, Stripe Checkout Session creation and handoff |
| **Payment** | Stripe Checkout for enrollment and registration fees, payment confirmation handling |
| **Internal Messages** | Parent/teacher internal messaging with file attachments, read/unread tracking |
| **Teacher Messages** | Teacher-to-teacher message threads, webcam video attachment support |
| **Incoming** | Incoming notification and message feeds, read state management |

### Public / System Controllers

| Controller | Function |
|---|---|
| **Home** | Public landing — redirects authenticated users to their portal, guests to teacher login |
| **RegistrationPaperForm** | Serves PDF registration forms with correct MIME headers from `public/registration_paper_form/` |
| **Stripe Webhook** | Processes `checkout.session.completed` events; updates `stripe_payment` and enrollment status |
| **My404** | Custom 404 handler returning the application error view, not CI4's default |

---

## 19. Database Schema Analysis

All 127+ production tables were preserved without alteration. Full schema analysis was conducted to produce accurate `$allowedFields`, `$primaryKey`, and `$useTimestamps` declarations for all 131+ models.

| Domain | Table Count | Representative Tables |
|---|---|---|
| Users, Roles & Access Control | 12 | `users`, `user_roles`, `access_levels`, `master_roles`, `master_sub_roles`, `user_login_details`, `user_media`, `user_addresss`, `user_google_authorization`, `ci_sessions` |
| Schools & Organisational Structure | 3 | `schools`, `school_category`, `school_staff` |
| Academic Programmes & Classrooms | 12 | `programs`, `class_rooms`, `class_room_types`, `class_room_activities`, `class_room_programs`, `assignments`, `concepts`, `materials`, `documents`, `medias`, `media_lesson_items`, `monthly_lesson_plan` |
| Student Management | 13 | `students`, `student_types`, `student_class`, `student_class_future`, `student_schedules`, `student_forms`, `student_siblings`, `student_withdraw`, `student_daily_activity`, `student_daily_in_out`, `student_behaviors`, `student_report_notes`, `student_medications` |
| Teacher Management | 5 | `teachers`, `teacher_class`, `teacher_schools`, `teacher_schedules`, `teacher_availability` |
| Activities & Scheduling | 7 | `activity`, `activity_types`, `activity_programs`, `activity_schedules`, `activity_students`, `student_assignment_lessons`, `student_assignments_status` |
| Montessori RA Assessment System | 5 | `ra_students`, `ra_area`, `ra_area_items`, `ra_student_area`, `ra_student_area_item` |
| Baseline Assessment System | 5 | `ba_student`, `ba_area`, `ba_area_questions`, `ba_area_question_types`, `ba_student_answers` |
| Student Development Records | 5 | `student_dr_items`, `student_dr_attachments`, `student_dr_comments`, `dr_items`, `dr_item_types` |
| Enrollment & Prospect Pipeline | 8 | `enrollment`, `enrollment_status`, `prospect_request_tour`, `prospect_request_child`, `prospect_request_tour_notes`, `prospect_request_tour_programs`, `prospect_source`, `prospect_status` |
| Parents & Family | 4 | `parents`, `families`, `family_agreements`, `relation_with_childs` |
| Concerns & Behavioural Tracking | 3 | `concern`, `concern_status`, `concern_category` |
| Messaging & Communication | 8 | `internal_messages`, `internal_message_attachments`, `teacher_message`, `teacher_message_attachments`, `teacher_message_webcam`, `message`, `newsletters`, `lesson_status` |
| Announcements & Notifications | 5 | `admin_announcements`, `admin_announcement_types`, `program_announcements`, `notifications`, `notification_programs` |
| Payments & Finance | 5 | `payment_type`, `stripe_payment`, `tution_rates_programs_details`, `tution_rates_subscription_details`, `sent_email_details` |
| Events & Calendar | 2 | `events`, `event_sync` |
| Email & Automation | 2 | `email_template`, `cron_email_once` |
| Reference / Lookup Data | 17 | `countries`, `states`, `genders`, `ethnicities`, `timezones`, `phone_types`, `categories`, `areas`, `days`, `months`, `leaving_reasons`, `importance_levels`, `emotional_state`, `staff_types`, `staff_positions`, `student_types`, `program_class_types` |
| Miscellaneous | 6 | `requests`, `classroom_roster`, `lunch`, `session`, `ra_students` (extended usage), `concerns` |

---

## 20. Technology Stack Delivered

### Backend

| Component | Technology | Version | Notes |
|---|---|---|---|
| Language | PHP | 8.4 | Fully tested against production runtime |
| Framework | CodeIgniter 4 | ^4.0 | PSR-4, Composer-native |
| Database | MySQL via CI4 Query Builder | — | Schema preserved, no ORM abstraction added |
| Payment SDK | Stripe PHP | ^16.0 | Checkout Sessions + Webhooks |
| Spreadsheet | PhpSpreadsheet | ^5.5 | Excel import/export retained |
| Session | CI4 database-backed | — | Uses existing `ci_sessions` table |
| Autoloading | Composer PSR-4 | — | All app code Composer-managed |
| Environment | `.env` + `env()` | — | No hardcoded credentials |

### Testing

| Tool | Purpose | Version |
|---|---|---|
| PHPUnit | Feature + integration test runner | ^10.5 |
| Faker PHP | Realistic test data generation | ^1.9 |
| vfsStream | Virtual filesystem for upload tests | ^1.6 |

### Frontend (preserved, no upgrades)

| Library | Purpose |
|---|---|
| Bootstrap 3 | Core UI grid and responsive layout |
| ACE Admin Theme | Admin panel visual skin |
| Font Awesome 4.7 | Icon set |
| jQuery + jQuery UI 1.10.3 | DOM manipulation, date pickers, UI widgets |
| jQuery DataTables | Server-side paginated and sortable data grids |
| jQuery Validate | Client-side form validation |
| FullCalendar (daygrid, timegrid, list, interaction) | Event calendar views |
| Moment.js | Date and time parsing, formatting, display |
| Chosen.js | Enhanced multi-select dropdowns |
| Bootbox.js | Confirm / alert / prompt modal dialogs |
| Bootstrap WYSIWYG | Rich text editing |
| DateRangePicker | Date range input component |
| Bootstrap Datepicker + Timepicker | Individual date and time inputs |
| Flot + jQuery Sparkline | Chart and inline graph rendering |
| jQuery Sidr | Sidebar navigation component |
| Mustache / Hogan.js | Client-side template rendering |

### Third-Party Integrations

| Service | Integration | Status |
|---|---|---|
| **Stripe** | PHP SDK v16 — Checkout Sessions, Payment Intents, Signed Webhooks | Rebuilt, production-ready |
| **SMTP Email** | CI4 Email service — configurable protocol, host, port, credentials via `.env` | Migrated, verified |
| **Google Calendar OAuth** | Auth structure preserved, forward-compatible | Structural preservation, full integration deferred per scope |

---

## 21. Engineering Hours Summary

| Phase | Description | Hours |
|---|---|---|
| **Phase 1** | Discovery, Audit & Architecture Planning | 40 hrs |
| **Phase 2** | Project Scaffold & Environment Setup | 15 hrs |
| **Phase 3** | Model Layer Migration (131+ models) | 125 hrs |
| **Phase 4** | Controller Layer Migration (30+ controllers) | 95 hrs |
| **Phase 5** | View Layer Conversion (219 files) | 75 hrs |
| **Phase 6** | Routing Architecture & Filter System | 15 hrs |
| **Phase 7** | Payment Gateway Rebuild (Stripe) | 28 hrs |
| **Phase 8** | Security Architecture & Authentication | 18 hrs |
| **Phase 9** | Test Suite Engineering (9 files, from scratch) | 40 hrs |
| **Phase 10** | QA, UI Alignment & Bug Resolution | 30 hrs |
| **Phase 11** | Code Review, Refactoring & Documentation | 12 hrs |
| | | |
| | **Total Engineering Investment** | **505 hours** |

### Hours by Layer

| Layer | Hours | % of Total |
|---|---|---|
| Planning & Architecture | 40 hrs | 7.9% |
| Infrastructure & Configuration | 15 hrs | 3.0% |
| Data Layer (Models) | 125 hrs | 24.8% |
| Application Layer (Controllers) | 95 hrs | 18.8% |
| Presentation Layer (Views) | 75 hrs | 14.9% |
| Routing & Security | 33 hrs | 6.5% |
| Payment Integration | 28 hrs | 5.5% |
| Testing & QA | 70 hrs | 13.9% |
| Review & Documentation | 24 hrs | 4.7% |
| | | |
| **Total** | **505 hours** | **100%** |

---

## 22. Results & Outcomes

### Technical Outcomes

| Metric | Result |
|---|---|
| Framework | CI3 (end-of-life) → CI4 (actively maintained, PHP 8.x native) |
| PHP compatibility | PHP 8.4 — fully tested against production runtime |
| Models migrated | 131+ — all namespaced, PSR-4 autoloaded, `$allowedFields` declared |
| Controllers migrated | 30+ — all namespaced, CI4 request/response lifecycle |
| View files converted | 219 — all CI4 syntax, `old()`, `base_url()`, `view()` |
| Routes registered | All routes explicitly declared in `app/Config/Routes.php` |
| Auth filters | 5 CI4 Filter classes covering all portal route groups |
| Database schema changes | **None** — 127+ tables preserved exactly, zero DDL executed |
| Production data loss | **Zero** |
| Test files written | 9 PHPUnit feature/integration files |
| Bug resolutions | 40+ regressions identified and resolved during testing |
| Stripe SDK | Rebuilt to v16, Checkout Sessions + Signed Webhooks |
| Security | CSRF protection, signed webhook verification, `$allowedFields`, CI4 Filters |

### Business Outcomes

| Outcome | Detail |
|---|---|
| **Server upgrade unblocked** | PHP 8.4 compatibility removes the blocker on OS-level security updates and hosting infrastructure upgrades |
| **Framework security risk eliminated** | The application no longer runs on an unmaintained, unpatched framework |
| **Maintenance cost trajectory improved** | PSR-4 namespacing, explicit routing, typed config, and dependency injection significantly reduce the cognitive load — and therefore the hourly cost — of future development |
| **Regulatory compliance posture strengthened** | Stripe Checkout + signed Webhooks aligns with current PCI DSS best practices for online payment handling |
| **Release confidence established** | The PHPUnit test suite provides an automated regression check for every future code change |
| **Future development unblocked** | The clean CI4 codebase supports dependency injection, modern PHP 8.x features, and the broader Composer ecosystem — enabling feature development that was not possible on CI3 |
| **Zero user disruption** | The migration was transparent to all active users — no downtime, no retraining, no data migration notice required |

---

## 23. Conclusion

The CMMSchool CI3 → CI4 migration was a large-scale, high-precision engineering engagement. The system's size — 131+ models, 30+ controllers, 219 views, 127+ database tables — combined with its domain specificity (Montessori-specific workflows, multi-role session architecture, live payment processing) placed it firmly in the category of migrations where the cost of error is high and the margin for assumption is low.

Every engineering decision was made against the standard of complete behavioural parity with the legacy system. The production database was treated as immutable throughout. Every migrated component was validated through automated tests before the engagement was considered complete.

The delivered platform now operates on:

- A **supported, actively maintained framework** (CodeIgniter 4) with a published long-term roadmap and regular security releases
- **PHP 8.4** — the current stable PHP runtime, compatible with modern hosting infrastructure
- A **modern Stripe payment integration** using Checkout Sessions and cryptographically signed Webhooks — aligned with Stripe's current best practices and PCI DSS guidance
- A **PHPUnit test suite** built from scratch, providing a regression safety net for every future release cycle
- A **clean, PSR-4 namespaced codebase** with environment-driven configuration, explicit routing, and dependency injection — ready for new feature development without the constraints of legacy technical debt

**Total engineering investment: 505 hours.**
**Production data loss: zero.**
**User disruption: zero.**
**Business logic changes: zero.**

---

*Case study prepared by the Senior Engineering Team.*
*Engagement: CMMSchool CI4 Migration — Fixed Scope.*
*Delivered: March 2026.*