fix enrollment and registration email send

- load global semester helpers consistently and use date-based semester defaults
- fix grading and daily attendance duplicate student/section rows
- keep attendance violations scoped to the current semester by default
- update invoice, refund, discount, payment, and financial aid flows
- add configuration cleanup migrations for duplicate calendar/semester keys
- refresh parent registration/report-card and print request handling
- update related models, services, views, cron notes, and test coverage

.gitea/workflows/deploy.yml

@@ -0,0 +1,189 @@
+name: Deploy to Shared Hosting
+
+on:
+  push:
+    branches:
+      - develop
+  workflow_dispatch:
+    inputs:
+      target:
+        description: 'Deployment target'
+        required: true
+        default: 'production'
+
+jobs:
+  deploy:
+    name: Shared hosting deploy
+    runs-on: ubuntu-latest
+
+    env:
+      DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
+      DEPLOY_PORT: ${{ secrets.DEPLOY_PORT }}
+      DEPLOY_USER: ${{ secrets.DEPLOY_USER }}
+      DEPLOY_APP_PATH: ${{ secrets.DEPLOY_APP_PATH }}
+      DEPLOY_PUBLIC_PATH: ${{ secrets.DEPLOY_PUBLIC_PATH }}
+      DEPLOY_PATH: ${{ secrets.DEPLOY_PATH }}
+      DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
+      DEPLOY_PHP_BIN: ${{ secrets.DEPLOY_PHP_BIN }}
+      DEPLOY_INDEX_REQUIRE: ${{ secrets.DEPLOY_INDEX_REQUIRE }}
+      GITEA_BASE_URL: ${{ secrets.GITEA_BASE_URL }}
+      GITEA_PACKAGE_OWNER: ${{ secrets.GITEA_PACKAGE_OWNER }}
+      GITEA_PACKAGE_USER: ${{ secrets.GITEAPACKAGEUSER }}
+      GITEA_PACKAGE_TOKEN: ${{ secrets.GITEAPACKAGETOKEN }}
+      GIT_SSL_NO_VERIFY: 'true'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        env:
+          GIT_SSL_NO_VERIFY: 'true'
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          extensions: dom, gd, intl, mbstring, mysqli, zip
+          coverage: none
+
+      - name: Validate Composer config
+        run: composer validate --no-check-publish --strict
+
+      - name: Install production dependencies
+        run: composer install --no-dev --no-interaction --prefer-dist --no-progress --optimize-autoloader
+
+      - name: Create deployment artifact
+        run: bash scripts/build-deploy-artifact.sh
+
+      - name: Publish deployment package
+        if: ${{ env.GITEA_PACKAGE_USER != '' && env.GITEA_PACKAGE_TOKEN != '' }}
+        run: |
+          BASE_URL="${GITEA_BASE_URL:-https://192.168.3.80}"
+          PACKAGE_OWNER="${GITEA_PACKAGE_OWNER:-melabidi}"
+          PACKAGE_NAME="alrahma_sunday_school"
+          REF_NAME="${GITHUB_REF_NAME:-manual}"
+          SHORT_SHA="$(printf '%s' "${GITHUB_SHA}" | cut -c1-7)"
+          VERSION="$(printf '%s-%s-%s' "${REF_NAME}" "${GITHUB_RUN_NUMBER}" "${SHORT_SHA}" | sed 's/[^A-Za-z0-9._+-]/-/g')"
+          FILE_NAME="${PACKAGE_NAME}-${VERSION}.tar.gz"
+          PACKAGE_URL="${BASE_URL}/api/packages/${PACKAGE_OWNER}/generic/${PACKAGE_NAME}/${VERSION}/${FILE_NAME}"
+
+          tar -czf "build/${FILE_NAME}" -C build/deploy .
+          echo "Publishing package ${PACKAGE_NAME} ${VERSION}"
+
+          curl --fail-with-body --insecure \
+            --user "${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}" \
+            --upload-file "build/${FILE_NAME}" \
+            "${PACKAGE_URL}"
+
+          echo "Package uploaded: ${PACKAGE_URL}"
+
+      - name: Resolve shared-hosting paths
+        run: |
+          APP_PATH="${DEPLOY_APP_PATH:-${DEPLOY_PATH}}"
+          PUBLIC_PATH="${DEPLOY_PUBLIC_PATH}"
+
+          if [ -z "${APP_PATH}" ]; then
+            echo "Set DEPLOY_APP_PATH (application directory next to public_html)."
+            echo "Example: /home/u280815660/domains/home.alrahmaisgl.org/alrahma"
+            exit 1
+          fi
+
+          if [ -z "${PUBLIC_PATH}" ]; then
+            PUBLIC_PATH="$(dirname "${APP_PATH}")/public_html"
+            echo "DEPLOY_PUBLIC_PATH is not set; using ${PUBLIC_PATH}"
+          fi
+
+          echo "APP_PATH=${APP_PATH}" >> "$GITHUB_ENV"
+          echo "PUBLIC_PATH=${PUBLIC_PATH}" >> "$GITHUB_ENV"
+          echo "SSH_PORT=${DEPLOY_PORT:-65002}" >> "$GITHUB_ENV"
+          echo "PHP_BIN=${DEPLOY_PHP_BIN:-/opt/alt/php85/usr/bin/php}" >> "$GITHUB_ENV"
+          echo "INDEX_REQUIRE=${DEPLOY_INDEX_REQUIRE:-../alrahma/app/Config/Paths.php}" >> "$GITHUB_ENV"
+
+      - name: Configure SSH
+        run: |
+          test -n "${DEPLOY_HOST}"
+          test -n "${DEPLOY_USER}"
+          test -n "${DEPLOY_SSH_KEY}"
+
+          mkdir -p ~/.ssh
+          chmod 700 ~/.ssh
+          printf '%s\n' "${DEPLOY_SSH_KEY}" > ~/.ssh/deploy_key
+          chmod 600 ~/.ssh/deploy_key
+
+          {
+            echo "Host shared-hosting"
+            echo "  HostName ${DEPLOY_HOST}"
+            echo "  User ${DEPLOY_USER}"
+            echo "  Port ${SSH_PORT}"
+            echo "  IdentityFile ~/.ssh/deploy_key"
+            echo "  IdentitiesOnly yes"
+            echo "  StrictHostKeyChecking accept-new"
+            echo "  ServerAliveInterval 30"
+          } > ~/.ssh/config
+          chmod 600 ~/.ssh/config
+
+          ssh-keyscan -p "${SSH_PORT}" "${DEPLOY_HOST}" >> ~/.ssh/known_hosts || true
+
+      - name: Prepare remote directories
+        run: |
+          ssh shared-hosting "mkdir -p \
+            '${APP_PATH}' \
+            '${APP_PATH}/writable/cache' \
+            '${APP_PATH}/writable/logs' \
+            '${APP_PATH}/writable/session' \
+            '${APP_PATH}/writable/uploads' \
+            '${APP_PATH}/writable/debugbar' \
+            '${APP_PATH}/writable/reports' \
+            '${PUBLIC_PATH}'"
+
+      - name: Deploy application files
+        run: |
+          rsync -az --delete \
+            -e ssh \
+            --exclude '.env' \
+            --exclude 'writable/cache/***' \
+            --exclude 'writable/logs/***' \
+            --exclude 'writable/session/***' \
+            --exclude 'writable/uploads/***' \
+            --exclude 'writable/debugbar/***' \
+            --exclude 'writable/reports/***' \
+            build/deploy/ "shared-hosting:${APP_PATH}/"
+
+      - name: Deploy public_html document root
+        run: |
+          rsync -az --delete \
+            -e ssh \
+            --exclude 'uploads/***' \
+            --exclude 'cgi-bin/***' \
+            --exclude '.well-known/***' \
+            --exclude 'error_log' \
+            --exclude 'default.php' \
+            build/deploy/public/ "shared-hosting:${PUBLIC_PATH}/"
+
+      - name: Finalize shared-hosting release
+        run: |
+          ssh shared-hosting "APP_PATH=$(printf '%q' "${APP_PATH}") PUBLIC_PATH=$(printf '%q' "${PUBLIC_PATH}") INDEX_REQUIRE=$(printf '%q' "${INDEX_REQUIRE}") PHP_BIN=$(printf '%q' "${PHP_BIN}") bash -s" <<'REMOTE'
+          set -euo pipefail
+
+          test -f "${PUBLIC_PATH}/index.php"
+          test -d "${APP_PATH}/app"
+          test -d "${APP_PATH}/vendor"
+
+          grep -q "require FCPATH . '" "${PUBLIC_PATH}/index.php"
+          sed -i "s|require FCPATH . '../[^']*app/Config/Paths.php';|require FCPATH . '${INDEX_REQUIRE}';|" "${PUBLIC_PATH}/index.php"
+          grep -F "require FCPATH . '${INDEX_REQUIRE}';" "${PUBLIC_PATH}/index.php"
+
+          chmod 644 "${PUBLIC_PATH}/index.php" "${PUBLIC_PATH}/.htaccess" || true
+          find "${PUBLIC_PATH}" -type d -exec chmod 755 {} +
+          find "${APP_PATH}/writable" -type d -exec chmod 775 {} + || true
+          find "${APP_PATH}/writable" -type f -exec chmod 664 {} + || true
+
+          if [ -x "${PHP_BIN}" ]; then
+            (cd "${APP_PATH}" && "${PHP_BIN}" spark cache:clear) || true
+          else
+            (cd "${APP_PATH}" && php spark cache:clear) || true
+          fi
+
+          echo "Deployed app to ${APP_PATH}"
+          echo "Deployed document root to ${PUBLIC_PATH}"
+          echo "index.php requires ${INDEX_REQUIRE}"
+          REMOTE

.gitea/workflows/tests.yml

@@ -0,0 +1,173 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - develop
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  phpunit:
+    name: PHPUnit
+    runs-on: ubuntu-latest
+
+    services:
+      mysql:
+        image: mariadb:10.11
+        env:
+          MYSQL_ROOT_PASSWORD: root
+          MYSQL_DATABASE: alrahma_test
+          MYSQL_USER: alrahma
+          MYSQL_PASSWORD: alrahma
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="mariadb-admin ping -h 127.0.0.1 -uroot -proot"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=10
+
+    env:
+      GIT_SSL_NO_VERIFY: 'true'
+      CI_ENVIRONMENT: testing
+      TEST_DB_HOST: mysql
+      TEST_DB_PORT: 3306
+      TEST_DB_NAME: alrahma_test
+      TEST_DB_USER: alrahma
+      TEST_DB_PASSWORD: alrahma
+      database.tests.hostname: mysql
+      database.tests.database: alrahma_test
+      database.tests.username: alrahma
+      database.tests.password: alrahma
+      database.tests.DBDriver: MySQLi
+      database.tests.DBPrefix: ''
+      database.tests.port: 3306
+      JWT_SECRET: test-secret-for-ci
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        env:
+          GIT_SSL_NO_VERIFY: 'true'
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          extensions: dom, gd, intl, mbstring, mysqli, zip
+          coverage: xdebug
+
+      - name: Validate Composer config
+        run: composer validate --no-check-publish --strict
+
+      - name: Install dependencies
+        run: composer install --no-interaction --prefer-dist --no-progress
+
+      - name: Prepare writable directories
+        run: |
+          mkdir -p \
+            writable/cache/testing \
+            writable/logs \
+            writable/session \
+            writable/uploads \
+            writable/debugbar
+          chown -R "$(id -u):$(id -g)" writable || true
+          chmod -R u+rwX,g+rwX writable
+
+      - name: Verify writable cache
+        run: |
+          test -d writable/cache/testing
+          test -w writable/cache/testing
+          touch writable/cache/testing/.ci-write-test
+          rm writable/cache/testing/.ci-write-test
+
+      - name: Verify database configuration
+        run: |
+          php -d variables_order=EGPCS -r '
+            define("FCPATH", __DIR__ . "/public/");
+            define("ENVIRONMENT", getenv("CI_ENVIRONMENT") ?: "production");
+            require "app/Config/Paths.php";
+            $paths = new Config\Paths();
+            require $paths->systemDirectory . "/Boot.php";
+            CodeIgniter\Boot::bootConsole($paths);
+
+            $database = config("Database");
+            $dbConfig = $database->{$database->defaultGroup};
+
+            echo "Environment: " . ENVIRONMENT . PHP_EOL;
+            echo "DB group: " . $database->defaultGroup . PHP_EOL;
+            echo "DB host: " . $dbConfig["hostname"] . PHP_EOL;
+            echo "DB port: " . $dbConfig["port"] . PHP_EOL;
+            echo "DB name: " . $dbConfig["database"] . PHP_EOL;
+          '
+
+      - name: Wait for MariaDB
+        run: |
+          for attempt in $(seq 1 30); do
+            php -r '
+              mysqli_report(MYSQLI_REPORT_OFF);
+              $db = @new mysqli(
+                  getenv("TEST_DB_HOST"),
+                  getenv("TEST_DB_USER"),
+                  getenv("TEST_DB_PASSWORD"),
+                  getenv("TEST_DB_NAME"),
+                  (int) getenv("TEST_DB_PORT")
+              );
+
+              exit($db->connect_errno === 0 ? 0 : 1);
+            ' && break
+
+            echo "Waiting for MariaDB, attempt ${attempt}/30"
+            sleep 2
+          done
+
+          php -r '
+            mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+
+            new mysqli(
+                getenv("TEST_DB_HOST"),
+                getenv("TEST_DB_USER"),
+                getenv("TEST_DB_PASSWORD"),
+                getenv("TEST_DB_NAME"),
+                (int) getenv("TEST_DB_PORT")
+            );
+
+            echo "MariaDB connection successful\n";
+          '
+
+      - name: Import baseline schema
+        run: php tests/_support/import_baseline.php Database_Dump/u280815660_school_12072025
+
+      - name: Run database migrations
+        run: |
+          php -d variables_order=EGPCS spark migrate --all --no-interaction
+          php -r '
+            mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+
+            $db = new mysqli(
+                getenv("TEST_DB_HOST"),
+                getenv("TEST_DB_USER"),
+                getenv("TEST_DB_PASSWORD"),
+                getenv("TEST_DB_NAME"),
+                (int) getenv("TEST_DB_PORT")
+            );
+
+            $tables = [];
+            $result = $db->query("SHOW TABLES");
+            while ($row = $result->fetch_array(MYSQLI_NUM)) {
+                $tables[$row[0]] = true;
+            }
+
+            foreach (["users", "students", "attendance_data"] as $table) {
+                if (!isset($tables[$table])) {
+                    fwrite(STDERR, "Migration schema missing required table: {$table}\n");
+                    exit(1);
+                }
+            }
+
+            echo "Migration schema verified\n";
+          '
+
+      - name: Run tests
+        run: composer test

.gitignore

@@ -1,6 +1,12 @@
 .env
 .env.*
 !.env.example
+/env
+/env.production
+/env.backup
+/env_for_test*
+/environment.txt
+/env\ (copy\ 1)
 
 /vendor/
 /node_modules/
@@ -47,6 +53,7 @@ Thumbs.db
 
 /coverage/
 /build/
+/build.tar.gz
 /builds
 /phpunit.xml.cache
 /.phpunit.result.cache

README.md

@@ -1,4 +1,11 @@
 # Current Software Architecture of `alrahma_sunday_school`
+
+<p>
+  <a href="/melabidi/alrahma_sunday_school/actions">
+    <img src="https://img.shields.io/badge/Deploy-Hosting%20Server-2ea44f?style=for-the-badge" alt="Deploy to Hosting Server"/>
+  </a>
+</p>
+
 <p align="center">
   <img src="/image/system_architecture.png" alt="software-architecture" width="1000"/>
 </p>
@@ -55,7 +62,7 @@ Problems with it can be raised on our forum, or as issues in the main repository
 
 ## Server Requirements
 
-PHP version 8.1 or higher is required, with the following extensions installed:
+PHP version 8.5 or higher is required, with the following extensions installed:
 
 - [intl](http://php.net/manual/en/intl.requirements.php)
 - [mbstring](http://php.net/manual/en/mbstring.installation.php)
@@ -64,7 +71,7 @@ PHP version 8.1 or higher is required, with the following extensions installed:
 > - The end of life date for PHP 7.4 was November 28, 2022.
 > - The end of life date for PHP 8.0 was November 26, 2023.
 > - If you are still using PHP 7.4 or 8.0, you should upgrade immediately.
-> - The end of life date for PHP 8.1 will be December 31, 2025.
+> - The end of life date for PHP 8.1 was December 31, 2025.
 
 Additionally, make sure that the following extensions are enabled in your PHP:
 

README.txt

@@ -1,32 +0,0 @@
-Al Rahma Sunday School — API Docs Pack
-=================================================
-Generated: 2025-11-07T21:01:43.815073
-
-WHAT'S INCLUDED
----------------
-- app/Controllers/Api/*.php (API controllers)
-- app/Controllers/{DocsController, ApiDocsController}
-- app/Filters/ApiDocsAuthFilter.php
-- app/Views/docs/{index.php, swagger_ui.php, swagger_ui_public.php}
-- public/docs/openapi/*.yaml (separate specs + master.yaml)
-- ROUTES_SNIPPET.php  (add to app/Config/Routes.php)
-- FILTERS_SNIPPET.php (add alias to app/Config/Filters.php)
-
-INSTALL
--------
-1) Unzip into your project root.
-2) Merge routes:
-   - Open app/Config/Routes.php and paste the contents of ROUTES_SNIPPET.php
-3) Add filter alias:
-   - Open app/Config/Filters.php and add the 'apiDocsAuth' alias from FILTERS_SNIPPET.php
-4) Ensure your Models exist and match the controller expectations.
-5) Set JWT secret in .env:
-   JWT_SECRET=your_super_secret_key
-6) Visit:
-   - /docs          (landing)
-   - /docs/api      (secured, admin only)
-   - /docs/api/public (public read-only)
-7) API base path:
-   - /api/v1/... (see YAMLs for full paths)
-
-Enjoy!

app/Commands/ConfigUpdate.php

@@ -98,10 +98,9 @@ class ConfigUpdate extends BaseCommand
             return true; // no-op is success
         }
 
-        CLI::write("Set semester = Spring" . ($dry ? ' [DRY]' : ''), 'light_gray');
-        if ($dry) return true;
+        CLI::write('Semester is derived from fall_semester_start and spring_semester_start; no config row is updated.', 'yellow');
 
-        return (bool) $this->configModel->setConfigValueByKey('semester', 'Spring');
+        return true;
     }
 
     protected function taskSetSemesterFall(bool $dry, DateTimeZone $tz): bool
@@ -118,10 +117,9 @@ class ConfigUpdate extends BaseCommand
             return true;
         }
 
-        CLI::write("Set semester = Fall" . ($dry ? ' [DRY]' : ''), 'light_gray');
-        if ($dry) return true;
+        CLI::write('Semester is derived from fall_semester_start and spring_semester_start; no config row is updated.', 'yellow');
 
-        return (bool) $this->configModel->setConfigValueByKey('semester', 'Fall');
+        return true;
     }
 
     public function run(array $params)

app/Commands/EnrollmentCloseoutReport.php

@@ -0,0 +1,323 @@
+<?php
+
+namespace App\Commands;
+
+use CodeIgniter\CLI\BaseCommand;
+use CodeIgniter\CLI\CLI;
+use CodeIgniter\Database\BaseConnection;
+
+class EnrollmentCloseoutReport extends BaseCommand
+{
+    protected $group = 'Registration';
+    protected $name = 'registration:closeout-report';
+    protected $description = 'Generate end-of-registration reconciliation and closeout exception lists.';
+    protected $usage = 'php spark registration:closeout-report [--school-year=2026-2027] [--json] [--export=/tmp/registration-closeout.csv]';
+    protected $options = [
+        '--school-year' => 'Target school year name. Defaults to the active/current configured year.',
+        '--json' => 'Print machine-readable JSON.',
+        '--export' => 'Write closeout exception rows to a CSV file.',
+    ];
+
+    private BaseConnection $db;
+
+    public function run(array $params)
+    {
+        $this->db = \Config\Database::connect();
+        $schoolYear = trim((string) (CLI::getOption('school-year') ?? ''));
+        if ($schoolYear === '') {
+            $schoolYear = $this->currentSchoolYear();
+        }
+
+        $report = $this->buildReport($schoolYear);
+        $exportPath = $this->optionValue('export');
+        if ($exportPath !== '') {
+            $this->writeCsv($exportPath, $report['exceptions']);
+            $report['export_path'] = $exportPath;
+        }
+
+        if (CLI::getOption('json') !== null) {
+            CLI::write(json_encode($report, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
+            return;
+        }
+
+        $this->printReport($report);
+    }
+
+    private function buildReport(string $schoolYear): array
+    {
+        $previousYear = $this->previousSchoolYearName($schoolYear);
+        $expected = $this->expectedReturningStudents($previousYear);
+        $enrolled = $this->enrolledStudents($schoolYear);
+        $unsubmitted = $this->unsubmittedReturningStudents($schoolYear, $previousYear);
+        $pendingEnrollments = $this->pendingEnrollments($schoolYear);
+        $unresolvedFlags = $this->unresolvedFlags($schoolYear);
+        $failedEmails = $this->failedEmails($schoolYear);
+
+        $exceptions = array_merge(
+            $this->exceptionRows('unsubmitted_returning_student', $unsubmitted),
+            $this->exceptionRows('pending_enrollment', $pendingEnrollments),
+            $this->exceptionRows('unresolved_flag', $unresolvedFlags),
+            $this->exceptionRows('failed_email', $failedEmails)
+        );
+
+        $summary = [
+            'expected_returning_students' => count($expected),
+            'students_with_target_year_enrollment' => count($enrolled),
+            'unsubmitted_returning_students' => count($unsubmitted),
+            'pending_enrollments' => count($pendingEnrollments),
+            'unresolved_flags' => count($unresolvedFlags),
+            'failed_emails' => count($failedEmails),
+            'closeout_exception_total' => count($exceptions),
+        ];
+
+        return [
+            'school_year' => $schoolYear,
+            'source_school_year' => $previousYear,
+            'generated_at' => date('Y-m-d H:i:s'),
+            'ready_to_close' => $summary['closeout_exception_total'] === 0,
+            'summary' => $summary,
+            'exceptions' => $exceptions,
+        ];
+    }
+
+    private function expectedReturningStudents(?string $previousYear): array
+    {
+        if ($previousYear === null || ! $this->db->tableExists('student_class')) {
+            return [];
+        }
+
+        return $this->db->table('student_class sc')
+            ->select('DISTINCT sc.student_id', false)
+            ->where('sc.school_year', $previousYear)
+            ->get()
+            ->getResultArray();
+    }
+
+    private function enrolledStudents(string $schoolYear): array
+    {
+        if (! $this->db->tableExists('enrollments')) {
+            return [];
+        }
+
+        return $this->db->table('enrollments')
+            ->select('DISTINCT student_id', false)
+            ->where('school_year', $schoolYear)
+            ->get()
+            ->getResultArray();
+    }
+
+    private function unsubmittedReturningStudents(string $schoolYear, ?string $previousYear): array
+    {
+        if ($previousYear === null || ! $this->db->tableExists('student_class') || ! $this->db->tableExists('enrollments')) {
+            return [];
+        }
+
+        $join = 'e.student_id = sc.student_id AND e.school_year = ' . $this->db->escape($schoolYear);
+
+        return $this->db->table('student_class sc')
+            ->select('sc.student_id, s.firstname, s.lastname, s.school_id')
+            ->select('e.id AS enrollment_id, e.enrollment_status, e.admission_status, e.registration_submitted_at')
+            ->join('students s', 's.id = sc.student_id', 'left')
+            ->join('enrollments e', $join, 'left', false)
+            ->where('sc.school_year', $previousYear)
+            ->groupStart()
+                ->where('e.id IS NULL')
+                ->orWhere('e.registration_submitted_at IS NULL', null, false)
+            ->groupEnd()
+            ->groupBy('sc.student_id, s.firstname, s.lastname, s.school_id, e.id, e.enrollment_status, e.admission_status, e.registration_submitted_at')
+            ->orderBy('s.lastname', 'ASC')
+            ->orderBy('s.firstname', 'ASC')
+            ->get()
+            ->getResultArray();
+    }
+
+    private function pendingEnrollments(string $schoolYear): array
+    {
+        if (! $this->db->tableExists('enrollments')) {
+            return [];
+        }
+
+        return $this->db->table('enrollments e')
+            ->select('e.student_id, e.id AS enrollment_id, e.enrollment_status, e.admission_status, e.registration_submitted_at, e.registration_confirmed_at')
+            ->select('s.firstname, s.lastname, s.school_id')
+            ->join('students s', 's.id = e.student_id', 'left')
+            ->where('e.school_year', $schoolYear)
+            ->groupStart()
+                ->where('e.enrollment_status', 'admission under review')
+                ->orWhere('e.admission_status', 'pending')
+                ->orWhere('e.registration_confirmed_at IS NULL', null, false)
+            ->groupEnd()
+            ->orderBy('s.lastname', 'ASC')
+            ->orderBy('s.firstname', 'ASC')
+            ->get()
+            ->getResultArray();
+    }
+
+    private function unresolvedFlags(string $schoolYear): array
+    {
+        if (! $this->db->tableExists('enrollment_flags')) {
+            return [];
+        }
+
+        return $this->db->table('enrollment_flags ef')
+            ->select('ef.id AS flag_id, ef.student_id, ef.flag_type, ef.priority, ef.created_at')
+            ->select('s.firstname, s.lastname, s.school_id')
+            ->join('students s', 's.id = ef.student_id', 'left')
+            ->where('ef.school_year', $schoolYear)
+            ->where('ef.status', 'open')
+            ->orderBy('ef.priority', 'DESC')
+            ->orderBy('ef.created_at', 'ASC')
+            ->get()
+            ->getResultArray();
+    }
+
+    private function failedEmails(string $schoolYear): array
+    {
+        if (! $this->db->tableExists('enrollment_email_records')) {
+            return [];
+        }
+
+        return $this->db->table('enrollment_email_records')
+            ->select('id AS email_record_id, parent_user_id, recipient_addresses_json, delivery_status, failure_reason, retry_count, updated_at')
+            ->where('school_year', $schoolYear)
+            ->where('delivery_status', 'failed')
+            ->orderBy('updated_at', 'DESC')
+            ->get()
+            ->getResultArray();
+    }
+
+    private function exceptionRows(string $type, array $rows): array
+    {
+        $exceptions = [];
+        foreach ($rows as $row) {
+            $studentName = trim((string) ($row['firstname'] ?? '') . ' ' . (string) ($row['lastname'] ?? ''));
+            $exceptions[] = [
+                'type' => $type,
+                'student_id' => $row['student_id'] ?? '',
+                'student_name' => $studentName,
+                'school_id' => $row['school_id'] ?? '',
+                'reference_id' => $row['enrollment_id'] ?? $row['flag_id'] ?? $row['email_record_id'] ?? '',
+                'status' => $row['enrollment_status'] ?? $row['flag_type'] ?? $row['delivery_status'] ?? '',
+                'detail' => $this->exceptionDetail($type, $row),
+            ];
+        }
+
+        return $exceptions;
+    }
+
+    private function exceptionDetail(string $type, array $row): string
+    {
+        return match ($type) {
+            'unsubmitted_returning_student' => empty($row['enrollment_id'])
+                ? 'No target-year enrollment exists.'
+                : 'Target-year enrollment exists but registration has not been submitted.',
+            'pending_enrollment' => 'Enrollment status: ' . (string) ($row['enrollment_status'] ?? '') . '; admission status: ' . (string) ($row['admission_status'] ?? ''),
+            'unresolved_flag' => 'Open flag priority: ' . (string) ($row['priority'] ?? ''),
+            'failed_email' => 'Retry count: ' . (int) ($row['retry_count'] ?? 0) . '; reason: ' . (string) ($row['failure_reason'] ?? ''),
+            default => '',
+        };
+    }
+
+    private function writeCsv(string $path, array $rows): void
+    {
+        $directory = dirname($path);
+        if ($directory !== '' && $directory !== '.' && ! is_dir($directory)) {
+            throw new \RuntimeException('Export directory does not exist: ' . $directory);
+        }
+
+        $handle = fopen($path, 'wb');
+        if ($handle === false) {
+            throw new \RuntimeException('Unable to write export file: ' . $path);
+        }
+
+        fputcsv($handle, ['type', 'student_id', 'student_name', 'school_id', 'reference_id', 'status', 'detail']);
+        foreach ($rows as $row) {
+            fputcsv($handle, [
+                $row['type'] ?? '',
+                $row['student_id'] ?? '',
+                $row['student_name'] ?? '',
+                $row['school_id'] ?? '',
+                $row['reference_id'] ?? '',
+                $row['status'] ?? '',
+                $row['detail'] ?? '',
+            ]);
+        }
+
+        fclose($handle);
+    }
+
+    private function optionValue(string $name): string
+    {
+        $value = CLI::getOption($name);
+        if (is_string($value) && trim($value) !== '') {
+            return trim($value);
+        }
+
+        $argv = $_SERVER['argv'] ?? [];
+        $long = '--' . $name;
+        foreach ($argv as $index => $arg) {
+            if (str_starts_with((string) $arg, $long . '=')) {
+                return trim(substr((string) $arg, strlen($long) + 1));
+            }
+            if ($arg === $long && isset($argv[$index + 1]) && ! str_starts_with((string) $argv[$index + 1], '--')) {
+                return trim((string) $argv[$index + 1]);
+            }
+        }
+
+        return '';
+    }
+
+    private function currentSchoolYear(): string
+    {
+        if ($this->db->tableExists('school_years')) {
+            $row = $this->db->table('school_years')
+                ->select('name')
+                ->where('status', 'active')
+                ->orderBy('id', 'DESC')
+                ->limit(1)
+                ->get()
+                ->getRowArray();
+            if (! empty($row['name'])) {
+                return (string) $row['name'];
+            }
+        }
+
+        if ($this->db->tableExists('configuration')) {
+            $row = $this->db->table('configuration')
+                ->select('config_value')
+                ->where('config_key', 'school_year')
+                ->limit(1)
+                ->get()
+                ->getRowArray();
+            if (! empty($row['config_value'])) {
+                return (string) $row['config_value'];
+            }
+        }
+
+        return '';
+    }
+
+    private function previousSchoolYearName(string $schoolYear): ?string
+    {
+        return preg_match('/^(\d{4})-(\d{4})$/', trim($schoolYear), $matches)
+            ? ((int) $matches[1] - 1) . '-' . ((int) $matches[2] - 1)
+            : null;
+    }
+
+    private function printReport(array $report): void
+    {
+        CLI::write('Registration Closeout Report: ' . (string) ($report['school_year'] ?? ''), ($report['ready_to_close'] ?? false) ? 'green' : 'yellow');
+        CLI::write('Generated at: ' . (string) ($report['generated_at'] ?? ''));
+        CLI::write('Ready to close: ' . (($report['ready_to_close'] ?? false) ? 'yes' : 'no'));
+        CLI::newLine();
+
+        foreach (($report['summary'] ?? []) as $key => $value) {
+            CLI::write($key . ': ' . $value);
+        }
+
+        if (! empty($report['export_path'])) {
+            CLI::newLine();
+            CLI::write('Export written: ' . (string) $report['export_path'], 'green');
+        }
+    }
+}

app/Commands/EnrollmentDataAuditCommand.php

@@ -0,0 +1,155 @@
+<?php
+
+namespace App\Commands;
+
+use App\Support\Enrollment\DeliberationDecision;
+use CodeIgniter\CLI\BaseCommand;
+use CodeIgniter\CLI\CLI;
+use CodeIgniter\Database\BaseConnection;
+
+class EnrollmentDataAuditCommand extends BaseCommand
+{
+    protected $group = 'Registration';
+    protected $name = 'registration:enrollment-data-audit';
+    protected $description = 'Audit withdrawn terminology normalization and duplicate enrollment rows per student/year.';
+    protected $usage = 'php spark registration:enrollment-data-audit [--school-year=2026-2027] [--json]';
+    protected $options = [
+        '--school-year' => 'Optional school year filter for duplicate enrollment detection.',
+        '--json' => 'Print machine-readable JSON.',
+    ];
+
+    private BaseConnection $db;
+
+    public function run(array $params)
+    {
+        $this->db = \Config\Database::connect();
+        $schoolYear = trim((string) (CLI::getOption('school-year') ?? ''));
+
+        $report = [
+            'generated_at' => date('Y-m-d H:i:s'),
+            'school_year_filter' => $schoolYear !== '' ? $schoolYear : null,
+            'withdrawn_normalization' => $this->auditWithdrawnValues(),
+            'duplicate_enrollments' => $this->auditDuplicateEnrollments($schoolYear),
+        ];
+
+        if (CLI::getOption('json') !== null) {
+            CLI::write(json_encode($report, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
+
+            return;
+        }
+
+        CLI::write('Enrollment Data Audit', 'green');
+        CLI::newLine();
+        CLI::write('Withdrawn / misspelling findings: ' . count($report['withdrawn_normalization']), 'yellow');
+        foreach ($report['withdrawn_normalization'] as $row) {
+            CLI::write(sprintf(
+                '  [%s] %s.%s = %s',
+                $row['table'],
+                $row['column'],
+                $row['id'] ?? $row['student_id'] ?? '?',
+                $row['value']
+            ));
+        }
+        CLI::newLine();
+        CLI::write('Duplicate enrollment groups: ' . count($report['duplicate_enrollments']), 'yellow');
+        foreach ($report['duplicate_enrollments'] as $group) {
+            CLI::write(sprintf(
+                '  student=%d year=%s rows=%d ids=[%s]',
+                $group['student_id'],
+                $group['school_year'],
+                $group['row_count'],
+                implode(',', $group['enrollment_ids'])
+            ));
+        }
+    }
+
+    /**
+     * @return list<array<string, mixed>>
+     */
+    private function auditWithdrawnValues(): array
+    {
+        $findings = [];
+        $patterns = ['widthrawan', 'widthrwan', 'withdraw'];
+
+        if ($this->db->tableExists('enrollments')) {
+            $rows = $this->db->table('enrollments')
+                ->select('id, student_id, school_year, enrollment_status')
+                ->get()
+                ->getResultArray();
+            foreach ($rows as $row) {
+                $status = strtolower(trim((string) ($row['enrollment_status'] ?? '')));
+                foreach ($patterns as $pattern) {
+                    if ($status === $pattern || str_contains($status, $pattern)) {
+                        $findings[] = [
+                            'table' => 'enrollments',
+                            'column' => 'enrollment_status',
+                            'id' => (int) ($row['id'] ?? 0),
+                            'student_id' => (int) ($row['student_id'] ?? 0),
+                            'school_year' => (string) ($row['school_year'] ?? ''),
+                            'value' => (string) ($row['enrollment_status'] ?? ''),
+                            'recommended' => 'withdrawn',
+                        ];
+                    }
+                }
+            }
+        }
+
+        if ($this->db->tableExists('student_decisions')) {
+            $rows = $this->db->table('student_decisions')
+                ->select('id, student_id, school_year, decision, deliberation_decision_standard')
+                ->get()
+                ->getResultArray();
+            foreach ($rows as $row) {
+                foreach (['decision', 'deliberation_decision_standard'] as $column) {
+                    $raw = (string) ($row[$column] ?? '');
+                    $normalized = DeliberationDecision::normalize($raw);
+                    if ($raw !== '' && $normalized === DeliberationDecision::WITHDRAWN && strtoupper($raw) !== DeliberationDecision::WITHDRAWN) {
+                        $findings[] = [
+                            'table' => 'student_decisions',
+                            'column' => $column,
+                            'id' => (int) ($row['id'] ?? 0),
+                            'student_id' => (int) ($row['student_id'] ?? 0),
+                            'school_year' => (string) ($row['school_year'] ?? ''),
+                            'value' => $raw,
+                            'recommended' => DeliberationDecision::WITHDRAWN,
+                        ];
+                    }
+                }
+            }
+        }
+
+        return $findings;
+    }
+
+    /**
+     * @return list<array<string, mixed>>
+     */
+    private function auditDuplicateEnrollments(string $schoolYear): array
+    {
+        if (! $this->db->tableExists('enrollments')) {
+            return [];
+        }
+
+        $builder = $this->db->table('enrollments')
+            ->select('student_id, school_year, COUNT(*) AS row_count, GROUP_CONCAT(id ORDER BY updated_at DESC, id DESC) AS enrollment_ids', false)
+            ->groupBy('student_id, school_year')
+            ->having('row_count >', 1);
+
+        if ($schoolYear !== '') {
+            $builder->where('school_year', $schoolYear);
+        }
+
+        $groups = [];
+        foreach ($builder->get()->getResultArray() as $row) {
+            $ids = array_values(array_filter(array_map('intval', explode(',', (string) ($row['enrollment_ids'] ?? '')))));
+            $groups[] = [
+                'student_id' => (int) ($row['student_id'] ?? 0),
+                'school_year' => (string) ($row['school_year'] ?? ''),
+                'row_count' => (int) ($row['row_count'] ?? 0),
+                'enrollment_ids' => $ids,
+            ];
+        }
+
+        return $groups;
+    }
+}

app/Commands/EnrollmentPostLaunchMonitor.php

@@ -0,0 +1,295 @@
+<?php
+
+namespace App\Commands;
+
+use CodeIgniter\CLI\BaseCommand;
+use CodeIgniter\CLI\CLI;
+use CodeIgniter\Database\BaseConnection;
+
+class EnrollmentPostLaunchMonitor extends BaseCommand
+{
+    protected $group = 'Registration';
+    protected $name = 'registration:monitor';
+    protected $description = 'Monitor post-launch enrollment progress, blocks, flags, and email delivery.';
+    protected $usage = 'php spark registration:monitor [--school-year=2026-2027] [--days=7] [--json]';
+    protected $options = [
+        '--school-year' => 'Target school year name. Defaults to the active/current configured year.',
+        '--days' => 'Recent activity window in days. Defaults to 7.',
+        '--json' => 'Print machine-readable JSON.',
+    ];
+
+    private BaseConnection $db;
+
+    public function run(array $params)
+    {
+        $this->db = \Config\Database::connect();
+        $schoolYear = trim((string) (CLI::getOption('school-year') ?? ''));
+        if ($schoolYear === '') {
+            $schoolYear = $this->currentSchoolYear();
+        }
+
+        $days = max(1, (int) (CLI::getOption('days') ?? 7));
+        $report = $this->buildReport($schoolYear, $days);
+
+        if (CLI::getOption('json') !== null) {
+            CLI::write(json_encode($report, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
+            return;
+        }
+
+        $this->printReport($report);
+    }
+
+    private function buildReport(string $schoolYear, int $days): array
+    {
+        $previousYear = $this->previousSchoolYearName($schoolYear);
+        $expected = $this->expectedReturningStudentCount($previousYear);
+        $enrollments = $this->enrollmentSummary($schoolYear);
+        $flags = $this->flagSummary($schoolYear, $days);
+        $emails = $this->emailSummary($schoolYear);
+        $audits = $this->auditSummary($schoolYear, $days);
+
+        $submitted = (int) ($enrollments['submitted'] ?? 0);
+        $progressPercent = $expected > 0 ? round(($submitted / $expected) * 100, 1) : null;
+        $needsAttention = (int) ($flags['open_total'] ?? 0)
+            + (int) ($flags['stale_total'] ?? 0)
+            + (int) ($emails['failed'] ?? 0)
+            + (int) ($enrollments['blocked_total'] ?? 0);
+
+        return [
+            'school_year' => $schoolYear,
+            'source_school_year' => $previousYear,
+            'generated_at' => date('Y-m-d H:i:s'),
+            'activity_window_days' => $days,
+            'expected_returning_students' => $expected,
+            'submitted_registrations' => $submitted,
+            'progress_percent' => $progressPercent,
+            'needs_attention_count' => $needsAttention,
+            'enrollments' => $enrollments,
+            'flags' => $flags,
+            'emails' => $emails,
+            'audits' => $audits,
+        ];
+    }
+
+    private function expectedReturningStudentCount(?string $previousYear): int
+    {
+        if ($previousYear === null || ! $this->db->tableExists('student_class')) {
+            return 0;
+        }
+
+        return (int) ($this->db->table('student_class')
+            ->select('COUNT(DISTINCT student_id) AS total', false)
+            ->where('school_year', $previousYear)
+            ->get()
+            ->getRowArray()['total'] ?? 0);
+    }
+
+    private function enrollmentSummary(string $schoolYear): array
+    {
+        if (! $this->db->tableExists('enrollments')) {
+            return [
+                'total' => 0,
+                'submitted' => 0,
+                'confirmed' => 0,
+                'blocked_total' => 0,
+                'by_status' => [],
+                'by_placement_status' => [],
+            ];
+        }
+
+        $total = $this->countRows('enrollments', ['school_year' => $schoolYear]);
+        $submitted = $this->db->fieldExists('registration_submitted_at', 'enrollments')
+            ? $this->countRows('enrollments', ['school_year' => $schoolYear], 'registration_submitted_at IS NOT NULL')
+            : $total;
+        $confirmed = $this->db->fieldExists('registration_confirmed_at', 'enrollments')
+            ? $this->countRows('enrollments', ['school_year' => $schoolYear], 'registration_confirmed_at IS NOT NULL')
+            : $this->countRows('enrollments', ['school_year' => $schoolYear, 'enrollment_status' => 'enrolled']);
+
+        $blocked = 0;
+        if ($this->db->fieldExists('parent_enrollment_allowed', 'enrollments')) {
+            $blocked += $this->countRows('enrollments', ['school_year' => $schoolYear, 'parent_enrollment_allowed' => 0]);
+        }
+        if ($this->db->fieldExists('exception_required', 'enrollments')) {
+            $blocked += $this->countRows('enrollments', ['school_year' => $schoolYear, 'exception_required' => 1]);
+        }
+
+        return [
+            'total' => $total,
+            'submitted' => $submitted,
+            'confirmed' => $confirmed,
+            'blocked_total' => $blocked,
+            'by_status' => $this->groupCount('enrollments', 'enrollment_status', ['school_year' => $schoolYear]),
+            'by_placement_status' => $this->db->fieldExists('placement_status', 'enrollments')
+                ? $this->groupCount('enrollments', 'placement_status', ['school_year' => $schoolYear])
+                : [],
+        ];
+    }
+
+    private function flagSummary(string $schoolYear, int $days): array
+    {
+        if (! $this->db->tableExists('enrollment_flags')) {
+            return [
+                'open_total' => 0,
+                'stale_total' => 0,
+                'by_type' => [],
+                'by_priority' => [],
+            ];
+        }
+
+        $staleBefore = date('Y-m-d H:i:s', strtotime('-' . $days . ' days'));
+
+        return [
+            'open_total' => $this->countRows('enrollment_flags', ['school_year' => $schoolYear, 'status' => 'open']),
+            'stale_total' => $this->countRows('enrollment_flags', ['school_year' => $schoolYear, 'status' => 'open'], 'created_at < ' . $this->db->escape($staleBefore)),
+            'by_type' => $this->groupCount('enrollment_flags', 'flag_type', ['school_year' => $schoolYear, 'status' => 'open']),
+            'by_priority' => $this->groupCount('enrollment_flags', 'priority', ['school_year' => $schoolYear, 'status' => 'open']),
+        ];
+    }
+
+    private function emailSummary(string $schoolYear): array
+    {
+        if (! $this->db->tableExists('enrollment_email_records')) {
+            return [
+                'total' => 0,
+                'sent' => 0,
+                'failed' => 0,
+                'pending' => 0,
+                'by_status' => [],
+            ];
+        }
+
+        return [
+            'total' => $this->countRows('enrollment_email_records', ['school_year' => $schoolYear]),
+            'sent' => $this->countRows('enrollment_email_records', ['school_year' => $schoolYear, 'delivery_status' => 'sent']),
+            'failed' => $this->countRows('enrollment_email_records', ['school_year' => $schoolYear, 'delivery_status' => 'failed']),
+            'pending' => $this->countRows('enrollment_email_records', ['school_year' => $schoolYear, 'delivery_status' => 'pending']),
+            'by_status' => $this->groupCount('enrollment_email_records', 'delivery_status', ['school_year' => $schoolYear]),
+        ];
+    }
+
+    private function auditSummary(string $schoolYear, int $days): array
+    {
+        if (! $this->db->tableExists('enrollment_transition_audits')) {
+            return [
+                'recent_total' => 0,
+                'by_action' => [],
+            ];
+        }
+
+        $since = date('Y-m-d H:i:s', strtotime('-' . $days . ' days'));
+
+        return [
+            'recent_total' => $this->countRows('enrollment_transition_audits', ['school_year' => $schoolYear], 'created_at >= ' . $this->db->escape($since)),
+            'by_action' => $this->groupCount('enrollment_transition_audits', 'action', ['school_year' => $schoolYear], 'created_at >= ' . $this->db->escape($since)),
+        ];
+    }
+
+    private function countRows(string $table, array $where, ?string $rawWhere = null): int
+    {
+        $builder = $this->db->table($table);
+        foreach ($where as $field => $value) {
+            $builder->where($field, $value);
+        }
+        if ($rawWhere !== null) {
+            $builder->where($rawWhere, null, false);
+        }
+
+        return $builder->countAllResults();
+    }
+
+    private function groupCount(string $table, string $field, array $where, ?string $rawWhere = null): array
+    {
+        if (! $this->db->fieldExists($field, $table)) {
+            return [];
+        }
+
+        $builder = $this->db->table($table)
+            ->select($field . ' AS value, COUNT(*) AS total', false)
+            ->groupBy($field)
+            ->orderBy('total', 'DESC', false);
+
+        foreach ($where as $whereField => $value) {
+            $builder->where($whereField, $value);
+        }
+        if ($rawWhere !== null) {
+            $builder->where($rawWhere, null, false);
+        }
+
+        $result = [];
+        foreach ($builder->get()->getResultArray() as $row) {
+            $key = trim((string) ($row['value'] ?? '')) ?: 'blank';
+            $result[$key] = (int) ($row['total'] ?? 0);
+        }
+
+        return $result;
+    }
+
+    private function currentSchoolYear(): string
+    {
+        if ($this->db->tableExists('school_years')) {
+            $row = $this->db->table('school_years')
+                ->select('name')
+                ->where('status', 'active')
+                ->orderBy('id', 'DESC')
+                ->limit(1)
+                ->get()
+                ->getRowArray();
+            if (! empty($row['name'])) {
+                return (string) $row['name'];
+            }
+        }
+
+        if ($this->db->tableExists('configuration')) {
+            $row = $this->db->table('configuration')
+                ->select('config_value')
+                ->where('config_key', 'school_year')
+                ->limit(1)
+                ->get()
+                ->getRowArray();
+            if (! empty($row['config_value'])) {
+                return (string) $row['config_value'];
+            }
+        }
+
+        return '';
+    }
+
+    private function previousSchoolYearName(string $schoolYear): ?string
+    {
+        return preg_match('/^(\d{4})-(\d{4})$/', trim($schoolYear), $matches)
+            ? ((int) $matches[1] - 1) . '-' . ((int) $matches[2] - 1)
+            : null;
+    }
+
+    private function printReport(array $report): void
+    {
+        CLI::write('Registration Post-Launch Monitor: ' . (string) ($report['school_year'] ?? ''), 'cyan');
+        CLI::write('Generated at: ' . (string) ($report['generated_at'] ?? ''));
+        CLI::write('Expected returning students: ' . (int) ($report['expected_returning_students'] ?? 0));
+        CLI::write('Submitted registrations: ' . (int) ($report['submitted_registrations'] ?? 0));
+        CLI::write('Progress: ' . (($report['progress_percent'] ?? null) === null ? 'n/a' : (string) $report['progress_percent'] . '%'));
+        CLI::write('Needs attention: ' . (int) ($report['needs_attention_count'] ?? 0), ((int) ($report['needs_attention_count'] ?? 0)) > 0 ? 'yellow' : 'green');
+        CLI::newLine();
+
+        $this->printSection('Enrollments', $report['enrollments'] ?? []);
+        $this->printSection('Flags', $report['flags'] ?? []);
+        $this->printSection('Emails', $report['emails'] ?? []);
+        $this->printSection('Recent Audits', $report['audits'] ?? []);
+    }
+
+    private function printSection(string $title, array $data): void
+    {
+        CLI::write($title, 'white');
+        foreach ($data as $key => $value) {
+            if (is_array($value)) {
+                CLI::write('  ' . $key . ':');
+                foreach ($value as $nestedKey => $nestedValue) {
+                    CLI::write('    ' . $nestedKey . ': ' . $nestedValue);
+                }
+            } else {
+                CLI::write('  ' . $key . ': ' . $value);
+            }
+        }
+        CLI::newLine();
+    }
+}

app/Commands/EnrollmentReleaseAudit.php

@@ -0,0 +1,319 @@
+<?php
+
+namespace App\Commands;
+
+use CodeIgniter\CLI\BaseCommand;
+use CodeIgniter\CLI\CLI;
+use CodeIgniter\Database\BaseConnection;
+
+class EnrollmentReleaseAudit extends BaseCommand
+{
+    protected $group = 'Registration';
+    protected $name = 'registration:release-audit';
+    protected $description = 'Audit school-year transition and registration readiness before launch.';
+    protected $usage = 'php spark registration:release-audit [--school-year=2026-2027] [--json]';
+    protected $options = [
+        '--school-year' => 'Target school year name. Defaults to the active/current configured year.',
+        '--json' => 'Print machine-readable JSON.',
+    ];
+
+    private BaseConnection $db;
+
+    public function run(array $params)
+    {
+        $this->db = \Config\Database::connect();
+        $schoolYear = trim((string) (CLI::getOption('school-year') ?? ''));
+        if ($schoolYear === '') {
+            $schoolYear = $this->currentSchoolYear();
+        }
+
+        $report = $this->buildReport($schoolYear);
+
+        if (CLI::getOption('json') !== null) {
+            CLI::write(json_encode($report, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
+            return;
+        }
+
+        $this->printReport($report);
+    }
+
+    private function buildReport(string $schoolYear): array
+    {
+        $previousYear = $this->previousSchoolYearName($schoolYear);
+        $checks = [
+            'school_year_configuration' => $this->schoolYearConfigurationCheck($schoolYear),
+            'launch_approval' => $this->launchApprovalCheck($schoolYear),
+            'deliberation_decisions' => $this->deliberationDecisionCheck($schoolYear, $previousYear),
+            'open_enrollment_flags' => $this->openEnrollmentFlagsCheck($schoolYear),
+            'failed_registration_emails' => $this->failedEmailCheck($schoolYear),
+            'duplicate_or_invalid_contacts' => $this->contactQualityCheck(),
+            'email_preview_sample' => $this->emailPreviewCheck($schoolYear),
+        ];
+
+        $blocking = 0;
+        $warnings = 0;
+        foreach ($checks as $check) {
+            if (($check['severity'] ?? '') === 'blocking') {
+                $blocking++;
+            } elseif (($check['severity'] ?? '') === 'warning') {
+                $warnings++;
+            }
+        }
+
+        return [
+            'school_year' => $schoolYear,
+            'source_school_year' => $previousYear,
+            'generated_at' => date('Y-m-d H:i:s'),
+            'ready' => $blocking === 0,
+            'blocking_count' => $blocking,
+            'warning_count' => $warnings,
+            'checks' => $checks,
+        ];
+    }
+
+    private function schoolYearConfigurationCheck(string $schoolYear): array
+    {
+        if (! $this->db->tableExists('school_years')) {
+            return $this->check('blocking', 'school_years table is missing.');
+        }
+
+        $row = $this->db->table('school_years')->where('name', $schoolYear)->limit(1)->get()->getRowArray();
+        if ($row === null) {
+            return $this->check('blocking', 'Target school year record was not found.');
+        }
+
+        $missing = [];
+        foreach ([
+            'registration_starts_on' => 'registration opening date',
+            'registration_ends_on' => 'registration deadline',
+        ] as $field => $label) {
+            if (empty($row[$field])) {
+                $missing[] = $label;
+            }
+        }
+
+        if (! $this->db->tableExists('email_templates')) {
+            $missing[] = 'email templates table';
+        } elseif ($this->activeTemplateCount('registration_opening') <= 0) {
+            $missing[] = 'active registration email template';
+        }
+
+        return $missing === []
+            ? $this->check('pass', 'Required school-year launch configuration is present.')
+            : $this->check('blocking', 'Missing: ' . implode(', ', $missing));
+    }
+
+    private function launchApprovalCheck(string $schoolYear): array
+    {
+        if (! $this->db->tableExists('school_years') || ! $this->db->fieldExists('registration_launch_approved_at', 'school_years')) {
+            return $this->check('warning', 'Launch approval fields have not been migrated yet.');
+        }
+
+        $row = $this->db->table('school_years')
+            ->select('registration_launch_approved_at')
+            ->where('name', $schoolYear)
+            ->limit(1)
+            ->get()
+            ->getRowArray();
+
+        return ! empty($row['registration_launch_approved_at'] ?? null)
+            ? $this->check('pass', 'Registration launch has been approved.')
+            : $this->check('warning', 'Registration launch has not been approved yet.');
+    }
+
+    private function deliberationDecisionCheck(string $schoolYear, ?string $previousYear): array
+    {
+        if ($previousYear === null) {
+            return $this->check('warning', 'Previous school year could not be inferred.');
+        }
+        if (! $this->db->tableExists('student_class') || ! $this->db->tableExists('student_decisions')) {
+            return $this->check('warning', 'Student placement or decision tables are missing.');
+        }
+
+        $rows = $this->db->table('student_class sc')
+            ->select('COUNT(DISTINCT sc.student_id) AS total', false)
+            ->join('student_decisions sd', 'sd.student_id = sc.student_id AND sd.school_year = ' . $this->db->escape($previousYear), 'left', false)
+            ->where('sc.school_year', $previousYear)
+            ->groupStart()
+                ->where('sd.id IS NULL')
+                ->orWhere('sd.decision IS NULL')
+                ->orWhere('TRIM(sd.decision) =', '')
+            ->groupEnd()
+            ->get()
+            ->getRowArray();
+
+        $missing = (int) ($rows['total'] ?? 0);
+        return $missing === 0
+            ? $this->check('pass', 'All placed source-year students have a recorded deliberation decision.')
+            : $this->check('blocking', $missing . ' source-year student(s) are missing deliberation decisions.');
+    }
+
+    private function openEnrollmentFlagsCheck(string $schoolYear): array
+    {
+        if (! $this->db->tableExists('enrollment_flags')) {
+            return $this->check('warning', 'Enrollment flags table has not been migrated yet.');
+        }
+
+        $count = $this->db->table('enrollment_flags')
+            ->where('school_year', $schoolYear)
+            ->where('status', 'open')
+            ->countAllResults();
+
+        return $count === 0
+            ? $this->check('pass', 'No open enrollment follow-up flags remain.')
+            : $this->check('warning', $count . ' open enrollment follow-up flag(s) remain.');
+    }
+
+    private function failedEmailCheck(string $schoolYear): array
+    {
+        if (! $this->db->tableExists('enrollment_email_records')) {
+            return $this->check('warning', 'Enrollment email record table has not been migrated yet.');
+        }
+
+        $failed = $this->db->table('enrollment_email_records')
+            ->where('school_year', $schoolYear)
+            ->where('delivery_status', 'failed')
+            ->countAllResults();
+
+        return $failed === 0
+            ? $this->check('pass', 'No failed registration email records found.')
+            : $this->check('warning', $failed . ' failed registration email record(s) need retry or review.');
+    }
+
+    private function contactQualityCheck(): array
+    {
+        if (! $this->db->tableExists('users')) {
+            return $this->check('warning', 'Users table is missing.');
+        }
+        if (! $this->db->fieldExists('email', 'users')) {
+            return $this->check('warning', 'Users table does not include an email field.');
+        }
+
+        $rows = $this->db->query(
+            "SELECT LOWER(TRIM(email)) AS normalized_email, COUNT(*) AS total
+             FROM users
+             WHERE email IS NOT NULL AND email <> ''
+             GROUP BY LOWER(TRIM(email))
+             HAVING COUNT(*) > 1"
+        )->getResultArray();
+
+        $invalid = 0;
+        foreach ($this->db->table('users')->select('email')->where('email IS NOT NULL')->where('email !=', '')->get()->getResultArray() as $row) {
+            if (! filter_var((string) ($row['email'] ?? ''), FILTER_VALIDATE_EMAIL)) {
+                $invalid++;
+            }
+        }
+
+        $duplicates = count($rows);
+        if ($duplicates === 0 && $invalid === 0) {
+            return $this->check('pass', 'No duplicate or invalid parent/user email addresses were detected.');
+        }
+
+        return $this->check('warning', $duplicates . ' duplicate email value(s) and ' . $invalid . ' invalid email address(es) were detected.');
+    }
+
+    private function emailPreviewCheck(string $schoolYear): array
+    {
+        if (! $this->db->tableExists('students')) {
+            return $this->check('warning', 'Students table is missing.');
+        }
+
+        $row = $this->db->table('students')
+            ->select('parent_id')
+            ->where('parent_id IS NOT NULL', null, false)
+            ->orderBy('parent_id', 'ASC')
+            ->limit(1)
+            ->get()
+            ->getRowArray();
+
+        $parentId = is_numeric($row['parent_id'] ?? null) ? (int) $row['parent_id'] : 0;
+        if ($parentId <= 0) {
+            return $this->check('warning', 'No parent with students was found for email preview.');
+        }
+
+        try {
+            $message = service('enrollmentRegistrationEmail')->previewForParent($schoolYear, $parentId);
+        } catch (\Throwable $e) {
+            return $this->check('blocking', 'Email preview generation failed: ' . $e->getMessage());
+        }
+
+        return $message !== null && trim((string) ($message['body'] ?? '')) !== ''
+            ? $this->check('pass', 'A consolidated registration email preview can be generated.')
+            : $this->check('blocking', 'No consolidated registration email preview could be generated.');
+    }
+
+    private function currentSchoolYear(): string
+    {
+        if ($this->db->tableExists('school_years')) {
+            $row = $this->db->table('school_years')
+                ->select('name')
+                ->where('status', 'active')
+                ->orderBy('id', 'DESC')
+                ->limit(1)
+                ->get()
+                ->getRowArray();
+            if (! empty($row['name'])) {
+                return (string) $row['name'];
+            }
+        }
+
+        if ($this->db->tableExists('configuration')) {
+            $row = $this->db->table('configuration')
+                ->select('config_value')
+                ->where('config_key', 'school_year')
+                ->limit(1)
+                ->get()
+                ->getRowArray();
+            if (! empty($row['config_value'])) {
+                return (string) $row['config_value'];
+            }
+        }
+
+        return '';
+    }
+
+    private function activeTemplateCount(string $key): int
+    {
+        $fields = $this->db->getFieldNames('email_templates');
+        $keyField = in_array('code', $fields, true) ? 'code' : 'template_key';
+
+        return $this->db->table('email_templates')
+            ->where($keyField, $key)
+            ->where('is_active', 1)
+            ->countAllResults();
+    }
+
+    private function previousSchoolYearName(string $schoolYear): ?string
+    {
+        return preg_match('/^(\d{4})-(\d{4})$/', trim($schoolYear), $matches)
+            ? ((int) $matches[1] - 1) . '-' . ((int) $matches[2] - 1)
+            : null;
+    }
+
+    private function check(string $severity, string $message): array
+    {
+        return ['severity' => $severity, 'message' => $message];
+    }
+
+    private function printReport(array $report): void
+    {
+        CLI::write('Registration Release Audit: ' . (string) ($report['school_year'] ?? ''), ($report['ready'] ?? false) ? 'green' : 'red');
+        CLI::write('Generated at: ' . (string) ($report['generated_at'] ?? ''));
+        CLI::write('Ready: ' . (($report['ready'] ?? false) ? 'yes' : 'no'));
+        CLI::newLine();
+
+        foreach (($report['checks'] ?? []) as $name => $check) {
+            $severity = (string) ($check['severity'] ?? 'warning');
+            $color = match ($severity) {
+                'pass' => 'green',
+                'blocking' => 'red',
+                default => 'yellow',
+            };
+            CLI::write(sprintf('[%s] %s: %s', strtoupper($severity), $name, (string) ($check['message'] ?? '')), $color);
+        }
+
+        CLI::newLine();
+        CLI::write('Blocking: ' . (int) ($report['blocking_count'] ?? 0), ((int) ($report['blocking_count'] ?? 0)) > 0 ? 'red' : 'green');
+        CLI::write('Warnings: ' . (int) ($report['warning_count'] ?? 0), ((int) ($report['warning_count'] ?? 0)) > 0 ? 'yellow' : 'green');
+    }
+}

app/Commands/RecalculateInvoices.php

@@ -0,0 +1,171 @@
+<?php
+
+namespace App\Commands;
+
+use App\Libraries\InvoiceLedgerService;
+use App\Models\InvoiceModel;
+use CodeIgniter\CLI\BaseCommand;
+use CodeIgniter\CLI\CLI;
+
+class RecalculateInvoices extends BaseCommand
+{
+    protected $group = 'Financial';
+    protected $name = 'financial:recalculate-invoices';
+    protected $description = 'Audits invoice totals against the centralized ledger and optionally writes the corrected values.';
+    protected $usage = 'financial:recalculate-invoices [--commit] [--invoice-id=123] [--parent-id=456] [--school-year=2025-2026] [--semester=Fall]';
+    protected $options = [
+        '--commit' => 'Persist recalculated totals. Without this flag the command runs in dry-run mode.',
+        '--invoice-id' => 'Only process a single invoice ID.',
+        '--parent-id' => 'Only process invoices for one parent.',
+        '--school-year' => 'Only process invoices for the specified school year.',
+        '--semester' => 'Only process invoices for the specified semester.',
+    ];
+
+    public function run(array $params)
+    {
+        $options = $this->parseOptions($params);
+        $invoiceModel = new InvoiceModel();
+        $ledgerService = new InvoiceLedgerService();
+        $invoiceIds = $this->loadInvoiceIds($invoiceModel, $options);
+
+        if ($invoiceIds === []) {
+            CLI::write('No invoices matched the provided filters.', 'yellow');
+            return;
+        }
+
+        $commit = !empty($options['commit']);
+        CLI::write(($commit ? 'Applying' : 'Dry-run auditing') . ' ' . count($invoiceIds) . ' invoice(s)...', 'yellow');
+
+        $changed = 0;
+        $unchanged = 0;
+        $errors = 0;
+
+        foreach ($invoiceIds as $invoiceId) {
+            $invoice = $invoiceModel->find($invoiceId);
+            if (!$invoice) {
+                continue;
+            }
+
+            try {
+                $calculation = $ledgerService->calculateInvoice($invoiceId);
+                $diffs = $this->diffInvoice($invoice, $calculation);
+
+                if ($diffs === []) {
+                    $unchanged++;
+                    CLI::write('Invoice #' . $invoiceId . ' unchanged.', 'green');
+                    continue;
+                }
+
+                $changed++;
+                CLI::write('Invoice #' . $invoiceId . ' requires recalculation:', 'light_yellow');
+                foreach ($diffs as $label => $values) {
+                    CLI::write(sprintf(
+                        '  %s: %s -> %s',
+                        $label,
+                        (string) $values['from'],
+                        (string) $values['to']
+                    ));
+                }
+
+                if ($commit) {
+                    $ledgerService->recalculateInvoice($invoiceId);
+                    CLI::write('  saved', 'blue');
+                }
+            } catch (\Throwable $e) {
+                $errors++;
+                CLI::error('Invoice #' . $invoiceId . ' failed: ' . $e->getMessage());
+            }
+        }
+
+        CLI::newLine();
+        CLI::write('Processed: ' . count($invoiceIds), 'white');
+        CLI::write('Changed: ' . $changed, $changed > 0 ? 'yellow' : 'white');
+        CLI::write('Unchanged: ' . $unchanged, 'green');
+        CLI::write('Errors: ' . $errors, $errors > 0 ? 'red' : 'white');
+
+        if (!$commit) {
+            CLI::write('Dry-run complete. Re-run with --commit to persist corrections.', 'light_blue');
+        }
+    }
+
+    protected function parseOptions(array $params): array
+    {
+        $options = [
+            'commit' => false,
+            'invoice-id' => null,
+            'parent-id' => null,
+            'school-year' => null,
+            'semester' => null,
+        ];
+
+        foreach ($params as $param) {
+            $value = trim((string) $param);
+            if ($value === '--commit') {
+                $options['commit'] = true;
+                continue;
+            }
+
+            if (!str_starts_with($value, '--') || !str_contains($value, '=')) {
+                continue;
+            }
+
+            [$key, $raw] = explode('=', substr($value, 2), 2);
+            if (array_key_exists($key, $options)) {
+                $options[$key] = $raw;
+            }
+        }
+
+        return $options;
+    }
+
+    protected function loadInvoiceIds(InvoiceModel $invoiceModel, array $options): array
+    {
+        $builder = $invoiceModel->select('id')->orderBy('id', 'ASC');
+
+        if (!empty($options['invoice-id'])) {
+            $builder->where('id', (int) $options['invoice-id']);
+        }
+
+        if (!empty($options['parent-id'])) {
+            $builder->where('parent_id', (int) $options['parent-id']);
+        }
+
+        if (!empty($options['school-year'])) {
+            $builder->where('school_year', (string) $options['school-year']);
+        }
+
+        if (!empty($options['semester'])) {
+            $builder->where('semester', (string) $options['semester']);
+        }
+
+        return array_map(
+            static fn (array $row): int => (int) ($row['id'] ?? 0),
+            $builder->findAll()
+        );
+    }
+
+    protected function diffInvoice(array $invoice, array $calculation): array
+    {
+        $fields = [
+            'total_amount' => 'total_amount',
+            'paid_amount' => 'paid_amount',
+            'balance' => 'balance',
+            'status' => 'status',
+            'has_discount' => 'has_discount',
+        ];
+        $diffs = [];
+
+        foreach ($fields as $invoiceKey => $calcKey) {
+            $current = (string) ($invoice[$invoiceKey] ?? '');
+            $recalculated = (string) ($calculation[$calcKey] ?? '');
+            if ($current !== $recalculated) {
+                $diffs[$invoiceKey] = [
+                    'from' => $current,
+                    'to' => $recalculated,
+                ];
+            }
+        }
+
+        return $diffs;
+    }
+}

app/Commands/ReconcileLegacyBookIssue.php

@@ -0,0 +1,196 @@
+<?php
+
+namespace App\Commands;
+
+use CodeIgniter\CLI\BaseCommand;
+use CodeIgniter\CLI\CLI;
+use InvalidArgumentException;
+use RuntimeException;
+use Throwable;
+
+/**
+ * Converts one legacy distribution movement into immutable, priced issue
+ * evidence. The existing stock movement is linked, never replayed, so this
+ * command cannot decrement inventory twice.
+ */
+class ReconcileLegacyBookIssue extends BaseCommand
+{
+    protected $group = 'Inventory';
+    protected $name = 'inventory:reconcile-legacy-book-issue';
+    protected $description = 'List or explicitly reconcile legacy student book distributions without guessing a price.';
+    protected $usage = 'php spark inventory:reconcile-legacy-book-issue [--school-year=2025-2026] [--movement-id=123 --unit-price=25.00 --reason="approved evidence" --actor-id=7 --commit]';
+    protected $options = [
+        '--school-year' => 'Filter the read-only orphan list.',
+        '--movement-id' => 'One legacy distribution movement to reconcile.',
+        '--unit-price' => 'Admin-approved historical unit charge price.',
+        '--reason' => 'Required audit explanation for the evidence source.',
+        '--actor-id' => 'Required administrator user ID.',
+        '--commit' => 'Actually write; without this flag the command is read-only.',
+        '--json' => 'Print listing or result as JSON.',
+    ];
+
+    public function run(array $params)
+    {
+        $db = \Config\Database::connect();
+        foreach (['inventory_movements', 'inventory_item_years', 'student_book_issues', 'withdrawal_financial_calculations', 'refunds'] as $table) {
+            if (! $db->tableExists($table)) {
+                CLI::error('Required table is missing: ' . $table . '. Run migrations first.');
+                return;
+            }
+        }
+
+        $movementId = (int) (CLI::getOption('movement-id') ?? 0);
+        if ($movementId <= 0) {
+            $builder = $db->table('inventory_movements im')
+                ->select('im.id, im.item_id, im.student_id, im.class_section_id, im.qty_change, im.school_year, im.created_at, i.name AS book_name')
+                ->join('inventory_items i', 'i.id = im.item_id', 'inner')
+                ->join('student_book_issues sbi', 'sbi.distribution_movement_id = im.id', 'left')
+                ->where('im.movement_type', 'distribution')
+                ->where('im.student_id IS NOT NULL', null, false)
+                ->where('im.qty_change <', 0)
+                ->where('im.status', 'posted')
+                ->where('sbi.id', null)
+                ->where('i.type', 'book')
+                ->orderBy('im.id', 'ASC');
+            $year = trim((string) (CLI::getOption('school-year') ?? ''));
+            if ($year !== '') {
+                $builder->where('im.school_year', $year);
+            }
+            $rows = $builder->get()->getResultArray();
+            if (CLI::getOption('json') !== null) {
+                CLI::write(json_encode(['count' => count($rows), 'legacy_distributions' => $rows], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
+                return;
+            }
+            CLI::write('Legacy book distributions requiring priced issue evidence: ' . count($rows), 'yellow');
+            foreach ($rows as $row) {
+                CLI::write(sprintf('#%d %s student=%d qty=%d year=%s', (int) $row['id'], (string) $row['book_name'], (int) $row['student_id'], abs((int) $row['qty_change']), (string) $row['school_year']));
+            }
+            return;
+        }
+
+        try {
+            $priceCents = $this->priceToCents((string) (CLI::getOption('unit-price') ?? ''));
+            $reason = trim((string) (CLI::getOption('reason') ?? ''));
+            $actorId = (int) (CLI::getOption('actor-id') ?? 0);
+            if ($reason === '' || $actorId <= 0) {
+                throw new InvalidArgumentException('--reason and a positive --actor-id are required.');
+            }
+
+            $db->transBegin();
+            $movement = $db->query('SELECT * FROM inventory_movements WHERE id = ? FOR UPDATE', [$movementId])->getRowArray();
+            if ($movement === null || ($movement['movement_type'] ?? '') !== 'distribution' || ($movement['status'] ?? '') !== 'posted' || (int) ($movement['qty_change'] ?? 0) >= 0 || (int) ($movement['student_id'] ?? 0) <= 0) {
+                throw new InvalidArgumentException('The movement is not a negative student distribution.');
+            }
+            if ($db->table('student_book_issues')->where('distribution_movement_id', $movementId)->countAllResults() > 0) {
+                throw new InvalidArgumentException('This movement is already linked to student issue evidence.');
+            }
+            $book = $db->table('inventory_items')->select('id, name, type')->where('id', (int) $movement['item_id'])->get(1)->getRowArray();
+            if ($book === null || ($book['type'] ?? '') !== 'book') {
+                throw new InvalidArgumentException('The movement item is not a book.');
+            }
+            $schoolYear = trim((string) ($movement['school_year'] ?? ''));
+            if ($schoolYear === '') {
+                throw new InvalidArgumentException('The legacy movement has no school year. Correct that evidence first.');
+            }
+            $itemYear = $db->table('inventory_item_years')
+                ->where('inventory_item_id', (int) $movement['item_id'])
+                ->where('school_year', $schoolYear)->get(1)->getRowArray();
+            if ($itemYear === null) {
+                throw new InvalidArgumentException('The book has no inventory-year record for ' . $schoolYear . '.');
+            }
+            $enrollments = $db->table('enrollments')->select('id, parent_id, class_section_id')
+                ->where('student_id', (int) $movement['student_id'])->where('school_year', $schoolYear)->get()->getResultArray();
+            if (count($enrollments) !== 1 || (int) ($enrollments[0]['parent_id'] ?? 0) <= 0) {
+                throw new InvalidArgumentException('Exactly one parent-linked enrollment must exist for the student and year.');
+            }
+
+            $quantity = abs((int) $movement['qty_change']);
+            if ($quantity <= 0 || $priceCents > intdiv(2147483647, $quantity)) {
+                throw new InvalidArgumentException('The quantity and approved price exceed the supported charge range.');
+            }
+            $now = date('Y-m-d H:i:s');
+            $issuedAt = trim((string) ($movement['created_at'] ?? '')) ?: $now;
+            $issue = [
+                'student_id' => (int) $movement['student_id'],
+                'enrollment_id' => (int) $enrollments[0]['id'],
+                'parent_id' => (int) $enrollments[0]['parent_id'],
+                'inventory_item_id' => (int) $movement['item_id'],
+                'inventory_item_year_id' => (int) $itemYear['id'],
+                'school_year' => $schoolYear,
+                'class_section_id' => (int) ($movement['class_section_id'] ?? $enrollments[0]['class_section_id'] ?? 0) ?: null,
+                'quantity' => $quantity,
+                'unit_charge_price_cents' => $priceCents,
+                'total_charge_cents' => $priceCents * $quantity,
+                'distribution_movement_id' => $movementId,
+                'idempotency_key' => 'legacy-distribution:' . $movementId,
+                'status' => 'issued',
+                'issued_at' => $issuedAt,
+                'issued_by' => $actorId,
+                'created_at' => $now,
+                'updated_at' => $now,
+            ];
+            if (CLI::getOption('commit') === null) {
+                $db->transRollback();
+                $result = ['mode' => 'dry-run', 'movement_id' => $movementId, 'book' => $book['name'], 'issue' => $issue, 'reason' => $reason];
+                CLI::write(json_encode($result, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
+                CLI::write('DRY RUN — add --commit to save.', 'yellow');
+                return;
+            }
+            if (! $db->table('student_book_issues')->insert($issue)) {
+                throw new RuntimeException('Unable to insert issue evidence.');
+            }
+            $issueId = (int) $db->insertID();
+            $db->table('inventory_movements')->where('id', $movementId)->update([
+                'item_year_id' => (int) $itemYear['id'],
+                'idempotency_key' => 'legacy-distribution-movement:' . $movementId,
+                'status' => 'posted',
+                'source_type' => 'student_book_issue',
+                'source_id' => $issueId,
+                'note' => trim((string) ($movement['note'] ?? '') . "\nLegacy evidence approved by user #{$actorId}: {$reason}"),
+                'updated_at' => $now,
+            ]);
+            $affectedCalculations = $db->table('withdrawal_financial_calculations')
+                ->select('id')
+                ->where('student_id', (int) $movement['student_id'])
+                ->where('school_year', $schoolYear)
+                ->where('status', 'posted')
+                ->where('withdrawal_request_date >=', substr($issuedAt, 0, 10))
+                ->get()->getResultArray();
+            $affectedIds = array_values(array_filter(array_map(static fn (array $row): int => (int) ($row['id'] ?? 0), $affectedCalculations)));
+            if ($affectedIds !== []) {
+                $db->table('withdrawal_financial_calculations')->whereIn('id', $affectedIds)->update([
+                    'status' => 'requires_review',
+                    'active_posted_key' => null,
+                    'updated_at' => $now,
+                ]);
+                $db->table('refunds')->whereIn('withdrawal_calculation_id', $affectedIds)->update([
+                    'reconciliation_status' => 'requires_review',
+                    'reconciliation_reason' => 'Legacy book issue evidence was added after the withdrawal calculation was posted.',
+                    'reconciliation_required_at' => $now,
+                    'updated_at' => $now,
+                ]);
+            }
+            if (! $db->transCommit()) {
+                throw new RuntimeException('Unable to commit the reconciliation.');
+            }
+            CLI::write('Reconciled movement #' . $movementId . ' as issue #' . $issueId . ' without changing stock.', 'green');
+        } catch (Throwable $e) {
+            $db->transRollback();
+            CLI::error($e->getMessage());
+        }
+    }
+
+    private function priceToCents(string $price): int
+    {
+        $price = trim($price);
+        if (! preg_match('/^\d+(?:\.\d{1,2})?$/', $price)) {
+            throw new InvalidArgumentException('--unit-price is required with no more than two decimal places.');
+        }
+        [$whole, $fraction] = array_pad(explode('.', $price, 2), 2, '');
+        $cents = ((int) $whole * 100) + (int) str_pad($fraction, 2, '0');
+        if ($cents <= 0 || $cents > 2147483647) {
+            throw new InvalidArgumentException('Unit price must be greater than zero and within range.');
+        }
+        return $cents;
+    }
+}

app/Commands/RefreshEnrollmentAdminTables.php

@@ -0,0 +1,217 @@
+<?php
+
+namespace App\Commands;
+
+use CodeIgniter\CLI\BaseCommand;
+use CodeIgniter\CLI\CLI;
+use CodeIgniter\Database\BaseConnection;
+use Throwable;
+
+class RefreshEnrollmentAdminTables extends BaseCommand
+{
+    protected $group = 'Registration';
+    protected $name = 'registration:refresh-admin-tables';
+    protected $description = 'Refresh enrollment admin dashboard data from the transition service.';
+    protected $usage = 'php spark registration:refresh-admin-tables [--school-year=2026-2027] [--limit=50] [--dry-run]';
+    protected $options = [
+        '--school-year' => 'Target school year name. Defaults to the active/current configured year.',
+        '--limit' => 'Maximum number of source-year students to process.',
+        '--dry-run' => 'Preview target/source years and source student count without writing.',
+    ];
+
+    private BaseConnection $db;
+
+    public function run(array $params)
+    {
+        $this->db = \Config\Database::connect();
+        $options = $this->parseOptions($params);
+        $schoolYear = trim((string) ($options['school-year'] ?? ''));
+        if ($schoolYear === '') {
+            $schoolYear = $this->currentSchoolYear();
+        }
+
+        $sourceYear = $this->previousSchoolYearName($schoolYear);
+        if ($schoolYear === '' || $sourceYear === null) {
+            CLI::error('Unable to determine target/source school year.');
+            return;
+        }
+
+        $limit = (int) ($options['limit'] ?? 0);
+        $dryRun = ! empty($options['dry-run']);
+        $students = $this->sourceStudents($sourceYear, $limit);
+
+        CLI::write('Enrollment admin refresh', 'cyan');
+        CLI::write('Target year: ' . $schoolYear);
+        CLI::write('Source year: ' . $sourceYear);
+        CLI::write('Source students: ' . count($students));
+
+        $before = $this->dashboardCounts($schoolYear);
+        $this->printCounts('Before', $before);
+
+        if ($dryRun) {
+            CLI::write('Dry-run complete. Re-run without --dry-run to write updates.', 'yellow');
+            return;
+        }
+
+        $processed = 0;
+        $eligible = 0;
+        $blocked = 0;
+        $errors = 0;
+        $transitionService = service('enrollmentTransition');
+
+        foreach ($students as $student) {
+            $studentId = (int) ($student['student_id'] ?? 0);
+            if ($studentId <= 0) {
+                continue;
+            }
+
+            try {
+                $evaluation = $transitionService->applyInitialTransition(
+                    $studentId,
+                    $sourceYear,
+                    $schoolYear,
+                    is_numeric($student['parent_id'] ?? null) ? (int) $student['parent_id'] : null,
+                    null,
+                    'admin'
+                );
+
+                $processed++;
+                if (! empty($evaluation['academic_eligible']) && ($evaluation['blockers'] ?? []) === []) {
+                    $eligible++;
+                } else {
+                    $blocked++;
+                }
+            } catch (Throwable $e) {
+                $errors++;
+                CLI::error('Student #' . $studentId . ' failed: ' . $e->getMessage());
+            }
+        }
+
+        $after = $this->dashboardCounts($schoolYear);
+        $this->printCounts('After', $after);
+        CLI::write('Processed: ' . $processed, 'white');
+        CLI::write('Eligible/applied: ' . $eligible, 'green');
+        CLI::write('Blocked/flagged: ' . $blocked, $blocked > 0 ? 'yellow' : 'white');
+        CLI::write('Errors: ' . $errors, $errors > 0 ? 'red' : 'white');
+    }
+
+    private function parseOptions(array $params): array
+    {
+        $options = [
+            'school-year' => '',
+            'limit' => 0,
+            'dry-run' => false,
+        ];
+
+        $rawParams = array_merge($params, array_slice($_SERVER['argv'] ?? [], 2));
+
+        foreach ($rawParams as $param) {
+            $value = trim((string) $param);
+            if ($value === '--dry-run') {
+                $options['dry-run'] = true;
+                continue;
+            }
+
+            if (! str_starts_with($value, '--') || ! str_contains($value, '=')) {
+                continue;
+            }
+
+            [$key, $raw] = explode('=', substr($value, 2), 2);
+            if (array_key_exists($key, $options)) {
+                $options[$key] = $raw;
+            }
+        }
+
+        return $options;
+    }
+
+    private function sourceStudents(string $sourceYear, int $limit): array
+    {
+        if (! $this->db->tableExists('student_class')) {
+            return [];
+        }
+
+        $builder = $this->db->table('student_class sc')
+            ->select('sc.student_id, s.parent_id')
+            ->join('students s', 's.id = sc.student_id', 'left')
+            ->where('sc.school_year', $sourceYear)
+            ->groupBy('sc.student_id, s.parent_id')
+            ->orderBy('sc.student_id', 'ASC');
+
+        if ($limit > 0) {
+            $builder->limit($limit);
+        }
+
+        return $builder->get()->getResultArray();
+    }
+
+    private function dashboardCounts(string $schoolYear): array
+    {
+        return [
+            'enrollments' => $this->countRows('enrollments', ['school_year' => $schoolYear]),
+            'open_flags' => $this->countRows('enrollment_flags', ['school_year' => $schoolYear, 'status' => 'open']),
+            'audits' => $this->countRows('enrollment_transition_audits', ['school_year' => $schoolYear]),
+            'exceptions' => $this->countRows('enrollment_exceptions', ['school_year' => $schoolYear]),
+            'email_records' => $this->countRows('enrollment_email_records', ['school_year' => $schoolYear]),
+        ];
+    }
+
+    private function countRows(string $table, array $where): int
+    {
+        if (! $this->db->tableExists($table)) {
+            return 0;
+        }
+
+        $builder = $this->db->table($table);
+        foreach ($where as $field => $value) {
+            $builder->where($field, $value);
+        }
+
+        return $builder->countAllResults();
+    }
+
+    private function printCounts(string $label, array $counts): void
+    {
+        CLI::write($label . ' counts:', 'white');
+        foreach ($counts as $key => $value) {
+            CLI::write('  ' . $key . ': ' . $value);
+        }
+    }
+
+    private function currentSchoolYear(): string
+    {
+        if ($this->db->tableExists('school_years')) {
+            $row = $this->db->table('school_years')
+                ->select('name')
+                ->where('status', 'active')
+                ->orderBy('id', 'DESC')
+                ->limit(1)
+                ->get()
+                ->getRowArray();
+            if (! empty($row['name'])) {
+                return (string) $row['name'];
+            }
+        }
+
+        if ($this->db->tableExists('configuration')) {
+            $row = $this->db->table('configuration')
+                ->select('config_value')
+                ->where('config_key', 'school_year')
+                ->limit(1)
+                ->get()
+                ->getRowArray();
+            if (! empty($row['config_value'])) {
+                return (string) $row['config_value'];
+            }
+        }
+
+        return '';
+    }
+
+    private function previousSchoolYearName(string $schoolYear): ?string
+    {
+        return preg_match('/^(\d{4})-(\d{4})$/', trim($schoolYear), $matches)
+            ? ((int) $matches[1] - 1) . '-' . ((int) $matches[2] - 1)
+            : null;
+    }
+}

app/Commands/SendExamDraftDeadlineReminders.php

@@ -23,7 +23,7 @@ class SendExamDraftDeadlineReminders extends BaseCommand
 
         $configModel = new ConfigurationModel();
         $schoolYear = (string) ($configModel->getConfig('school_year') ?? '');
-        $semester = (string) ($configModel->getConfig('semester') ?? '');
+        $semester = (string) (getSemester() ?? '');
         $deadlineValue = trim((string) ($configModel->getConfig('exam_draft_deadline') ?? ''));
         if ($deadlineValue === '') {
             CLI::write('exam_draft_deadline is not configured.', 'yellow');
@@ -54,13 +54,10 @@ class SendExamDraftDeadlineReminders extends BaseCommand
 
         $db = Database::connect();
         $teacherClassRows = $db->table('teacher_class')
-            ->select('teacher_id, class_section_id, school_year, semester')
+            ->select('teacher_id, class_section_id, school_year')
             ->when($schoolYear !== '', static function ($builder) use ($schoolYear) {
                 return $builder->where('school_year', $schoolYear);
             })
-            ->when($semester !== '', static function ($builder) use ($semester) {
-                return $builder->where('semester', $semester);
-            })
             ->get()
             ->getResultArray();
 

app/Commands/SendRegistrationOpeningEmail.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace App\Commands;
+
+use CodeIgniter\CLI\BaseCommand;
+use CodeIgniter\CLI\CLI;
+
+class SendRegistrationOpeningEmail extends BaseCommand
+{
+    protected $group = 'Registration';
+    protected $name = 'registration:send-opening-email';
+    protected $description = 'Send the parent registration opening email on the configured registration start date.';
+    protected $usage = 'php spark registration:send-opening-email [--force] [--date=YYYY-MM-DD] [--email=parent@example.com] [--dry-run] [--tz=America/New_York]';
+
+    public function run(array $params)
+    {
+        $tzName = (string) (CLI::getOption('tz') ?? config('School')->attendance['timezone'] ?? 'America/New_York');
+        $timezone = new \DateTimeZone($tzName);
+        $dateOption = CLI::getOption('date');
+        $date = $dateOption
+            ? new \DateTimeImmutable((string) $dateOption, $timezone)
+            : new \DateTimeImmutable('today', $timezone);
+
+        $force = CLI::getOption('force') !== null;
+        $dryRun = CLI::getOption('dry-run') !== null;
+        $email = CLI::getOption('email');
+        $email = is_string($email) && trim($email) !== '' ? trim($email) : null;
+
+        if ($email !== null && ! filter_var($email, FILTER_VALIDATE_EMAIL)) {
+            CLI::error('Invalid --email value.');
+            return;
+        }
+
+        $service = service('enrollmentRegistrationEmail');
+        $summary = $service->sendForDate($date, $force, $email, $dryRun);
+
+        foreach ($summary['messages'] as $message) {
+            CLI::write($message, 'yellow');
+        }
+
+        $sentLabel = $dryRun ? 'Would send' : 'Sent';
+
+        CLI::write(sprintf(
+            'Registration opening email complete. Years: %d. Recipients: %d. %s: %d. Failed: %d. Skipped: %d%s.',
+            $summary['school_years'],
+            $summary['recipients'],
+            $sentLabel,
+            $summary['sent'],
+            $summary['failed'],
+            $summary['skipped'],
+            $dryRun ? ' (dry run)' : ''
+        ), $summary['failed'] > 0 ? 'red' : 'green');
+    }
+}

app/Commands/SyncPaypalPayments.php

@@ -1,232 +0,0 @@
-<?php
-
-namespace App\Commands;
-
-use CodeIgniter\CLI\BaseCommand;
-use CodeIgniter\CLI\CLI;
-use App\Models\PayPalPaymentModel;
-use App\Models\PaymentModel;
-use App\Models\UserModel;
-use App\Models\ConfigurationModel;
-use App\Models\InvoiceModel;
-use App\Models\StudentModel;
-use App\Models\EnrollmentModel;
-
-class SyncPaypalPayments extends BaseCommand
-{
-    protected $group       = 'Payments';
-    protected $name        = 'payments:sync-paypal';
-    protected $description = 'Sync PayPal payments to internal payments table from paypal_payments';
-    protected $configModel;
-    protected $semester;
-    protected $schoolYear;
-    protected $paypalModel;
-    protected $paymentModel;
-    protected $userModel;
-    protected $invoiceModel;
-    protected $studentModel;
-    protected $enrollmentModel;
-
-    public function __construct()
-    {
-        $this->configModel = new ConfigurationModel();
-        $this->paypalModel    = new PayPalPaymentModel();
-        $this->paymentModel   = new PaymentModel();
-        $this->userModel      = new UserModel();
-        $this->invoiceModel   = new InvoiceModel();
-        $this->studentModel = new StudentModel();
-        $this->enrollmentModel = new EnrollmentModel();
-
-        $this->semester = $this->configModel->getConfig('semester');
-        $this->schoolYear = $this->configModel->getConfig('school_year');
-    }
-
-    public function run(array $params)
-    {
-        $dryRun     = CLI::getOption('dry-run');
-        $reportOnly = CLI::getOption('report-only');
-        $mode       = $reportOnly ? 'REPORT-ONLY' : ($dryRun ? 'DRY-RUN' : 'LIVE');
-
-        $paypalEntries = $this->paypalModel
-            ->where('status', 'COMPLETED')
-            ->where('synced', 0)
-            ->where('sync_attempts <', 3)
-            ->where('transaction_id IS NOT NULL')
-            ->findAll();
-
-        $syncedCount = 0;
-        $failed = [];
-
-        foreach ($paypalEntries as $entry) {
-            $parentId = null;
-            $invoiceId = 0;
-
-            $users = $this->userModel->getUsersBySchoolId($entry['parent_school_id']);
-            $user = $users[0] ?? null;
-
-            // Always increment sync_attempts unless report-only
-            if (!$reportOnly) {
-                $this->paypalModel->update($entry['id'], [
-                    'sync_attempts' => $entry['sync_attempts'] + 1
-                ]);
-            }
-
-            if ($user) {
-                $parentId = $user['id'];
-
-                $invoice = $this->invoiceModel->getInvoicesByParentId($parentId, $this->schoolYear);
-
-                if (!$reportOnly && !$dryRun) {
-                    if ($invoice) {
-                        $invoiceId = $invoice['id'];
-
-                        $success = $this->processPayment(
-                            $invoiceId,
-                            $entry['amount'],
-                            'PayPal',
-                            null,
-                            $entry['transaction_id'],
-                            date('Y-m-d', strtotime($entry['created_at'])),
-                            $this->schoolYear,
-                            $this->semester
-                        );
-
-                        if (!$success) {
-                            $failed[] = $entry['transaction_id'];
-                            continue;
-                        }
-                    } else {
-                        $this->paymentModel->insert([
-                            'parent_id'              => $parentId,
-                            'invoice_id'             => 0,
-                            'total_amount'           => $entry['amount'],
-                            'paid_amount'            => $entry['amount'],
-                            'balance'                => 0.00,
-                            'number_of_installments' => 1,
-                            'transaction_id'         => $entry['transaction_id'],
-                            'payment_method'         => 'PayPal',
-                            'payment_date'           => date('Y-m-d', strtotime($entry['created_at'])),
-                            'school_year'            => $this->schoolYear,
-                            'semester'               => $this->semester,
-                            'status'                 => 'Completed',
-                            'updated_by'             => null,
-                        ]);
-                    }
-
-                    // Mark as synced only in LIVE mode
-                    $this->paypalModel->update($entry['id'], ['synced' => 1]);
-                }
-
-                $syncedCount++;
-            } else {
-                log_message('error', "[PAYPAL SYNC FAILED] No user found for parent_school_id: {$entry['parent_school_id']}");
-                $failed[] = $entry['transaction_id'];
-            }
-        }
-
-        // === Logging ===
-        log_message('info', "[$mode] PAYPAL SYNC: $syncedCount processed.");
-        if (!empty($failed)) {
-            log_message('error', "[$mode] PAYPAL SYNC Failed: " . implode(', ', $failed));
-        }
-
-        // === CLI Output ===
-        CLI::write("[$mode] $syncedCount PayPal payments processed.", 'green');
-        if (!empty($failed)) {
-            CLI::error("[$mode] Failed transactions: " . implode(', ', $failed));
-        }
-
-        // === Email Report: Only if there's any update ===
-        if ($syncedCount > 0 || !empty($failed)) {
-            helper('email');
-            $email = \Config\Services::email();
-            $email->setTo('support@alrahmaisgl.org');
-            $email->setFrom('no-parentsreply@alrahmaisgl.org', 'PayPal Sync Report');
-            $email->setSubject("[$mode] PayPal Sync Report - " . date('Y-m-d H:i'));
-
-            $body = "PayPal Sync Mode: $mode\n\n";
-            $body .= "$syncedCount PayPal payments processed.\n\n";
-
-            if (!empty($failed)) {
-                $body .= count($failed) . " failed transactions:\n";
-                $body .= implode("\n", $failed);
-            } else {
-                $body .= "No failed transactions.\n";
-            }
-
-            $email->setMessage(nl2br($body));
-
-            if ($email->send()) {
-                CLI::write("[$mode] Email report sent successfully.", 'yellow');
-            } else {
-                CLI::error("[$mode] Failed to send email report.");
-                log_message('error', 'Email send error: ' . $email->printDebugger(['headers']));
-            }
-        } else {
-            log_message('info', "[$mode] No PayPal sync updates. Email not sent.");
-            CLI::write("[$mode] No changes to report. Email not sent.", 'blue');
-        }
-    }
-
-    private function processPayment($invoiceId, $amount, $paymentMethod, $checkFile = null, $transactionId = null, $paymentDate = null, $schoolYear = null, $semester = null)
-    {
-        $invoice = $this->invoiceModel->find($invoiceId);
-        if (!$invoice) {
-            return false;
-        }
-
-        $transactionId = $transactionId ?? 'INV-' . $invoiceId . '-' . time();
-        $paymentDate   = $paymentDate ?? date('Y-m-d');
-
-        $newPaid    = $invoice['paid_amount'] + $amount;
-        $newBalance = $invoice['balance'] - $amount;
-
-        $invoiceUpdateData = [
-            'paid_amount' => $newPaid,
-            'balance'     => $newBalance,
-            'status'      => ($newBalance <= 0) ? 'Paid' : $invoice['status'],
-        ];
-
-        if (!$this->invoiceModel->update($invoiceId, $invoiceUpdateData)) {
-            return false;
-        }
-
-        $this->paymentModel->insert([
-            'parent_id'              => $invoice['parent_id'],
-            'invoice_id'             => $invoiceId,
-            'total_amount'           => $invoice['total_amount'],
-            'paid_amount'            => $amount,
-            'balance'                => $newBalance,
-            'number_of_installments' => 1,
-            'transaction_id'         => $transactionId,
-            'payment_method'         => $paymentMethod,
-            'payment_date'           => $paymentDate,
-            'status'                 => ($newBalance <= 0) ? 'Full' : 'Partial',
-            'check_file'             => $checkFile,
-            'updated_by'             => null, // Avoid using session()->get() in CLI
-            'school_year'            => $schoolYear,
-            'semester'               => $semester
-        ]);
-
-        $this->updateEnrollmentStatusIfPaid($invoiceId, $schoolYear);
-        return true;
-    }
-
-    private function updateEnrollmentStatusIfPaid($invoiceId, $schoolYear)
-    {
-        $invoice = $this->invoiceModel->find($invoiceId);
-        if (!$invoice || $invoice['balance'] > 0) {
-            return;
-        }
-
-        $students = $this->studentModel->where('parent_id', $invoice['parent_id'])
-            ->where('school_year', $schoolYear)
-            ->findAll();
-
-        foreach ($students as $student) {
-            $this->enrollmentModel->set(['enrollment_status' => 'enrolled'])
-                ->where('student_id', $student['id'])
-                ->update();
-        }
-    }
-}

app/Commands/SyncStudentActivity.php

@@ -0,0 +1,171 @@
+<?php
+
+namespace App\Commands;
+
+use App\Services\EnrollmentStatusService;
+use CodeIgniter\CLI\BaseCommand;
+use CodeIgniter\CLI\CLI;
+use CodeIgniter\Database\BaseConnection;
+
+class SyncStudentActivity extends BaseCommand
+{
+    protected $group = 'Enrollment';
+    protected $name = 'students:sync-activity';
+    protected $description = 'Synchronize students.is_active from current-year enrollment_status.';
+    protected $usage = 'php spark students:sync-activity --school-year=YYYY-YYYY [--dry-run]';
+    protected $options = [
+        '--school-year' => 'School year to use as the controlling enrollment year.',
+        '--dry-run' => 'Report changes without updating students.',
+    ];
+
+    private BaseConnection $db;
+    private EnrollmentStatusService $statusService;
+
+    public function run(array $params)
+    {
+        $this->db = \Config\Database::connect();
+        $this->statusService = new EnrollmentStatusService($this->db);
+
+        $schoolYear = $this->optionValue('school-year');
+        if ($schoolYear === '') {
+            $schoolYear = $this->statusService->currentSchoolYear();
+        }
+
+        if ($schoolYear === '') {
+            CLI::error('Missing --school-year and no configured current school year was found.');
+            return EXIT_ERROR;
+        }
+
+        $dryRun = CLI::getOption('dry-run') !== null;
+        $duplicates = $this->duplicates($schoolYear);
+        $unknownStatuses = [];
+        $withoutEnrollment = [];
+        $mismatches = [];
+        $updated = 0;
+
+        $students = $this->db->table('students')
+            ->select('id, school_id, firstname, lastname, is_active')
+            ->orderBy('id', 'ASC')
+            ->get()
+            ->getResultArray();
+
+        foreach ($students as $student) {
+            $studentId = (int) $student['id'];
+            $enrollment = $this->statusService->controllingEnrollment($studentId, $schoolYear);
+            if ($enrollment === null) {
+                $expected = 0;
+                $withoutEnrollment[] = $this->studentLabel($student);
+            } else {
+                try {
+                    $status = $this->statusService->normalizeStatus((string) ($enrollment['enrollment_status'] ?? ''));
+                    $expected = $this->statusService->activeFlagForStatus($status);
+                } catch (\InvalidArgumentException $e) {
+                    $unknownStatuses[] = [
+                        'student' => $this->studentLabel($student),
+                        'enrollment_id' => (int) ($enrollment['id'] ?? 0),
+                        'status' => (string) ($enrollment['enrollment_status'] ?? ''),
+                    ];
+                    continue;
+                }
+            }
+
+            $actual = (int) ($student['is_active'] ?? 1);
+            if ($actual !== $expected) {
+                $mismatches[] = [
+                    'student' => $this->studentLabel($student),
+                    'current' => $actual,
+                    'expected' => $expected,
+                    'status' => (string) ($enrollment['enrollment_status'] ?? 'no enrollment'),
+                ];
+
+                if (! $dryRun) {
+                    $this->db->table('students')->where('id', $studentId)->update(['is_active' => $expected]);
+                    $updated++;
+                }
+            }
+        }
+
+        CLI::write('School year: ' . $schoolYear);
+        CLI::write('Dry run: ' . ($dryRun ? 'yes' : 'no'));
+        CLI::write('Duplicate enrollment groups: ' . count($duplicates));
+        foreach ($duplicates as $row) {
+            CLI::write(sprintf(
+                '  student_id=%d school_year=%s semester=%s count=%d',
+                (int) $row['student_id'],
+                (string) $row['school_year'],
+                (string) ($row['semester'] ?? ''),
+                (int) $row['row_count']
+            ));
+        }
+
+        CLI::write('Unknown statuses: ' . count($unknownStatuses));
+        foreach ($unknownStatuses as $row) {
+            CLI::write(sprintf('  %s enrollment_id=%d status=%s', $row['student'], $row['enrollment_id'], $row['status']));
+        }
+
+        CLI::write('Students without current enrollment: ' . count($withoutEnrollment));
+        foreach (array_slice($withoutEnrollment, 0, 50) as $label) {
+            CLI::write('  ' . $label);
+        }
+        if (count($withoutEnrollment) > 50) {
+            CLI::write('  ... ' . (count($withoutEnrollment) - 50) . ' more');
+        }
+
+        CLI::write('Mismatches: ' . count($mismatches));
+        foreach ($mismatches as $row) {
+            CLI::write(sprintf(
+                '  %s current=%d expected=%d status=%s',
+                $row['student'],
+                $row['current'],
+                $row['expected'],
+                $row['status']
+            ));
+        }
+
+        if (! $dryRun) {
+            CLI::write('Updated students: ' . $updated);
+        }
+
+        return EXIT_SUCCESS;
+    }
+
+    private function duplicates(string $schoolYear): array
+    {
+        return $this->db->table('enrollments')
+            ->select('student_id, school_year, semester, COUNT(*) AS row_count')
+            ->where('school_year', $schoolYear)
+            ->groupBy('student_id, school_year, semester')
+            ->having('COUNT(*) >', 1)
+            ->orderBy('student_id', 'ASC')
+            ->get()
+            ->getResultArray();
+    }
+
+    private function studentLabel(array $student): string
+    {
+        $name = trim((string) ($student['firstname'] ?? '') . ' ' . (string) ($student['lastname'] ?? ''));
+        return '#' . (int) ($student['id'] ?? 0) . ($name !== '' ? ' ' . $name : '');
+    }
+
+    private function optionValue(string $name): string
+    {
+        $value = CLI::getOption($name);
+        if (is_string($value) && trim($value) !== '') {
+            return trim($value);
+        }
+
+        $argv = $_SERVER['argv'] ?? [];
+        $prefix = '--' . $name . '=';
+        foreach ($argv as $index => $arg) {
+            if (is_string($arg) && str_starts_with($arg, $prefix)) {
+                return trim(substr($arg, strlen($prefix)));
+            }
+
+            if ($arg === '--' . $name && isset($argv[$index + 1])) {
+                return trim((string) $argv[$index + 1]);
+            }
+        }
+
+        return '';
+    }
+}

app/Commands/WithdrawalInventoryAudit.php

@@ -0,0 +1,182 @@
+<?php
+
+namespace App\Commands;
+
+use CodeIgniter\CLI\BaseCommand;
+use CodeIgniter\CLI\CLI;
+
+/** Read-only audit for withdrawal refund posting prerequisites. */
+class WithdrawalInventoryAudit extends BaseCommand
+{
+    protected $group = 'Financial';
+    protected $name = 'financial:withdrawal-inventory-audit';
+    protected $description = 'Audit withdrawal policy, book inventory evidence, invoices, and open refunds without changing data.';
+    protected $usage = 'php spark financial:withdrawal-inventory-audit --school-year=2025-2026 [--json]';
+    protected $options = ['--school-year' => 'Required school year.', '--json' => 'Print JSON.'];
+
+    public function run(array $params)
+    {
+        $db = \Config\Database::connect();
+        $year = trim((string) (CLI::getOption('school-year') ?? ''));
+        if ($year === '') {
+            CLI::error('--school-year is required; the audit will not guess an active year.');
+            return;
+        }
+        $checks = [];
+        $policy = $db->table('school_years')->where('name', $year)->get(1)->getRowArray();
+        $configWeeksRow = $db->table('configuration')
+            ->select('config_value')
+            ->where('config_key', 'total_instructional_weeks')
+            ->orderBy('id', 'DESC')
+            ->get(1)
+            ->getRowArray();
+        $configWeeks = filter_var($configWeeksRow['config_value'] ?? null, FILTER_VALIDATE_INT);
+        $checks['policy'] = $policy !== null
+            && $configWeeks !== false
+            && $configWeeks > 0
+            && (int) ($policy['annual_fee_includes_books'] ?? 0) === 1
+            ? $this->check('pass', 'School-year refund inputs are present.')
+            : $this->check('blocking', 'Configuration total_instructional_weeks or book-inclusive policy is missing.');
+
+        $missingPrices = $db->table('inventory_item_years iy')
+            ->join('inventory_items i', 'i.id = iy.inventory_item_id', 'inner')
+            ->where('iy.school_year', $year)->where('i.type', 'book')
+            ->groupStart()->where('iy.charge_price_cents <=', 0)->orWhere('iy.price_confirmed !=', 1)->groupEnd()
+            ->countAllResults();
+        $checks['book_prices'] = $missingPrices === 0 ? $this->check('pass', 'All book-year prices are confirmed.') : $this->check('blocking', $missingPrices . ' book-year price(s) are missing or unconfirmed.');
+
+        $catalogRows = $db->table('inventory_items')->select('id, name, isbn, edition, sku, author')->where('type', 'book')->get()->getResultArray();
+        $identityCounts = [];
+        $skuCounts = [];
+        foreach ($catalogRows as $catalogRow) {
+            $isbn = strtoupper((string) preg_replace('/[^0-9X]/i', '', (string) ($catalogRow['isbn'] ?? '')));
+            $edition = strtolower(trim((string) ($catalogRow['edition'] ?? '')));
+            $sku = strtolower(trim((string) ($catalogRow['sku'] ?? '')));
+            if ($isbn !== '') {
+                $identityCounts[$isbn . '|' . $edition] = ($identityCounts[$isbn . '|' . $edition] ?? 0) + 1;
+            }
+            if ($sku !== '') {
+                $skuCounts[$sku] = ($skuCounts[$sku] ?? 0) + 1;
+            }
+        }
+        $duplicateCount = count(array_filter($identityCounts, static fn (int $count): bool => $count > 1))
+            + count(array_filter($skuCounts, static fn (int $count): bool => $count > 1));
+        $checks['duplicate_catalog'] = $duplicateCount === 0 ? $this->check('pass', 'No duplicate normalized ISBN/edition or SKU keys found.') : $this->check('blocking', $duplicateCount . ' duplicate normalized ISBN/edition or SKU group(s) require reconciliation.');
+
+        $missingAuthorCount = count(array_filter($catalogRows, static fn (array $row): bool => trim((string) ($row['author'] ?? '')) === ''));
+        $checks['catalog_author'] = $missingAuthorCount === 0
+            ? $this->check('pass', 'All book catalog rows have an author.')
+            : $this->check('warning', $missingAuthorCount . ' book catalog row(s) have no author.');
+        $unassignedBooks = $db->table('inventory_items i')
+            ->join('inventory_book_class_assignments a', 'a.inventory_item_id = i.id AND a.school_year = ' . $db->escape($year), 'left')
+            ->where('i.type', 'book')->where('i.is_active', 1)->where('a.id', null)->countAllResults();
+        $checks['book_class_assignments'] = $unassignedBooks === 0
+            ? $this->check('pass', 'All active books have explicit year/class assignments.')
+            : $this->check('warning', $unassignedBooks . ' active book(s) rely on category fallback instead of explicit class assignments.');
+
+        $malformedYearTags = $db->table('inventory_movements')->where('school_year IS NOT NULL', null, false)
+            ->where("school_year NOT REGEXP '^[0-9]{4}-[0-9]{4}$'", null, false)->countAllResults();
+        $checks['movement_year_tags'] = $malformedYearTags === 0
+            ? $this->check('pass', 'Inventory movement year tags are well formed.')
+            : $this->check('warning', $malformedYearTags . ' inventory movement(s) have malformed school-year tags.');
+
+        $legacyDistributions = $db->table('inventory_movements im')
+            ->join('student_book_issues sbi', 'sbi.distribution_movement_id = im.id', 'left')
+            ->where('im.school_year', $year)->where('im.movement_type', 'distribution')->where('sbi.id', null)
+            ->countAllResults();
+        $checks['legacy_distributions'] = $legacyDistributions === 0 ? $this->check('pass', 'Every distribution has a price-snapshotted issue.') : $this->check('blocking', $legacyDistributions . ' distribution movement(s) lack student issue evidence and cannot be priced automatically.');
+
+        $positiveStudentMovements = $db->table('inventory_movements')
+            ->where('school_year', $year)->where('student_id IS NOT NULL', null, false)->where('qty_change >', 0)
+            ->groupStart()->where('source_type !=', 'student_book_issue_reversal')->orWhere('source_type', null)->groupEnd()->countAllResults();
+        $checks['possible_returns'] = $positiveStudentMovements === 0 ? $this->check('pass', 'No unclassified positive student book movements found.') : $this->check('blocking', $positiveStudentMovements . ' positive student movement(s) look like legacy returns/corrections and require manual classification.');
+
+        $duplicateOpenings = $db->table('inventory_movements')
+            ->select('item_id')->where('school_year', $year)->where('movement_type', 'initial')->groupBy('item_id')->having('COUNT(*) > 1', null, false)->countAllResults();
+        $checks['duplicate_openings'] = $duplicateOpenings === 0 ? $this->check('pass', 'No duplicate legacy opening movements found.') : $this->check('blocking', $duplicateOpenings . ' book/item(s) have duplicate opening movements.');
+
+        $quantityMismatches = $db->query(
+            "SELECT COUNT(*) AS total FROM (
+                SELECT i.id
+                FROM inventory_items i
+                JOIN inventory_item_years iy ON iy.inventory_item_id = i.id AND iy.school_year = ?
+                LEFT JOIN inventory_movements im ON im.item_year_id = iy.id AND im.status IN ('posted','reversed')
+                WHERE i.type = 'book'
+                GROUP BY i.id, i.quantity, iy.opening_quantity
+                HAVING i.quantity != iy.opening_quantity + COALESCE(SUM(im.qty_change), 0)
+            ) mismatches",
+            [$year]
+        )->getRowArray();
+        $quantityMismatchCount = (int) ($quantityMismatches['total'] ?? 0);
+        $checks['quantity_projection'] = $quantityMismatchCount === 0
+            ? $this->check('pass', 'Book catalog quantities match the year movement ledger.')
+            : $this->check('blocking', $quantityMismatchCount . ' book quantity projection(s) disagree with the year movement ledger.');
+
+        $legacyRefunds = $db->table('refunds')->where('school_year', $year)
+            ->whereIn('status', ['Pending', 'pending', 'requested', 'Approved', 'approved', 'Partial', 'partial', 'partially_paid'])
+            ->groupStart()->where('withdrawal_calculation_id', null)->orWhere('withdrawal_calculation_id', 0)->groupEnd()
+            ->groupStart()->where('source_type', 'tuition_withdrawal')->orLike('reason', 'Withdrawal')->groupEnd()->countAllResults();
+        $checks['legacy_refunds'] = $legacyRefunds === 0 ? $this->check('pass', 'Open withdrawal refunds have calculation links.') : $this->check('blocking', $legacyRefunds . ' open withdrawal refund(s) have no versioned calculation.');
+
+        $comparisonRows = $db->query(
+            "SELECT r.id AS refund_id, r.invoice_id, r.refund_amount,
+                    r.requested_amount_cents AS stored_requested_cents,
+                    wfc.id AS calculation_id, wfc.new_refund_request_cents AS calculated_requested_cents,
+                    wfc.status AS calculation_status
+               FROM refunds r
+          LEFT JOIN withdrawal_financial_calculations wfc ON wfc.id = r.withdrawal_calculation_id
+              WHERE r.school_year = ?
+                AND (r.source_type = 'tuition_withdrawal' OR r.reason LIKE '%Withdrawal%')
+                AND LOWER(COALESCE(r.status,'')) IN ('pending','requested','approved','partial','partially_paid')
+           ORDER BY r.id",
+            [$year]
+        )->getResultArray();
+        $comparisonDifferences = 0;
+        foreach ($comparisonRows as &$comparison) {
+            $storedCents = (int) ($comparison['stored_requested_cents'] ?? 0);
+            if ($storedCents === 0) {
+                $storedCents = (int) round(((float) ($comparison['refund_amount'] ?? 0)) * 100, 0, PHP_ROUND_HALF_UP);
+            }
+            $comparison['stored_requested_cents'] = $storedCents;
+            $comparison['difference_cents'] = $comparison['calculation_id'] === null
+                ? null
+                : $storedCents - (int) ($comparison['calculated_requested_cents'] ?? 0);
+            if ($comparison['difference_cents'] !== null && $comparison['difference_cents'] !== 0) {
+                $comparisonDifferences++;
+            }
+        }
+        unset($comparison);
+        $checks['refund_comparison'] = $comparisonDifferences === 0
+            ? $this->check('pass', 'Linked open refund requests match their versioned calculations.')
+            : $this->check('blocking', $comparisonDifferences . ' linked open refund request(s) differ from their calculation snapshot.');
+
+        $duplicateInvoices = $db->query(
+            "SELECT COUNT(*) AS total FROM (
+                SELECT parent_id FROM invoices WHERE school_year = ?
+                AND LOWER(COALESCE(status,'')) NOT IN ('void','voided','cancelled','canceled')
+                GROUP BY parent_id HAVING COUNT(*) > 1
+            ) duplicates",
+            [$year]
+        )->getRowArray();
+        $duplicateInvoiceCount = (int) ($duplicateInvoices['total'] ?? 0);
+        $checks['duplicate_invoices'] = $duplicateInvoiceCount === 0 ? $this->check('pass', 'No parent has multiple active invoices.') : $this->check('blocking', $duplicateInvoiceCount . ' parent(s) have multiple active invoices and require review.');
+
+        $blocking = count(array_filter($checks, static fn (array $check): bool => $check['severity'] === 'blocking'));
+        $report = ['school_year' => $year, 'generated_at' => date('Y-m-d H:i:s'), 'ready_to_enable' => $blocking === 0, 'blocking_count' => $blocking, 'checks' => $checks, 'open_refund_comparison' => $comparisonRows];
+        if (CLI::getOption('json') !== null) {
+            CLI::write(json_encode($report, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
+            return;
+        }
+        CLI::write('Withdrawal and inventory audit for ' . $year, 'yellow');
+        foreach ($checks as $name => $check) {
+            $color = $check['severity'] === 'blocking' ? 'red' : ($check['severity'] === 'warning' ? 'yellow' : 'green');
+            CLI::write(strtoupper($check['severity']) . ' ' . $name . ': ' . $check['message'], $color);
+        }
+        CLI::write($blocking === 0 ? 'READY TO ENABLE' : 'DO NOT ENABLE — blockers remain', $blocking === 0 ? 'green' : 'red');
+    }
+
+    private function check(string $severity, string $message): array
+    {
+        return ['severity' => $severity, 'message' => $message];
+    }
+}

app/Config/App.php

@@ -215,4 +215,16 @@ class App extends BaseConfig
     // Sessions (also in App.php)
     public string $sessionCookieName = '__Host-ci_session';
     public bool   $sessionRegenerateDestroy = true;
+
+    public function __construct()
+    {
+        parent::__construct();
+        $isProduction = ENVIRONMENT === 'production';
+        $this->forceGlobalSecureRequests = $isProduction;
+        $this->cookieSecure = $isProduction;
+        if (! $isProduction) {
+            $this->cookiePrefix = '';
+            $this->sessionCookieName = 'ci_session';
+        }
+    }
 }

app/Config/Autoload.php

@@ -98,6 +98,6 @@ class Autoload extends AutoloadConfig
      *
      * @var list<string>
      */
-    public $helpers = ['url', 'form', 'pbkdf2', 'document', 'time', 'api']; 
+    public $helpers = ['url', 'form', 'pbkdf2', 'document', 'time', 'api', 'global_config', 'student_status']; 
     
 }

app/Config/Cache.php

@@ -168,4 +168,12 @@ class Cache extends BaseConfig
         'redis'     => RedisHandler::class,
         'wincache'  => WincacheHandler::class,
     ];
+
+    public function __construct()
+    {
+        if (ENVIRONMENT === 'testing') {
+            $this->storePath         = WRITEPATH . 'cache/testing/';
+            $this->file['storePath'] = WRITEPATH . 'cache/testing/';
+        }
+    }
 }

app/Config/Commands.php

@@ -16,11 +16,12 @@ class Commands extends BaseService
             \App\Commands\CleanupPasswordResets::class,
             \App\Commands\ConfigUpdate::class,
             \App\Commands\DeleteInactiveUsers::class,
+            \App\Commands\RecalculateInvoices::class,
             \App\Commands\SendAbsenteesSummary::class,
             \App\Commands\SendLatesSummary::class,
             \App\Commands\SendMonthlyPaymentNotifications::class,
+            \App\Commands\SendRegistrationOpeningEmail::class,
             \App\Commands\SendTestPaymentNotification::class,
-            \App\Commands\SyncPaypalPayments::class,
             \App\Commands\RecalculateAttendance::class,
         ];
 
@@ -30,4 +31,4 @@ class Commands extends BaseService
             }
         }
     }
-}
+}

app/Config/Constants.php

@@ -25,6 +25,19 @@ defined('APP_NAMESPACE') || define('APP_NAMESPACE', 'App');
  */
 defined('COMPOSER_PATH') || define('COMPOSER_PATH', ROOTPATH . 'vendor/autoload.php');
 
+/*
+ | --------------------------------------------------------------------------
+ | Test Support Path
+ | --------------------------------------------------------------------------
+ |
+ | Spark may be run with CI_ENVIRONMENT=testing before CodeIgniter's PHPUnit
+ | bootstrap has had a chance to define SUPPORTPATH. The framework autoloader
+ | expects this constant when that environment flag is present.
+ */
+if (! defined('SUPPORTPATH') && defined('TESTPATH') && is_dir(TESTPATH . '_support')) {
+    define('SUPPORTPATH', realpath(TESTPATH . '_support') . DIRECTORY_SEPARATOR);
+}
+
 /*
  |--------------------------------------------------------------------------
  | Timing Constants

app/Config/ContentSecurityPolicy.php

@@ -47,28 +47,63 @@ class ContentSecurityPolicy extends BaseConfig
      *
      * @var list<string>|string|null
      */
-    public $defaultSrc;
+    public $defaultSrc = 'self';
 
     /**
      * Lists allowed scripts' URLs.
      *
      * @var list<string>|string
      */
-    public $scriptSrc = 'self';
+    public $scriptSrc = [
+        'self',
+        'unsafe-inline',
+        'https://cdn.jsdelivr.net',
+        'https://code.jquery.com',
+        'https://cdnjs.cloudflare.com',
+    ];
 
     /**
      * Lists allowed stylesheets' URLs.
      *
      * @var list<string>|string
      */
-    public $styleSrc = 'self';
+    public $styleSrc = [
+        'self',
+        'unsafe-inline',
+        'https://cdn.jsdelivr.net',
+        'https://fonts.googleapis.com',
+        'https://cdnjs.cloudflare.com',
+    ];
+
+    /**
+     * Lists allowed stylesheet element URLs.
+     *
+     * @var list<string>|string
+     */
+    public $styleSrcElem = [
+        'self',
+        'unsafe-inline',
+        'https://cdn.jsdelivr.net',
+        'https://fonts.googleapis.com',
+        'https://cdnjs.cloudflare.com',
+    ];
+
+    /**
+     * Allows inline style attributes used by legacy views.
+     *
+     * @var list<string>|string
+     */
+    public $styleSrcAttr = [
+        'self',
+        'unsafe-inline',
+    ];
 
     /**
      * Defines the origins from which images can be loaded.
      *
      * @var list<string>|string
      */
-    public $imageSrc = 'self';
+    public $imageSrc = ['self', 'data:', 'https:'];
 
     /**
      * Restricts the URLs that can appear in a page's `<base>` element.
@@ -99,7 +134,13 @@ class ContentSecurityPolicy extends BaseConfig
      *
      * @var list<string>|string
      */
-    public $fontSrc;
+    public $fontSrc = [
+        'self',
+        'data:',
+        'https://fonts.gstatic.com',
+        'https://cdn.jsdelivr.net',
+        'https://cdnjs.cloudflare.com',
+    ];
 
     /**
      * Lists valid endpoints for submission from `<form>` tags.

app/Config/Cookie.php

@@ -56,6 +56,15 @@ class Cookie extends BaseConfig
      */
     public bool $secure = false;
 
+    public function __construct()
+    {
+        parent::__construct();
+        $this->secure = ENVIRONMENT === 'production';
+        if ($this->secure) {
+            $this->prefix = '__Host-';
+        }
+    }
+
     /**
      * --------------------------------------------------------------------------
      * Cookie HTTPOnly

app/Config/Cors.php

@@ -34,7 +34,7 @@ class Cors extends BaseConfig
          *   - ['http://localhost:8080']
          *   - ['https://www.example.com']
          */
-        'allowedOrigins' => ['*'], // Allow all origins for mobile apps
+        'allowedOrigins' => ['*'],
 
         /**
          * Origin regex patterns for the `Access-Control-Allow-Origin` header.
@@ -57,7 +57,7 @@ class Cors extends BaseConfig
          *
          * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials
          */
-        'supportsCredentials' => true, // Enable for mobile apps using cookies/auth
+        'supportsCredentials' => false,
 
         /**
          * Set headers to allow.

app/Config/Database.php

@@ -16,6 +16,10 @@ class Database extends Config
     {
         parent::__construct();
 
+        if (ENVIRONMENT === 'testing') {
+            $this->defaultGroup = 'tests';
+        }
+
         $this->default = [
             'DSN'      => '',
             'hostname' => env('database.default.hostname'),
@@ -25,7 +29,7 @@ class Database extends Config
             'DBDriver' => env('database.default.DBDriver', 'MySQLi'),
             'DBPrefix' => '',
             'pConnect' => false,
-            'DBDebug'  => (ENVIRONMENT !== 'development'),
+            'DBDebug'  => (ENVIRONMENT === 'development'),
             'charset'  => 'utf8',
             'DBCollat' => 'utf8_general_ci',
             'swapPre'  => '',
@@ -38,22 +42,22 @@ class Database extends Config
 
         $this->tests = [
             'DSN'      => '',
-            'hostname' => env('database.tests.hostname', env('database.default.hostname')),
-            'username' => env('database.tests.username', env('database.default.username')),
-            'password' => env('database.tests.password', env('database.default.password')),
-            'database' => env('database.tests.database', env('database.default.database')),
+            'hostname' => env('TEST_DB_HOST', env('database.tests.hostname', env('database.default.hostname'))),
+            'username' => env('TEST_DB_USER', env('database.tests.username', env('database.default.username'))),
+            'password' => env('TEST_DB_PASSWORD', env('database.tests.password', env('database.default.password'))),
+            'database' => env('TEST_DB_NAME', env('database.tests.database', 'alrahma_test')),
             'DBDriver' => env('database.tests.DBDriver', env('database.default.DBDriver', 'MySQLi')),
-            'DBPrefix' => env('database.tests.DBPrefix', 'db_'),
+            'DBPrefix' => env('database.tests.DBPrefix', ''),
             'pConnect' => false,
             'DBDebug'  => true,
-            'charset'  => 'utf8',
-            'DBCollat' => 'utf8_general_ci',
+            'charset'  => 'utf8mb4',
+            'DBCollat' => 'utf8mb4_general_ci',
             'swapPre'  => '',
             'encrypt'  => false,
             'compress' => false,
             'strictOn' => false,
             'failover' => [],
-            'port'     => (int) env('database.tests.port', env('database.default.port', 3306)),
+            'port'     => (int) env('TEST_DB_PORT', env('database.tests.port', env('database.default.port', 3306))),
         ];
     }
 }

app/Config/Email.php

@@ -6,16 +6,16 @@ use CodeIgniter\Config\BaseConfig;
 
 class Email extends BaseConfig
 {
-    public string $protocol     = 'smtp';
-    public string $SMTPHost     = 'smtp.gmail.com';
-    public string $SMTPUser     = 'alrahma.sunday.school@gmail.com';
-    public string $SMTPPass     = 'psnp emdq dykw ypul'; // Consider using ENV()
-    public int    $SMTPPort     = 465;
-    public string $SMTPCrypto   = 'ssl';           // ✅ Correct for port 465
+    public string $protocol;
+    public string $SMTPHost;
+    public string $SMTPUser;
+    public string $SMTPPass;
+    public int    $SMTPPort;
+    public string $SMTPCrypto;
 
-    public bool   $SMTPAuth     = true;
-    public int    $SMTPTimeout  = 5;
-    public bool   $SMTPKeepAlive = true;
+    public bool   $SMTPAuth;
+    public int    $SMTPTimeout;
+    public bool   $SMTPKeepAlive;
 
     public string $charset      = 'UTF-8';
     public string $mailType     = 'html';
@@ -23,4 +23,19 @@ class Email extends BaseConfig
 
     public string $newline      = "\r\n";
     public string $CRLF         = "\r\n";
-}
+
+    public function __construct()
+    {
+        parent::__construct();
+
+        $this->protocol      = (string) env('mail.protocol', env('email.protocol', 'smtp'));
+        $this->SMTPHost      = (string) env('mail.SMTPHost', env('email.SMTPHost', env('SMTP_HOST', 'smtp.gmail.com')));
+        $this->SMTPUser      = (string) env('mail.SMTPUser', env('email.SMTPUser', env('SMTP_USER', '')));
+        $this->SMTPPass      = (string) env('mail.SMTPPass', env('email.SMTPPass', env('SMTP_PASS', '')));
+        $this->SMTPPort      = (int) env('mail.SMTPPort', env('email.SMTPPort', env('SMTP_PORT', 465)));
+        $this->SMTPCrypto    = (string) env('mail.SMTPCrypto', env('email.SMTPCrypto', env('SMTP_ENCRYPTION', 'ssl')));
+        $this->SMTPAuth      = filter_var(env('mail.SMTPAuth', env('email.SMTPAuth', true)), FILTER_VALIDATE_BOOLEAN);
+        $this->SMTPTimeout   = (int) env('mail.SMTPTimeout', env('email.SMTPTimeout', 5));
+        $this->SMTPKeepAlive = filter_var(env('mail.SMTPKeepAlive', env('email.SMTPKeepAlive', true)), FILTER_VALIDATE_BOOLEAN);
+    }
+}

app/Config/Encryption.php

@@ -23,6 +23,15 @@ class Encryption extends BaseConfig
      */
     public string $key = '';
 
+    public function __construct()
+    {
+        parent::__construct();
+        $fromEnv = (string) env('encryption.key', env('ENCRYPTION_KEY', ''));
+        if ($fromEnv !== '') {
+            $this->key = $fromEnv;
+        }
+    }
+
     /**
      * --------------------------------------------------------------------------
      * Encryption Driver to Use

app/Config/Events.php

@@ -9,6 +9,7 @@ use App\Listeners\SchoolEventListener;
 use App\Listeners\AttendanceConsequenceListener;
 use App\Listeners\WhatsappInviteListener;
 use App\Listeners\BelowSixtyEmailListener;
+use App\Listeners\DecisionEmailListener;
 
 // Create an instance so we can use $this->emailService like your other handlers
 $waListener = new WhatsappInviteListener(service('emailService'));
@@ -118,6 +119,7 @@ Events::on('attendance.follow_up',   [AttendanceConsequenceListener::class, 'fol
 Events::on('attendance.final_warning', [AttendanceConsequenceListener::class, 'finalWarning']);
 Events::on('attendance.dismissal',   [AttendanceConsequenceListener::class, 'dismissal']);
 Events::on('below60.email', [BelowSixtyEmailListener::class, 'handle']);
+Events::on('below60.decision_email', [DecisionEmailListener::class, 'handle']);
 
 //Whatsapp Event listener
 Events::on('whatsapp_invites.send', [$waListener, 'handle']);

app/Config/Feature.php

@@ -27,4 +27,9 @@ class Feature extends BaseConfig
      * Use improved new auto routing instead of the default legacy version.
      */
     public bool $autoRoutesImproved = false;
+
+    /**
+     * Show the global school-year selector in authenticated admin layouts.
+     */
+    public bool $globalSchoolYearSelector = true;
 }

app/Config/Filters.php

@@ -24,11 +24,15 @@ class Filters extends BaseConfig
         'honeypot'          => Honeypot::class,
         'invalidchars'      => InvalidChars::class,
         'secureheaders'     => SecureHeaders::class,
+        'sanitizeinput'     => \App\Filters\SanitizeInputFilter::class,
+        'apiratelimit'      => \App\Filters\ApiRateLimitFilter::class,
         'auth'              => \App\Filters\AuthFilter::class, // Define the alias for your auth filter
         'apiAuth'           => \App\Filters\ApiAuthFilter::class, // JWT-based API authentication
         'cleanupScheduler'  => \App\Filters\CleanupScheduler::class,
-        'permission'        => \App\Filters\PermissionFilter::class, 
+        'permission'        => \App\Filters\PermissionFilter::class,
         'timezone'          => \App\Filters\TimezoneFilter::class,
+        'schoolYear'        => \App\Filters\RequireSchoolYearFilter::class,
+        'schoolYearWritable'=> \App\Filters\SchoolYearWritableFilter::class,
     ];
 
 
@@ -41,16 +45,31 @@ class Filters extends BaseConfig
      */
     public array $globals = [
     'before' => [
-        'timezone',
+        // Heartbeat must not load timezone preferences / settings.
+        'timezone' => ['except' => [
+            'session/ping-activity',
+            'index.php/session/ping-activity',
+            'session/ping',
+            'index.php/session/ping',
+            'session/check-timeout',
+            'index.php/session/check-timeout',
+            'session/get-timeout-config',
+            'index.php/session/get-timeout-config',
+        ]],
+        'sanitizeinput',
+        'invalidchars',
+        // Heartbeat is not a school-year write; skip writable-year DB work.
+        'schoolYearWritable' => ['except' => [
+            'session/ping-activity',
+            'index.php/session/ping-activity',
+            'session/ping',
+            'index.php/session/ping',
+            'session/check-timeout',
+            'index.php/session/check-timeout',
+            'session/get-timeout-config',
+            'index.php/session/get-timeout-config',
+        ]],
         'csrf' => ['except' => [
-            // Webhooks / integrations
-            'api/paypal-webhook',
-            'index.php/api/paypal-webhook',
-
-            // WhatsApp membership management (legacy allowances retained)
-            'whatsapp/update-membership',
-            'index.php/whatsapp/update-membership',
-
             // Attendance management AJAX saves
             'attendance/update',
             'index.php/attendance/update',
@@ -77,9 +96,16 @@ class Filters extends BaseConfig
             // Badge PDF generation posts (handled by auth; allow multiple submits without reload)
             'badge',
             'index.php/badge',
+
+            // Session keep-alive endpoint updates only the current browser session.
+            'session/ping',
+            'index.php/session/ping',
+            'session/ping-activity',
+            'index.php/session/ping-activity',
         ]],
     ],
     'after' => [
+        'secureheaders',
         'toolbar',
         'cleanupScheduler' => ['except' => ['cleanup/*']],
     ],
@@ -112,7 +138,7 @@ class Filters extends BaseConfig
      * @var array<string, array<string, list<string>>>
      */
     public array $filters = [
-        
+        'apiratelimit' => ['before' => ['api/*', 'index.php/api/*']],
     ];
 
 }

app/Config/Format.php

@@ -9,6 +9,7 @@ use CodeIgniter\Format\XMLFormatter;
 
 class Format extends BaseConfig
 {
+    public int $jsonEncodeDepth = 512;
     /**
      * --------------------------------------------------------------------------
      * Available Response Formats

app/Config/PaypalConfig.php

@@ -1,13 +0,0 @@
-<?php
-
-namespace Config;
-
-use CodeIgniter\Config\BaseConfig;
-
-class PaypalConfig extends BaseConfig
-{
-    // PayPal API Credentials
-    public $paypalClientId = 'YOUR_PAYPAL_CLIENT_ID';
-    public $paypalSecret = 'YOUR_PAYPAL_SECRET';
-    public $paypalMode = 'sandbox'; // Change to 'live' when moving to production
-}

app/Config/Routes.php

@@ -47,6 +47,8 @@ $routes->setAutoRoute(false);
  * --------------------------------------------------------------------
  */
 $routes->post('api/proofread', 'ProofreadController::check', ['filter' => 'auth']);
+$routes->post('school-year/select', 'View\SchoolYearSelectionController::select', ['filter' => 'auth']);
+$routes->post('school-year/reset', 'View\SchoolYearSelectionController::reset', ['filter' => 'auth']);
 
 /*
  * --------------------------------------------------------------------
@@ -105,6 +107,28 @@ $routes->post('student/score-card', 'View\StudentController::scoreCard');
 $routes->get('student/score-card', 'View\StudentController::scoreCardIndex');
 $routes->get('student/score-card/list', 'View\StudentController::scoreCardList');
 $routes->get('administrator/student-score-card', 'View\StudentController::scoreCardAdmin');
+$enrollmentAdminFilter = 'auth:admin|administrator|principal|vice_principal|vice principal';
+$routes->get('administrator/enrollment-admin', 'View\EnrollmentAdminController::dashboard', ['filter' => $enrollmentAdminFilter]);
+$routes->get('administrator/enrollment-admin/email-preview', 'View\EnrollmentAdminController::previewEmail', ['filter' => $enrollmentAdminFilter]);
+$routes->post('administrator/enrollment-admin/approve-launch', 'View\EnrollmentAdminController::approveLaunch', ['filter' => $enrollmentAdminFilter]);
+$routes->post('administrator/enrollment-admin/send-registration-emails', 'View\EnrollmentAdminController::sendRegistrationEmails', ['filter' => $enrollmentAdminFilter]);
+$routes->post('administrator/enrollment-admin/flags/(:num)/resolve', 'View\EnrollmentAdminController::resolveFlag/$1', ['filter' => $enrollmentAdminFilter]);
+$routes->post('administrator/enrollment-admin/flags/(:num)/assign-class', 'View\EnrollmentAdminController::assignClass/$1', ['filter' => $enrollmentAdminFilter]);
+$routes->post('administrator/enrollment-admin/flags/(:num)/makeup-promotion', 'View\EnrollmentAdminController::confirmMakeupPromotion/$1', ['filter' => $enrollmentAdminFilter]);
+$routes->post('administrator/enrollment-admin/flags/(:num)/approve-exception', 'View\EnrollmentAdminController::approveException/$1', ['filter' => $enrollmentAdminFilter]);
+$routes->post('administrator/enrollment-admin/exceptions/create', 'View\EnrollmentAdminController::createException', ['filter' => $enrollmentAdminFilter]);
+$routes->post('administrator/enrollment-admin/exceptions/(:num)/revoke', 'View\EnrollmentAdminController::revokeException/$1', ['filter' => $enrollmentAdminFilter]);
+$routes->get('administrator/financial-aid', 'Administrator\FinancialAidController::index', ['filter' => 'auth:admin|administrator|principal|oversee_financial_aid']);
+$routes->get('administrator/financial-aid/(:num)', 'Administrator\FinancialAidController::show/$1', ['filter' => 'auth:admin|administrator|principal|oversee_financial_aid']);
+$routes->post('administrator/financial-aid/(:num)/estimate', 'Administrator\FinancialAidController::estimate/$1', ['filter' => 'auth:admin|administrator|principal|oversee_financial_aid']);
+$routes->post('administrator/financial-aid/(:num)/approve', 'Administrator\FinancialAidController::approve/$1', ['filter' => 'auth:admin|administrator|principal|oversee_financial_aid']);
+$routes->post('administrator/financial-aid/(:num)/deny', 'Administrator\FinancialAidController::deny/$1', ['filter' => 'auth:admin|administrator|principal|oversee_financial_aid']);
+$withdrawalFinancialFilter = 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal';
+$routes->get('administrator/withdrawals/(:num)/review', 'Administrator\WithdrawalFinancialController::review/$1', ['filter' => $withdrawalFinancialFilter]);
+$routes->post('administrator/withdrawals/(:num)/recalculate', 'Administrator\WithdrawalFinancialController::recalculate/$1', ['filter' => $withdrawalFinancialFilter . ',update']);
+$routes->post('administrator/withdrawal-calculations/(:num)/confirm', 'Administrator\WithdrawalFinancialController::confirm/$1', ['filter' => $withdrawalFinancialFilter . ',update']);
+$routes->get('administrator/withdrawal-calculations/(:num)', 'Administrator\WithdrawalFinancialController::calculation/$1', ['filter' => $withdrawalFinancialFilter]);
+$routes->get('administrator/invoices/(:num)/withdrawal-calculations', 'Administrator\WithdrawalFinancialController::invoiceSummary/$1', ['filter' => $withdrawalFinancialFilter]);
 // API for report card meta (students, class sections, school years)
 $routes->get('api/printables/report-card/meta', 'View\ReportCardsController::reportCardMeta', ['filter' => 'auth']);
 $routes->get('api/printables/report-card/completeness', 'View\ReportCardsController::reportCardCompleteness', ['filter' => 'auth']);
@@ -174,6 +198,18 @@ $routes->group('administrator/subject-curriculum', ['filter' => 'auth:update_cur
     $routes->post('delete/(:num)', 'View\SubjectCurriculumController::delete/$1');
 });
 
+$routes->get('administrator/trophy',              'View\TrophyController::index',   ['filter' => 'auth:admin']);
+$routes->get('administrator/trophy/winners',      'View\TrophyController::winners', ['filter' => 'auth:admin']);
+$routes->get('administrator/trophy/final',        'View\TrophyController::final',   ['filter' => 'auth:admin']);
+
+// Certificates
+$routes->get('administrator/certificates',           'View\CertificateController::index',    ['filter' => 'auth:admin']);
+$routes->get('administrator/certificates/csrf-token', 'View\CertificateController::csrfToken', ['filter' => 'auth:admin']);
+$routes->post('administrator/certificates/generate', 'View\CertificateController::generate', ['filter' => 'auth:admin']);
+$routes->get('administrator/certificates/log',       'View\CertificateController::auditLog',  ['filter' => 'auth:admin']);
+$routes->get('administrator/certificates/reprint/(:any)', 'View\CertificateController::reprint/$1', ['filter' => 'auth:read']);
+$routes->get('verify/(:segment)',                    'View\CertificateController::verify/$1');
+
 
 
 /*
@@ -190,10 +226,11 @@ $routes->get('/classes', 'View\UserController::classes'); // Classes page route
 $routes->get('/contact', 'View\UserController::contact'); // Contact Us page route
 $routes->post('/user/login', 'AuthController::login');
 $routes->post('api/login', 'AuthController::apiLogin');
+$routes->get('admin/api/v1/admin/auth/me', 'AuthController::adminAuthMe');
 $routes->get('/welcome_back', 'View\UserController::welcomeBack');
 
 $routes->get('user/forgot_password', 'View\UserController::forgotPassword'); //display forgot password form
-//$routes->post('user/forgot_password', 'View\UserController::processForgotPassword'); //process the password forgot request
+$routes->post('user/forgot_password', 'View\UserController::processForgotPassword'); //process the password forgot request
 
 $routes->get('login', 'AuthController::loginMask');
 $routes->get(
@@ -241,19 +278,24 @@ $routes->post('administrator/remove_class_student', 'View\StudentController::rem
 // Sections auto-distribution (admin)
 $routes->get('administrator/sections/auto-distribute', 'View\StudentController::autoDistributePage');
 $routes->post('administrator/sections/auto-distribute', 'View\StudentController::autoDistributeSections');
+$routes->post('administrator/sections/distribution-draft/update', 'View\StudentController::updateDistributionDraft');
+$routes->post('administrator/sections/distribution-candidate/update', 'View\StudentController::updateDistributionCandidate');
 // Totals API for dashboard
 $routes->get('administrator/sections/promotion-totals', 'View\StudentController::promotionTotalsApi');
 
 
-$routes->get('refunds/list', 'View\RefundController::listRefunds');
-$routes->post('refunds/request', 'View\RefundController::requestRefund');
-$routes->post('refunds/approve/(:num)', 'View\RefundController::approveRefund/$1');
-$routes->post('refunds/pay/(:num)', 'View\RefundController::payRefund/$1');
-$routes->post('refunds/updateStatus/(:num)', 'View\RefundController::updateStatus/$1');
-$routes->post('refunds/processRefunds', 'View\RefundController::processRefunds');
-$routes->post('refunds/updateStatus', 'View\RefundController::updateStatus');
-$routes->post('refunds/updatePayment', 'View\RefundController::updatePayment');
-$routes->post('refunds/recalculateOverpayments', 'View\RefundController::recalculateOverpayments');
+$routes->get('refunds/list', 'View\RefundController::listRefunds', ['filter' => 'auth:view_invoice|view_financial_reports|administrator|administrative staff|principal']);
+$routes->post('refunds/request', 'View\RefundController::requestRefund', ['filter' => 'auth:create_invoice|view_financial_reports|administrator|administrative staff|principal,create']);
+$routes->post('refunds/approve/(:num)', 'View\RefundController::approveRefund/$1', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->post('refunds/pay/(:num)', 'View\RefundController::payRefund/$1', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->post('refunds/reversePayout/(:num)', 'View\RefundController::reversePayout/$1', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->post('refunds/updateStatus/(:num)', 'View\RefundController::updateStatus/$1', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->post('refunds/processRefunds', 'View\RefundController::processRefunds', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->post('refunds/updateStatus', 'View\RefundController::updateStatus', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->post('refunds/updatePayment', 'View\RefundController::updatePayment', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->post('refunds/recalculateOverpayments', 'View\RefundController::recalculateOverpayments', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->get('refunds/file/(:num)', 'View\RefundController::serveRefundFile/$1', ['filter' => 'auth:view_invoice|view_financial_reports|administrator|administrative staff|principal']);
+$routes->get('refunds/file/(:num)/(:segment)', 'View\RefundController::serveRefundFile/$1/$2', ['filter' => 'auth:view_invoice|view_financial_reports|administrator|administrative staff|principal']);
 
 
 
@@ -271,7 +313,9 @@ $routes->get('ui/style', 'View\UiController::style');
 
 
 //Timeout page after timeout
+$routes->get('session/get-timeout-config', 'View\SessionTimeoutController::getTimeoutConfig');
 $routes->get('session/check-timeout', 'View\SessionTimeoutController::checkTimeout');
+$routes->post('session/ping-activity', 'View\SessionTimeoutController::pingActivity');
 $routes->post('session/ping', 'View\SessionTimeoutController::pingActivity');
 
 
@@ -393,8 +437,8 @@ $routes->get('print-requests/file/(:segment)', 'PrintRequests::serveFile/$1', ['
 $routes->get('print-requests/file/(:segment)/(:alpha)', 'PrintRequests::serveFile/$1/$2', ['filter' => 'auth:teacher,teacher_assistant,admin']);
 $routes->get('uploads/print_requests/(:segment)', 'PrintRequests::serveFile/$1', ['filter' => 'auth:teacher,teacher_assistant,admin']);
 
-$routes->get('exam-drafts/files/teacher/(:segment)', 'View\FilesController::examDraftTeacher/$1', ['filter' => 'auth:teacher,teacher_assistant,admin']);
-$routes->get('exam-drafts/files/final/(:segment)', 'View\FilesController::examDraftFinal/$1', ['filter' => 'auth:teacher,teacher_assistant,admin']);
+$routes->get('exam-drafts/files/teacher/(:segment)', 'View\FilesController::examDraftTeacher/$1', ['filter' => 'auth:teacher,teacher_assistant,admin,administrator,principal']);
+$routes->get('exam-drafts/files/final/(:segment)', 'View\FilesController::examDraftFinal/$1', ['filter' => 'auth:teacher,teacher_assistant,admin,administrator,principal']);
 
 
 
@@ -402,6 +446,7 @@ $routes->get('exam-drafts/files/final/(:segment)', 'View\FilesController::examDr
 
 
 
+$routes->get('teacher/progress', 'ClassProgressController::history', ['filter' => 'auth:teacher,teacher_assistant']);
 $routes->get('teacher/progress/submit', 'ClassProgressController::create', ['filter' => 'auth:teacher,teacher_assistant']);
 $routes->post('teacher/progress/store', 'ClassProgressController::store', ['filter' => 'auth:teacher,teacher_assistant']);
 $routes->get('teacher/progress/history', 'ClassProgressController::history', ['filter' => 'auth:teacher,teacher_assistant']);
@@ -511,82 +556,81 @@ $routes->post('grading/below-60/email', 'View\GradingController::sendBelowSixtyE
 $routes->post('grading/below-60/status', 'View\GradingController::updateBelowSixtyStatus', ['filter' => 'auth:read']);
 $routes->get('grading/below-60/schedule', 'View\GradingController::scheduleBelowSixty', ['filter' => 'auth:read']);
 $routes->post('grading/below-60/schedule', 'View\GradingController::saveBelowSixtyMeeting', ['filter' => 'auth:read']);
+$routes->get('grading/decisions', 'View\GradingController::allDecisions', ['filter' => 'auth:read']);
+$routes->post('grading/decisions/generate', 'View\GradingController::generateAllDecisions', ['filter' => 'auth:read']);
+$routes->get('grading/below-60/decisions', 'View\GradingController::belowSixtyDecisions', ['filter' => 'auth:read']);
+$routes->post('grading/below-60/decisions/save', 'View\GradingController::saveBelowSixtyDecision', ['filter' => 'auth:read']);
+$routes->get('grading/below-60/decisions/student-details', 'View\GradingController::studentDecisionDetails', ['filter' => 'auth:read']);
+$routes->get(
+    'grading/below-60/decisions/email/preview',
+    'View\GradingController::previewBelowSixtyDecisionEmail',
+    ['filter' => 'auth:read']
+);
 
+$routes->post(
+    'grading/below-60/decisions/email',
+    'View\GradingController::sendBelowSixtyDecisionEmail',
+    ['filter' => 'auth:read']
+);
 
 // Final part
 $routes->get('grading/(:segment)/(:num)/(:num)', 'View\GradingController::show/$1/$2/$3');
 $routes->post('grading/update', 'View\GradingController::update');
 $routes->get('grading', 'View\GradingController::grading');
 $routes->post('grading/toggle-score-lock', 'View\GradingController::toggleScoreLock', ['filter' => 'auth:read']);
+$routes->get('grading/toggle-score-lock', static function () {
+    return 'GET route hit. Something is calling this route incorrectly.';
+});
 $routes->post('grading/lock-all-scores', 'View\GradingController::lockAllScores', ['filter' => 'auth:read']);
 $routes->post('grading/release-scores', 'View\GradingController::toggleParentScoresRelease', ['filter' => 'auth:read']);
 $routes->post('grading/refresh-semester-scores', 'View\GradingController::refreshSemesterScores', ['filter' => 'auth:read']);
 
 // Event admin routes
-$routes->get('administrator/events', 'View\EventController::index');
-$routes->get('administrator/events/create', 'View\EventController::create'); // show create form
-$routes->post('administrator/events/create', 'View\EventController::create'); // handle event create submission
-// Route to show form and handle POST in same controller method
-$routes->match(['get', 'post'], 'administrator/events/edit/(:num)', 'View\EventController::edit/$1');
-
-
-$routes->post('administrator/events/delete/(:num)', 'View\EventController::delete/$1'); // handle delete
-$routes->post('payment/event_charges', 'View\EventController::eventUpdate');
+$routes->get('administrator/events', 'View\EventController::index', ['filter' => 'auth:admin']);
+$routes->get('administrator/events/create', 'View\EventController::create', ['filter' => 'auth:admin']);
+$routes->post('administrator/events/create', 'View\EventController::create', ['filter' => 'auth:admin']);
+$routes->match(['get', 'post'], 'administrator/events/edit/(:num)', 'View\EventController::edit/$1', ['filter' => 'auth:admin']);
+$routes->post('administrator/events/delete/(:num)', 'View\EventController::delete/$1', ['filter' => 'auth:admin']);
+$routes->post('payment/event_charges', 'View\EventController::eventUpdate', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
 
 // Parent event participation
-$routes->get('administrator/event-charges', 'View\EventController::eventShow');
-$routes->post('administrator/event-charges/remove/(:num)', 'View\EventController::removeCharge/$1');
-$routes->post('administrator/event-charges/payment/(:num)', 'View\EventController::toggleEventPayment/$1');
-$routes->get('administrator/get-students-with-charges', 'View\EventController::getStudentsWithCharges');
+$routes->get('administrator/event-charges', 'View\EventController::eventShow', ['filter' => 'auth:view_invoice|view_financial_reports|administrator|administrative staff|principal']);
+$routes->get('administrator/event-charges/pdf', 'View\EventController::eventChargesPdf', ['filter' => 'auth:view_invoice|view_financial_reports|administrator|administrative staff|principal']);
+$routes->post('administrator/event-charges/remove/(:num)', 'View\EventController::removeCharge/$1', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->post('administrator/event-charges/payment/(:num)', 'View\EventController::toggleEventPayment/$1', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->post('administrator/event-charges/waiver/(:num)', 'View\EventController::toggleWaiverStatus/$1', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->get('administrator/get-students-with-charges', 'View\EventController::getStudentsWithCharges', ['filter' => 'auth:view_invoice|view_financial_reports|administrator|administrative staff|principal']);
 
 $routes->get('parent/events', 'View\ParentController::parentEventPage', ['filter' => 'auth:parent']);
 // parent event participation page
-$routes->post('parent/updateParticipation', 'View\ParentController::updateParticipation'); // handle parent participation updates
+$routes->post('parent/updateParticipation', 'View\ParentController::updateParticipation', ['filter' => 'auth:parent']);
 
 
 // Web View Routes for Invoices
-$routes->get('invoices/getByParent/(:num)', 'View\InvoiceController::getByParent/$1');
-$routes->get('invoices/create', 'View\InvoiceController::create');
-$routes->post('invoices/updateStatus/(:num)', 'View\InvoiceController::updateStatus/$1');
+$routes->get('invoices/getByParent/(:num)', 'View\InvoiceController::getByParent/$1', ['filter' => 'auth:parent|view_invoice|view_financial_reports|administrator|administrative staff|principal']);
+$routes->get('invoices/create', 'View\InvoiceController::create', ['filter' => 'auth:create_invoice|view_financial_reports|administrator|administrative staff|principal,create']);
+$routes->post('invoices/updateStatus/(:num)', 'View\InvoiceController::updateStatus/$1', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
 
 // app/Config/Routes.php
 
 // app/Config/Routes.php
 $routes->group('payment', ['filter' => 'auth'], static function ($routes) {
     // Read
-    $routes->get('manual_pay', 'View\PaymentController::manualPaySearch', ['filter' => 'auth:read']);
-    $routes->get('manual_pay_suggest', 'View\PaymentController::manualPaySuggest', ['filter' => 'auth:read']);
+    $routes->get('manual_pay', 'View\PaymentController::manualPaySearch', ['filter' => 'auth:view_invoice|view_payment|view_financial_reports|administrator|administrative staff|principal']);
+    $routes->get('manual_pay_suggest', 'View\PaymentController::manualPaySuggest', ['filter' => 'auth:view_invoice|view_payment|view_financial_reports|administrator|administrative staff|principal']);
 
     // Create
-    $routes->post('manual_pay', 'View\PaymentController::manualPayUpdate', ['filter' => 'auth:create']);
+    $routes->post('manual_pay', 'View\PaymentController::manualPayUpdate', ['filter' => 'auth:create_payment|create_invoice|view_financial_reports|administrator|administrative staff|principal,create']);
 
     // Update
-    $routes->post('manual_pay_edit', 'View\PaymentController::manualPayEdit', ['filter' => 'auth:update']);
-    $routes->post('manual_pay_update', 'View\PaymentController::manualPayUpdate', ['filter' => 'auth:update']);
+    $routes->post('manual_pay_edit', 'View\PaymentController::manualPayEdit', ['filter' => 'auth:update_payment|update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+    $routes->post('manual_pay_update', 'View\PaymentController::manualPayUpdate', ['filter' => 'auth:create_payment|create_invoice|view_financial_reports|administrator|administrative staff|principal,create']);
 
     // Read (serve files)
-    $routes->get('serveCheckFile/(:any)/(:any)', 'View\PaymentController::serveCheckFile/$1/$2', ['filter' => 'auth:read']);
-    $routes->get('serveCheckFile/(:any)', 'View\PaymentController::serveCheckFile/$1', ['filter' => 'auth:read']);
+    $routes->get('file/(:num)/(:segment)', 'View\PaymentController::servePaymentFile/$1/$2', ['filter' => 'auth:view_invoice|view_payment|view_financial_reports|administrator|administrative staff|principal']);
+    $routes->get('file/(:num)', 'View\PaymentController::servePaymentFile/$1', ['filter' => 'auth:view_invoice|view_payment|view_financial_reports|administrator|administrative staff|principal']);
 });
 
-
-
-// Optional: if someone opens it in the browser via GET, redirect to the search page:
-$routes->get('payment/manual_pay_update', function () {
-    return redirect()->to(site_url('payment/manual_pay'));
-});
-
-/*
-$routes->group('admin/charges', ['filter' => 'auth'], static function($routes) {
-    $routes->get('/', 'ExtraChargesController::index');
-    $routes->get('parents', 'ExtraChargesController::parentOptions'); // <-- for Select2
-    $routes->post('store', 'ExtraChargesController::store');
-    $routes->post('update/(:num)', 'ExtraChargesController::update/$1');
-    $routes->post('void/(:num)', 'ExtraChargesController::void/$1');
-});
-
-*/
-
 $routes->group('admin', ['filter' => 'auth'], static function ($routes) {
     $routes->group('charges', static function ($routes) {
         // Serve HTML page from ::page, keep ::index for API JSON
@@ -594,10 +638,12 @@ $routes->group('admin', ['filter' => 'auth'], static function ($routes) {
         $routes->get('parents',  [ExtraChargesController::class, 'parentOptions']);
         $routes->get('invoices', [ExtraChargesController::class, 'invoicesForParent']); // <-- AJAX endpoint
         $routes->get('list',     [ExtraChargesController::class, 'apiList']);
-        $routes->post('store',   [ExtraChargesController::class, 'store']);
-        $routes->post('update/(:num)', [ExtraChargesController::class, 'update/$1']);
-        $routes->post('void/(:num)',   [ExtraChargesController::class, 'void/$1']);
-        $routes->post('reverse/(:num)', [ExtraChargesController::class, 'reverse/$1']);
+        $routes->post('store', [ExtraChargesController::class, 'store'], ['filter' => 'auth:create_invoice|view_financial_reports|administrator|administrative staff|principal,create']);
+        $routes->post('update/(:num)', [ExtraChargesController::class, 'update/$1'], ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+        $routes->post('approve/(:num)', [ExtraChargesController::class, 'approve/$1'], ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+        $routes->post('apply/(:num)', [ExtraChargesController::class, 'apply/$1'], ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+        $routes->post('void/(:num)', [ExtraChargesController::class, 'void/$1'], ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+        $routes->post('reverse/(:num)', [ExtraChargesController::class, 'reverse/$1'], ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
     });
 });
 
@@ -605,14 +651,19 @@ $routes->group('admin', ['filter' => 'auth'], static function ($routes) {
 $routes->group('admin', ['filter' => 'auth'], static function ($routes) {
     $routes->get('broadcast-email', 'View\BroadcastEmailController::index');
     $routes->post('broadcast-email/send', 'View\BroadcastEmailController::send');
+    $routes->post('broadcast-email/upload-image', 'View\BroadcastEmailController::uploadImage');
 });
-$routes->post('admin/broadcast-email/upload-image', 'View\BroadcastEmailController::uploadImage');
 
 
-$routes->get('payment/financial_report', 'View\FinancialController::financialReport');
-$routes->get('financial-report/financialReportSummary', 'View\FinancialController::financialReportSummary');
-$routes->get('payment/download_csv', 'View\FinancialController::downloadCsv');
-$routes->get('reports/downloadFinancialReport', 'View\FinancialController::downloadFinancialReport');
+$routes->get('payment/financial_report', 'View\FinancialController::financialReport', ['filter' => 'auth:view_financial_reports|view_invoice|administrator|administrative staff|principal']);
+$routes->get('financial-report/financialReportSummary', 'View\FinancialController::financialReportSummary', ['filter' => 'auth:view_financial_reports|view_invoice|administrator|administrative staff|principal']);
+$routes->get('financial-report/downloadSummaryCsv', 'View\FinancialController::downloadSummaryCsv', ['filter' => 'auth:view_financial_reports|view_invoice|administrator|administrative staff|principal']);
+$routes->get('financial-report/downloadSummaryAllDetailsCsv', 'View\FinancialController::downloadSummaryAllDetailsCsv', ['filter' => 'auth:view_financial_reports|view_invoice|administrator|administrative staff|principal']);
+$routes->get('payment/download_csv', 'View\FinancialController::downloadCsv', ['filter' => 'auth:view_financial_reports|view_invoice|administrator|administrative staff|principal']);
+$routes->get('administrator/tuition-forecast', 'View\TuitionForecastController::index', ['filter' => 'auth:view_financial_reports|view_invoice|administrator|administrative staff|principal']);
+$routes->post('administrator/tuition-forecast/calculate', 'View\TuitionForecastController::calculate', ['filter' => 'auth:view_financial_reports|view_invoice|administrator|administrative staff|principal']);
+$routes->get('administrator/tuition-forecast/export', 'View\TuitionForecastController::exportCsv', ['filter' => 'auth:view_financial_reports|view_invoice|administrator|administrative staff|principal']);
+$routes->get('reports/downloadFinancialReport', 'View\FinancialController::downloadFinancialReport', ['filter' => 'auth:view_financial_reports|view_invoice|administrator|administrative staff|principal']);
 // Financial APIs (JSON)
 $routes->get('api/financial/report', 'View\FinancialController::financialReportData', ['filter' => 'auth']);
 $routes->get('api/financial/summary', 'View\FinancialController::financialReportSummaryData', ['filter' => 'auth']);
@@ -622,43 +673,44 @@ $routes->get('payment/unpaid-parents', 'View\FinancialController::unpaidParents'
 $routes->get('api/financial/unpaid-parents', 'View\FinancialController::unpaidParents', ['filter' => 'auth:view_invoice']);
 
 
-$routes->get('expenses/index', 'View\ExpenseController::index');
-$routes->get('expenses/create', 'View\ExpenseController::create');
-$routes->post('expenses/store', 'View\ExpenseController::store');
-$routes->post('expenses/updateStatus', 'View\ExpenseController::updateStatus');
+$routes->get('expenses/index', 'View\ExpenseController::index', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal']);
+$routes->get('expenses/create', 'View\ExpenseController::create', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal']);
+$routes->post('expenses/store', 'View\ExpenseController::store', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal,create']);
+$routes->post('expenses/updateStatus', 'View\ExpenseController::updateStatus', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal,update']);
 
-$routes->get('reimbursements/index', 'View\ReimbursementController::index');
-$routes->get('reimbursements/create', 'View\ReimbursementController::create');
-$routes->post('reimbursements/store', 'View\ReimbursementController::store');
-$routes->get('reimbursements/under-processing', 'View\ReimbursementController::underProcessing');
-$routes->post('reimbursements/mark-donation', 'View\ReimbursementController::markDonation');
-$routes->post('reimbursements/batch/create', 'View\ReimbursementController::createBatch');
-$routes->post('reimbursements/batch/update', 'View\ReimbursementController::updateBatchAssignment');
-$routes->post('reimbursements/batch/lock', 'View\ReimbursementController::lockBatch');
-$routes->post('reimbursements/batch/admin-file/upload', 'View\ReimbursementController::uploadBatchAdminFile');
-$routes->get('reimbursements/batch/admin-file/(:segment)', 'View\ReimbursementController::serveAdminCheckFile/$1');
-$routes->get('reimbursements/batch/admin-file/(:segment)/(:segment)', 'View\ReimbursementController::serveAdminCheckFile/$1/$2');
-$routes->post('reimbursements/batch/send', 'View\ReimbursementController::sendBatchEmail');
-$routes->get('reimbursements/batch/export', 'View\ReimbursementController::exportBatch');
-$routes->post('reimbursements/process', 'View\ReimbursementController::process');
-$routes->get('reimbursements/export', 'View\ReimbursementController::export');
-$routes->get('reimbursements', 'View\ReimbursementController::index');
+$routes->get('reimbursements/index', 'View\ReimbursementController::index', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal']);
+$routes->get('reimbursements/create', 'View\ReimbursementController::create', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal']);
+$routes->post('reimbursements/store', 'View\ReimbursementController::store', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal,create']);
+$routes->get('reimbursements/under-processing', 'View\ReimbursementController::underProcessing', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal']);
+$routes->post('reimbursements/mark-donation', 'View\ReimbursementController::markDonation', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->post('reimbursements/batch/create', 'View\ReimbursementController::createBatch', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal,create']);
+$routes->post('reimbursements/batch/update', 'View\ReimbursementController::updateBatchAssignment', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->post('reimbursements/batch/lock', 'View\ReimbursementController::lockBatch', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->post('reimbursements/batch/admin-file/upload', 'View\ReimbursementController::uploadBatchAdminFile', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->get('reimbursements/batch/admin-file/(:segment)', 'View\ReimbursementController::serveAdminCheckFile/$1', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal']);
+$routes->get('reimbursements/batch/admin-file/(:segment)/(:segment)', 'View\ReimbursementController::serveAdminCheckFile/$1/$2', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal']);
+$routes->post('reimbursements/batch/send', 'View\ReimbursementController::sendBatchEmail', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->get('reimbursements/batch/export', 'View\ReimbursementController::exportBatch', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal']);
+$routes->post('reimbursements/process', 'View\ReimbursementController::process', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->post('reimbursements/reverse/(:num)', 'View\ReimbursementController::reverse/$1', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->get('reimbursements/export', 'View\ReimbursementController::export', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal']);
+$routes->get('reimbursements', 'View\ReimbursementController::index', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal']);
 
 // Health check (upload dirs + DB timezone columns)
-$routes->get('admin/health', 'View\HealthController::index');
+$routes->get('admin/health', 'View\HealthController::index', ['filter' => 'auth:admin']);
 
 //Notifications
-$routes->get('notifications/active', 'View\NotificationsController::listActive');
-$routes->get('api/notifications/active', 'View\NotificationsController::activeNotificationsData');
-$routes->get('notifications/deleted', 'View\NotificationsController::listDeleted');
-$routes->get('api/notifications/deleted', 'View\NotificationsController::deletedNotificationsData');
-$routes->post('notifications/restore/(:num)', 'View\NotificationsController::restore/$1');
+$routes->get('notifications/active', 'View\NotificationsController::listActive', ['filter' => 'auth:admin']);
+$routes->get('api/notifications/active', 'View\NotificationsController::activeNotificationsData', ['filter' => 'auth:admin']);
+$routes->get('notifications/deleted', 'View\NotificationsController::listDeleted', ['filter' => 'auth:admin']);
+$routes->get('api/notifications/deleted', 'View\NotificationsController::deletedNotificationsData', ['filter' => 'auth:admin']);
+$routes->post('notifications/restore/(:num)', 'View\NotificationsController::restore/$1', ['filter' => 'auth:admin']);
 //$routes->post('notifications/restore/(:num)', 'View\NotificationsController::restore/$1');
 //$routes->get('notifications/mark-read/(:num)', 'View\NotificationsController::markAsRead/$1');
-$routes->get('/administrator/notifications_alerts', 'View\AdministratorController::notificationsAlerts');
-$routes->post('/administrator/notifications_alerts/save', 'View\AdministratorController::saveNotificationSubjects');
-$routes->get('/administrator/print-notifications', 'View\AdministratorController::printNotificationRecipients');
-$routes->post('/administrator/print-notifications/save', 'View\AdministratorController::savePrintNotificationRecipients');
+$routes->get('/administrator/notifications_alerts', 'View\AdministratorController::notificationsAlerts', ['filter' => 'auth:admin']);
+$routes->post('/administrator/notifications_alerts/save', 'View\AdministratorController::saveNotificationSubjects', ['filter' => 'auth:admin']);
+$routes->get('/administrator/print-notifications', 'View\AdministratorController::printNotificationRecipients', ['filter' => 'auth:admin']);
+$routes->post('/administrator/print-notifications/save', 'View\AdministratorController::savePrintNotificationRecipients', ['filter' => 'auth:admin']);
 
 
 $routes->get(
@@ -691,32 +743,24 @@ $routes->post(
     'View\InvoiceController::generateInvoice',
     ['filter' => 'auth:create_invoice']
 );
-$routes->get('/parent/invoice_payment', 'View\InvoiceController::invoicePayment'); // Route for invoice payment page
-$routes->get('invoice/pay/(:num)', 'View\InvoiceController::payInvoice/$1'); // Route for paying the invoice
-$routes->get('invoices', 'View\InvoiceController::index'); // Default route for invoices
-$routes->get('invoices/(:any)', 'View\InvoiceController::index/$1'); // Route with school year filter
-$routes->get('invoices/recalculate/(:segment)', 'View\PaymentController::recalculateInvoiceByNumber/$1', ['filter' => 'auth:update_invoice']); // Recalculate invoice totals/balance
+$routes->get('/parent/invoice_payment', 'View\InvoiceController::invoicePayment', ['filter' => 'auth:parent']); // Route for invoice payment page
+$routes->get('/parent/financial-aid', 'View\ParentFinancialAidController::index', ['filter' => 'auth:parent']);
+$routes->post('/parent/financial-aid', 'View\ParentFinancialAidController::submit', ['filter' => 'auth:parent']);
+$routes->get('invoice/pay/(:num)', 'View\InvoiceController::payInvoice/$1', ['filter' => 'auth:view_invoice|view_payment|administrator|administrative staff|principal|parent']); // Route for paying the invoice
+$routes->get('invoices', 'View\InvoiceController::index', ['filter' => 'auth:view_invoice|view_financial_reports|administrator|administrative staff|principal']); // Default route for invoices
+$routes->get('invoices/(:any)', 'View\InvoiceController::index/$1', ['filter' => 'auth:view_invoice|view_financial_reports|administrator|administrative staff|principal']); // Route with school year filter
+$routes->post('invoices/recalculate/(:segment)', 'View\PaymentController::recalculateInvoiceByNumber/$1', ['filter' => 'auth:update_invoice']); // Recalculate invoice totals/balance
 $routes->get('invoice/pdf/(:num)', 'View\InvoiceController::generatePdfInvoice/$1', ['filter' => 'auth:invoice_pdf,read']);
 
 
 // Web View Routes for Payments
-$routes->get('payments/getByParent/(:num)', 'View\PaymentController::getByParent/$1');
-$routes->get('payments/create', 'View\PaymentController::create');
-$routes->post('payments/updateBalance/(:num)', 'View\PaymentController::updateBalance/$1');
+$routes->get('payments/getByParent/(:num)', 'View\PaymentController::getByParent/$1', ['filter' => 'auth:view_invoice|view_payment|view_financial_reports|administrator|administrative staff|principal']);
+$routes->get('payments/create', 'View\PaymentController::create', ['filter' => 'auth:create_payment|create_invoice|view_financial_reports|administrator|administrative staff|principal']);
+$routes->post('payments/updateBalance/(:num)', 'View\PaymentController::updateBalance/$1', ['filter' => 'auth:update_payment|update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
 
-// Web View Routes for Payment Transactions
-$routes->get('payment_transactions/getByPayment/(:num)', 'View\PaymentTransactionController::getByPayment/$1');
-$routes->get('payment_transactions/create', 'View\PaymentTransactionController::create');
-$routes->post('payment_transactions/updateStatus/(:num)', 'View\PaymentTransactionController::updateStatus/$1');
-
-// Routes for PayPal integration
-$routes->get('payments/createPaypalPayment/(:num)', 'View\PaymentController::createPaypalPayment/$1');
-$routes->get('payments/executePaypalPayment', 'View\PaymentController::executePaypalPayment');
-$routes->get('payments/cancelPaypalPayment', 'View\PaymentController::cancelPaypalPayment');
-
-$routes->get('payments/view/(:num)', 'View\PaymentController::viewPayment/$1');
-$routes->post('payments/createPaypalPayment/(:num)', 'View\PaymentController::createPaypalPayment/$1');
-$routes->get('payment/get_enrolled_students/(:num)', 'View\PaymentController::getEnrolledStudents/$1');
+// Routes for payment pages
+$routes->get('payments/view/(:num)', 'View\PaymentController::viewPayment/$1', ['filter' => 'auth:view_invoice|view_payment|view_financial_reports|administrator|administrative staff|principal']);
+$routes->get('payment/get_enrolled_students/(:num)', 'View\PaymentController::getEnrolledStudents/$1', ['filter' => 'auth:view_invoice|view_payment|view_financial_reports|administrator|administrative staff|principal']);
 
 // Payment Notification Management
 $routes->get('payment/notification_management', 'View\PaymentNotificationController::index', ['filter' => 'auth:view_invoice']);
@@ -738,32 +782,34 @@ $routes->get('administrator/userSearch', 'View\AdministratorController::userSear
 
 $routes->get('/administrator/student_profiles', 'View\AdministratorController::studentProfiles');
 $routes->get('/administrator/parent_profiles', 'View\AdministratorController::parentProfiles');
-$routes->get('/administrator/removed_students', 'View\StudentController::removedStudents');
 $routes->get('/administrator/teacher-submissions', 'View\AdministratorController::teacherSubmissionsReport', ['filter' => 'auth:admin']);
 $routes->post('/administrator/teacher-submissions/notify', 'View\AdministratorController::sendTeacherSubmissionNotifications', ['filter' => 'auth:admin']);
 $routes->get('/administrator/exam-drafts', 'View\ExamDraftController::adminIndex', ['filter' => 'auth:admin']);
 $routes->post('/administrator/exam-drafts/review', 'View\ExamDraftController::adminReview', ['filter' => 'auth:admin']);
 $routes->post('/administrator/exam-drafts/upload-legacy', 'View\ExamDraftController::adminUploadLegacy', ['filter' => 'auth:admin']);
+$routes->get('/principal/exam-drafts', 'View\ExamDraftController::principalIndex', ['filter' => 'auth:admin']);
+$routes->post('/principal/exam-drafts/review', 'View\ExamDraftController::principalReview', ['filter' => 'auth:admin']);
+$routes->post('/principal/exam-drafts/upload-legacy', 'View\ExamDraftController::principalUploadLegacy', ['filter' => 'auth:admin']);
 
 /*
  * --------------------------------------------------------------------
  * routes for View\MessagesController
  * --------------------------------------------------------------------
  */
-$routes->get('messages', 'View\MessagesController::index');
-$routes->post('messages/send', 'View\MessagesController::send');
-$routes->get('/messages/inbox', 'View\MessagesController::inbox');
-$routes->get('/messages/sent', 'View\MessagesController::sent');
-$routes->get('/messages/drafts', 'View\MessagesController::drafts');
-$routes->get('/messages/trash', 'View\MessagesController::trash');
+$routes->get('messages', 'View\MessagesController::index', ['filter' => 'auth']);
+$routes->post('messages/send', 'View\MessagesController::send', ['filter' => 'auth']);
+$routes->get('/messages/inbox', 'View\MessagesController::inbox', ['filter' => 'auth']);
+$routes->get('/messages/sent', 'View\MessagesController::sent', ['filter' => 'auth']);
+$routes->get('/messages/drafts', 'View\MessagesController::drafts', ['filter' => 'auth']);
+$routes->get('/messages/trash', 'View\MessagesController::trash', ['filter' => 'auth']);
 
 // Additional routes for handling actions like viewing, sending, deleting, etc.
-$routes->get('/messages/view/(:num)', 'View\MessagesController::view/$1');
-$routes->post('/messages/send', 'View\MessagesController::send');
-$routes->get('/messages/delete/(:num)', 'View\MessagesController::delete/$1');
-$routes->get('/messages/deletePermanent/(:num)', 'View\MessagesController::deletePermanent/$1');
-$routes->get('/messages/restore/(:num)', 'View\MessagesController::restore/$1');
-$routes->get('/messages/getRecipients/(:any)', 'View\MessagesController::getRecipients/$1');
+$routes->get('/messages/view/(:num)', 'View\MessagesController::view/$1', ['filter' => 'auth']);
+$routes->post('/messages/send', 'View\MessagesController::send', ['filter' => 'auth']);
+$routes->get('/messages/delete/(:num)', 'View\MessagesController::delete/$1', ['filter' => 'auth']);
+$routes->get('/messages/deletePermanent/(:num)', 'View\MessagesController::deletePermanent/$1', ['filter' => 'auth']);
+$routes->get('/messages/restore/(:num)', 'View\MessagesController::restore/$1', ['filter' => 'auth']);
+$routes->get('/messages/getRecipients/(:any)', 'View\MessagesController::getRecipients/$1', ['filter' => 'auth']);
 
 /*
  * --------------------------------------------------------------------
@@ -808,7 +854,7 @@ $routes->group('api/time', ['namespace' => 'App\Controllers\Api'], static functi
  * routes for View\SchoolCalendarController
  * --------------------------------------------------------------------
  */
-$routes->group('administrator', ['namespace' => 'App\Controllers'], function ($routes) {
+$routes->group('administrator', ['namespace' => 'App\Controllers', 'filter' => 'auth:admin|administrator|principal|vice_principal|vice principal'], function ($routes) {
     $routes->get('calendar_view', 'View\SchoolCalendarController::index');
     $routes->get('calendar_edit/(:num)', 'View\SchoolCalendarController::edit/$1');
     $routes->get('calendar_delete/(:num)', 'View\SchoolCalendarController::delete/$1');
@@ -825,52 +871,53 @@ $routes->group('administrator', ['namespace' => 'App\Controllers'], function ($r
  * routes for Parent Pages
  * --------------------------------------------------------------------
 */
-$routes->get('/parent/add_second_parent', 'View\ParentController::addSecondParent');
-$routes->get('/parent/viewSecondParent', 'View\ParentController::viewSecondParent');
-$routes->post('/parent/saveSecondParent', 'View\ParentController::saveSecondParent');
+$routes->get('/parent/add_second_parent', 'View\ParentController::addSecondParent', ['filter' => 'auth:parent']);
+$routes->get('/parent/viewSecondParent', 'View\ParentController::viewSecondParent', ['filter' => 'auth:parent']);
+$routes->post('/parent/saveSecondParent', 'View\ParentController::saveSecondParent', ['filter' => 'auth:parent']);
 
-$routes->get('/parent/enroll_classes', 'View\ParentController::enrollClasses');
-$routes->post('/parent/enroll_classes_handler', 'View\ParentController::enrollClassesHandler');
-$routes->get('/parent/enroll_success', 'View\ParentController::enrollSuccess');
-$routes->get('/parent/enroll_failure', 'View\ParentController::enrollFailure');
-$routes->get('/parent/payment', 'View\ParentController::viewPayments');
-$routes->get('/parent/calendar', 'View\SchoolCalendarController::calendarParentView');
-$routes->get('/parent/attendance', 'View\ParentController::attendance');
+$routes->get('/parent/enroll_classes', 'View\ParentController::enrollClasses', ['filter' => 'auth:parent']);
+$routes->post('/parent/enroll_classes_handler', 'View\ParentController::enrollClassesHandler', ['filter' => 'auth:parent']);
+$routes->get('/parent/enrollment_eligibility_refresh', 'View\ParentController::enrollmentEligibilityRefresh', ['filter' => 'auth:parent']);
+$routes->get('/parent/enroll_success', 'View\ParentController::enrollSuccess', ['filter' => 'auth:parent']);
+$routes->get('/parent/enroll_failure', 'View\ParentController::enrollFailure', ['filter' => 'auth:parent']);
+$routes->get('/parent/payment', 'View\ParentController::viewPayments', ['filter' => 'auth:parent']);
+$routes->get('/parent/calendar', 'View\SchoolCalendarController::calendarParentView', ['filter' => 'auth:parent']);
+$routes->get('/parent/attendance', 'View\ParentController::attendance', ['filter' => 'auth:parent']);
 // Parent reporting: absence/late/early dismissal
-$routes->get('parent/report-attendance', 'View\ParentAttendanceReportController::form');
-$routes->post('parent/report-attendance', 'View\ParentAttendanceReportController::submit');
-$routes->post('parent/report-attendance/update', 'View\ParentAttendanceReportController::update');
-$routes->get('attendance/parent-reports', 'View\ParentAttendanceReportController::list');
+$routes->get('parent/report-attendance', 'View\ParentAttendanceReportController::form', ['filter' => 'auth:parent']);
+$routes->post('parent/report-attendance', 'View\ParentAttendanceReportController::submit', ['filter' => 'auth:parent']);
+$routes->post('parent/report-attendance/update', 'View\ParentAttendanceReportController::update', ['filter' => 'auth:parent']);
+$routes->get('attendance/parent-reports', 'View\ParentAttendanceReportController::list', ['filter' => 'auth:admin']);
 // Admin/Teacher: early dismissal page by month
-$routes->get('attendance/early-dismissals', 'View\ParentAttendanceReportController::earlyDismissals');
+$routes->get('attendance/early-dismissals', 'View\ParentAttendanceReportController::earlyDismissals', ['filter' => 'auth:admin']);
 // Admin/Teacher: add early dismissal
-$routes->get('attendance/early-dismissals/new', 'View\ParentAttendanceReportController::addEarlyDismissalForm');
-$routes->post('attendance/early-dismissals', 'View\ParentAttendanceReportController::saveEarlyDismissal');
-$routes->post('attendance/early-dismissals/signature', 'View\ParentAttendanceReportController::uploadEarlyDismissalSignature');
+$routes->get('attendance/early-dismissals/new', 'View\ParentAttendanceReportController::addEarlyDismissalForm', ['filter' => 'auth:admin']);
+$routes->post('attendance/early-dismissals', 'View\ParentAttendanceReportController::saveEarlyDismissal', ['filter' => 'auth:admin']);
+$routes->post('attendance/early-dismissals/signature', 'View\ParentAttendanceReportController::uploadEarlyDismissalSignature', ['filter' => 'auth:admin']);
 // Parent report: client-side check API
-$routes->post('api/parent/report-attendance/check', 'View\ParentAttendanceReportController::checkExisting');
+$routes->post('api/parent/report-attendance/check', 'View\ParentAttendanceReportController::checkExisting', ['filter' => 'auth:parent']);
 
 
 $routes->get('/support', 'View\StatsController::support');
 
-$routes->get('no-kids', 'View\ParentController::noKids');
-$routes->match(['get', 'post'], 'parent/edit-student/(:num)', 'View\ParentController::editStudent/$1');
-$routes->get('parent/edit-all-students', 'View\ParentController::showEditAllStudentsModal');
-$routes->post('parent/edit-all-students', 'View\ParentController::updateAllStudents');
+$routes->get('no-kids', 'View\ParentController::noKids', ['filter' => 'auth:parent']);
+$routes->match(['get', 'post'], 'parent/edit-student/(:num)', 'View\ParentController::editStudent/$1', ['filter' => 'auth:parent']);
+$routes->get('parent/edit-all-students', 'View\ParentController::showEditAllStudentsModal', ['filter' => 'auth:parent']);
+$routes->post('parent/edit-all-students', 'View\ParentController::updateAllStudents', ['filter' => 'auth:parent']);
 
 // Show registration form with dynamic student and emergency contact blocks
-$routes->get('/parent/register_student', 'View\ParentController::registerStudentForm');
-$routes->get('/parent/child_register', 'View\ParentController::registerKidCheck');
+$routes->get('/parent/register_student', 'View\ParentController::registerStudentForm', ['filter' => 'auth:parent']);
+$routes->get('/parent/child_register', 'View\ParentController::registerKidCheck', ['filter' => 'auth:parent']);
 
 // Handle form submission (students + emergency contacts)
-$routes->post('/parent/register_student/save', 'View\ParentController::saveStudentRegistration');
-$routes->post('/parent/update_student/(:num)', 'View\ParentController::updateStudent/$1');
-$routes->get('/parent/edit_student/(:num)', 'View\ParentController::editStudent/$1');
-$routes->post('/parent/edit_student/(:num)', 'View\ParentController::editStudent/$1');
-$routes->post('/parent/delete_student/(:num)', 'View\ParentController::deleteStudent/$1');
+$routes->post('/parent/register_student/save', 'View\ParentController::saveStudentRegistration', ['filter' => 'auth:parent']);
+$routes->post('/parent/update_student/(:num)', 'View\ParentController::updateStudent/$1', ['filter' => 'auth:parent']);
+$routes->get('/parent/edit_student/(:num)', 'View\ParentController::editStudent/$1', ['filter' => 'auth:parent']);
+$routes->post('/parent/edit_student/(:num)', 'View\ParentController::editStudent/$1', ['filter' => 'auth:parent']);
+$routes->post('/parent/delete_student/(:num)', 'View\ParentController::deleteStudent/$1', ['filter' => 'auth:parent']);
 
-$routes->get('/parent/edit_emergency_contact/(:num)', 'View\ParentController::editEmergencyContact/$1');
-$routes->post('/parent/edit_emergency_contact/(:num)', 'View\ParentController::editEmergencyContact/$1');
+$routes->get('/parent/edit_emergency_contact/(:num)', 'View\ParentController::editEmergencyContact/$1', ['filter' => 'auth:parent']);
+$routes->post('/parent/edit_emergency_contact/(:num)', 'View\ParentController::editEmergencyContact/$1', ['filter' => 'auth:parent']);
 
 
 /*management navigation bar*/
@@ -881,8 +928,12 @@ $routes->get('nav-builder/delete/(:num)', 'View\NavBuilderController::delete/$1'
 $routes->post('nav-builder/reorder',      'View\NavBuilderController::reorder', ['filter' => 'auth']);
 
 
+// Teacher book distribution is the only inventory path teachers may access directly.
+$routes->get('inventory/books/distribute',  'View\InventoryController::teacherDistributeForm',  ['filter' => 'auth:view_inventory|update_inventory|administrator|administrative staff|principal|teacher|teacher_assistant']);
+$routes->post('inventory/books/distribute', 'View\InventoryController::teacherDistributeStore', ['filter' => 'auth:view_inventory|update_inventory|administrator|administrative staff|principal|teacher|teacher_assistant,update']);
+
 // Inventory routes
-$routes->group('inventory', ['filter' => 'csrf'], static function ($routes) {
+$routes->group('inventory', ['filter' => 'auth:view_inventory|administrator|administrative staff|principal'], static function ($routes) {
 
     /** ---------------------------
      *  Movements (put FIRST)
@@ -890,11 +941,11 @@ $routes->group('inventory', ['filter' => 'csrf'], static function ($routes) {
     $routes->group('movements', static function ($routes) {
         $routes->get('/',              'View\InventoryController::movementsIndex');       // /inventory/movements
         $routes->get('create',         'View\InventoryController::movementsCreate');      // /inventory/movements/create
-        $routes->post('store',         'View\InventoryController::movementsStore');       // /inventory/movements/store
+        $routes->post('store',         'View\InventoryController::movementsStore', ['filter' => 'auth:create_inventory|administrator|administrative staff|principal,create']);       // /inventory/movements/store
         $routes->get('edit/(:num)',    'View\InventoryController::movementsEdit/$1');     // /inventory/movements/edit/123
-        $routes->post('update/(:num)', 'View\InventoryController::movementsUpdate/$1');   // /inventory/movements/update/123
-        $routes->post('delete/(:num)', 'View\InventoryController::movementsDelete/$1');   // /inventory/movements/delete/123
-        $routes->post('bulk-delete',   'View\InventoryController::movementsBulkDelete');
+        $routes->post('update/(:num)', 'View\InventoryController::movementsUpdate/$1', ['filter' => 'auth:update_inventory|administrator|administrative staff|principal,update']);   // /inventory/movements/update/123
+        $routes->post('delete/(:num)', 'View\InventoryController::movementsDelete/$1', ['filter' => 'auth:delete_inventory|administrator|administrative staff|principal,delete']);   // /inventory/movements/delete/123
+        $routes->post('bulk-delete',   'View\InventoryController::movementsBulkDelete', ['filter' => 'auth:delete_inventory|administrator|administrative staff|principal,delete']);
     });
 
     /** ---------------------------
@@ -903,19 +954,21 @@ $routes->group('inventory', ['filter' => 'csrf'], static function ($routes) {
     // Summary & actions (keep these BEFORE the wildcard too)
     $routes->get('summary-all',                 'View\InventoryController::summaryAll');
     $routes->get('adjust/(:num)',               'View\InventoryController::adjustForm/$1');
-    $routes->post('adjust/(:num)',              'View\InventoryController::adjustStore/$1');
-    $routes->get('books/distribute',            'View\InventoryController::teacherDistributeForm');
-    $routes->post('books/distribute',           'View\InventoryController::teacherDistributeStore');
+    $routes->post('adjust/(:num)',              'View\InventoryController::adjustStore/$1', ['filter' => 'auth:update_inventory|administrator|administrative staff|principal,update']);
+    $routes->get('book-prices',                 'View\InventoryController::bookPrices');
+    $routes->post('book-prices',                'View\InventoryController::updateBookPrices', ['filter' => 'auth:update_inventory|administrator|administrative staff|principal,update']);
     $routes->get('classroom/audit/(:num)',      'View\InventoryController::auditClassroomForm/$1');
-    $routes->post('classroom/audit/(:num)',     'View\InventoryController::auditClassroomStore/$1');
+    $routes->post('classroom/audit/(:num)',     'View\InventoryController::auditClassroomStore/$1', ['filter' => 'auth:update_inventory|administrator|administrative staff|principal,update']);
 
     // CRUD for items/categories
     $routes->get('create/(:alpha)',             'View\InventoryController::create/$1');
-    $routes->post('store',                      'View\InventoryController::store');
+    $routes->post('store',                      'View\InventoryController::store', ['filter' => 'auth:create_inventory|administrator|administrative staff|principal,create']);
     $routes->get('edit/(:num)',                 'View\InventoryController::edit/$1');
-    $routes->post('update/(:num)',              'View\InventoryController::update/$1');
-    $routes->post('delete/(:num)',              'View\InventoryController::delete/$1');
-    $routes->post('category/save',              'View\InventoryController::saveCategory');
+    $routes->post('update/(:num)',              'View\InventoryController::update/$1', ['filter' => 'auth:update_inventory|administrator|administrative staff|principal,update']);
+    $routes->post('delete/(:num)',              'View\InventoryController::delete/$1', ['filter' => 'auth:delete_inventory|administrator|administrative staff|principal,delete']);
+    $routes->post('category/save',              'View\InventoryController::saveCategory', ['filter' => 'auth:update_inventory|administrator|administrative staff|principal,update']);
+    $routes->post('po/receive/(:num)',          'View\PurchaseOrderController::receive/$1', ['filter' => 'auth:update_inventory|administrator|administrative staff|principal,update']);
+    $routes->post('po/receipt/reverse/(:num)',  'View\PurchaseOrderController::reverseReceipt/$1', ['filter' => 'auth:update_inventory|administrator|administrative staff|principal,update']);
 
     /** ---------------------------
      *  Index & section switcher
@@ -933,15 +986,6 @@ $routes->group('inventory', ['filter' => 'csrf'], static function ($routes) {
 $routes->get('admin/enrollment/new-students', 'View\AdministratorController::showNewStudents', ['filter' => 'auth:view_new_students']);
 
 
-//Paypal transactions
-$routes->post('api/paypal-webhook', 'Api\PaypalWebhook::handle');
-$routes->get('administrator/paypal_transactions', 'View\PaypalTransactionsController::index');
-$routes->get('administrator/paypal_transactions/export', 'View\PaypalTransactionsController::exportCsv');
-$routes->get('admin/paypal-transactions', 'View\PaypalTransactionsController::index');
-$routes->get('admin/paypal-transactions/export', 'View\PaypalTransactionsController::exportCsv');
-
-
-
 //Emergency Contact
 $routes->get('administrator/emergency_contact', 'View\EmergencyContactController::index');
 $routes->get('administrator/emergency_contact/edit/(:num)', 'View\EmergencyContactController::edit/$1');
@@ -987,28 +1031,29 @@ $routes->group('communications',  static function ($routes) {
 ////////////////////////////////////////////////
 
 // app/Config/Routes.php
-$routes->group('api',  static function ($routes) {
+$routes->group('api', ['filter' => 'auth:admin'], static function ($routes) {
     // Families & Guardians API
-    $routes->get('students/(:num)/families', 'FamilyController::familiesByStudent/$1');
-    $routes->get('families/(:num)/guardians', 'FamilyController::guardiansByFamily/$1');
+    $routes->get('students/(:num)/families', 'View\FamilyController::familiesByStudent/$1');
+    $routes->get('families/(:num)/guardians', 'View\FamilyController::guardiansByFamily/$1');
 });
 
-$routes->group('families',  static function ($routes) {
+$routes->group('families', ['filter' => 'auth:admin'], static function ($routes) {
     // Allow GET for convenience in browser; keep POST for API/automation
-    $routes->match(['get', 'post'], 'bootstrap', 'FamilyController::bootstrap');   // protect with auth in production
-    $routes->post('attach-second-by-user',  'FamilyController::attachSecondByUser');
-    $routes->post('attach-second-by-email', 'FamilyController::attachSecondByEmail');
+    $routes->match(['get', 'post'], 'bootstrap', 'View\FamilyController::bootstrap');   // protect with auth in production
+    $routes->post('attach-second-by-user',  'View\FamilyController::attachSecondByUser');
+    $routes->post('attach-second-by-email', 'View\FamilyController::attachSecondByEmail');
 
-    $routes->post('set-primary-home',       'FamilyController::setPrimaryHome');
-    $routes->post('set-guardian-flags',     'FamilyController::setGuardianFlags');
-    $routes->post('unlink-guardian',        'FamilyController::unlinkGuardian');
-    $routes->post('unlink-student',         'FamilyController::unlinkStudent');
+    $routes->post('set-primary-home',       'View\FamilyController::setPrimaryHome');
+    $routes->post('set-guardian-flags',     'View\FamilyController::setGuardianFlags');
+    $routes->post('unlink-guardian',        'View\FamilyController::unlinkGuardian');
+    $routes->post('unlink-student',         'View\FamilyController::unlinkStudent');
 });
 // Allow GET for manual triggering from browser
-$routes->match(['get', 'post'], 'families/import-legacy', 'FamilyController::importSecondParentsFromLegacy');
+$routes->match(['get', 'post'], 'families/import-legacy', 'View\FamilyController::importSecondParentsFromLegacy', ['filter' => 'auth:admin']);
 
 // Admin page (protect with your auth/permission)
-$routes->group('family',  static function ($routes) {
+$routes->group('family', ['filter' => 'auth:admin'], static function ($routes) {
+    $routes->get('', 'View\FamilyAdminController::index');
     $routes->get('index', 'View\FamilyAdminController::index');
     $routes->get('search', 'View\FamilyAdminController::search');
     $routes->get('card', 'View\FamilyAdminController::card');
@@ -1016,31 +1061,31 @@ $routes->group('family',  static function ($routes) {
     $routes->post('compose-email/send', 'View\FamilyAdminController::sendComposeEmail');
 });
 // Convenience alias
-$routes->get('family', 'View\FamilyAdminController::index');
+$routes->get('family', 'View\FamilyAdminController::index', ['filter' => 'auth:admin']);
 //////////////////////////////////////////////////////////
 
 //upload files
-$routes->get('receipts/(:any)', 'View\FilesController::receipt/$1');
-$routes->get('reimbreceipts/(:any)', 'View\FilesController::reimb/$1'); // serves from writable/uploads/reimbursements
-$routes->get('early-dismissal-signatures/(:any)', 'View\FilesController::earlyDismissalSignature/$1');
+$routes->get('receipts/(:any)', 'View\FilesController::receipt/$1', ['filter' => 'auth']);
+$routes->get('reimbreceipts/(:any)', 'View\FilesController::reimb/$1', ['filter' => 'auth']); // serves from writable/uploads/reimbursements
+$routes->get('early-dismissal-signatures/(:any)', 'View\FilesController::earlyDismissalSignature/$1', ['filter' => 'auth']);
 // Expenses
-$routes->get('expenses/edit/(:num)',   'View\ExpenseController::edit/$1');
-$routes->post('expenses/update/(:num)', 'View\ExpenseController::update/$1');
+$routes->get('expenses/edit/(:num)',   'View\ExpenseController::edit/$1', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal']);
+$routes->post('expenses/update/(:num)', 'View\ExpenseController::update/$1', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal,update']);
 
 // Reimbursements
-$routes->get('reimbursements/edit/(:num)',    'View\ReimbursementController::edit/$1');
-$routes->post('reimbursements/update/(:num)', 'View\ReimbursementController::update/$1');
+$routes->get('reimbursements/edit/(:num)',    'View\ReimbursementController::edit/$1', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal']);
+$routes->post('reimbursements/update/(:num)', 'View\ReimbursementController::update/$1', ['filter' => 'auth:view_financial_reports|administrator|administrative staff|principal,update']);
 
 
 
 // app/Config/Routes.php
-$routes->get('whatsapp/', 'View\WhatsappController::index');
-$routes->post('whatsapp/sendInvites', 'View\WhatsappController::sendInvites');
-$routes->post('whatsapp/saveLink', 'View\WhatsappController::saveLink');
-$routes->get('whatsapp/parent-contacts', 'View\WhatsappController::parentContacts');
-$routes->get('whatsapp/parent-contacts-by-class', 'View\WhatsappController::parentContactsByClass');
+$routes->get('whatsapp/', 'View\WhatsappController::index', ['filter' => 'auth:admin']);
+$routes->post('whatsapp/sendInvites', 'View\WhatsappController::sendInvites', ['filter' => 'auth:admin']);
+$routes->post('whatsapp/saveLink', 'View\WhatsappController::saveLink', ['filter' => 'auth:admin']);
+$routes->get('whatsapp/parent-contacts', 'View\WhatsappController::parentContacts', ['filter' => 'auth:admin']);
+$routes->get('whatsapp/parent-contacts-by-class', 'View\WhatsappController::parentContactsByClass', ['filter' => 'auth:admin']);
 // Track WhatsApp group membership per class/parent
-$routes->match(['get', 'post'], 'whatsapp/update-membership', 'View\WhatsappController::updateMembership');
+$routes->match(['get', 'post'], 'whatsapp/update-membership', 'View\WhatsappController::updateMembership', ['filter' => 'auth:admin']);
 
 
 
@@ -1080,15 +1125,15 @@ $routes->post('admin/teacher-attendance/save-cell', 'View\AttendanceController::
 $routes->post('admin/admins-attendance/save-cell',  'View\AttendanceController::saveCell');
 
 
-$routes->get('parent/edit-emergency-contact', 'View\ParentController::editEmergencyContact');
-$routes->match(['get', 'post'], 'parent/edit-emergency-contact/(:num)', 'View\ParentController::editEmergencyContact/$1');
+$routes->get('parent/edit-emergency-contact', 'View\ParentController::editEmergencyContact', ['filter' => 'auth:parent']);
+$routes->match(['get', 'post'], 'parent/edit-emergency-contact/(:num)', 'View\ParentController::editEmergencyContact/$1', ['filter' => 'auth:parent']);
 
 
 $routes->get('rfid_coming_soon', 'View\RFIDController::rfidComingSoon');
 
 
-$routes->post('/parent/save-emergency-contact', 'View\ParentController::saveEmergencyContact');
-$routes->get('/parent/add-emergency-form', 'View\ParentController::addEmergencyForm');
+$routes->post('/parent/save-emergency-contact', 'View\ParentController::saveEmergencyContact', ['filter' => 'auth:parent']);
+$routes->get('/parent/add-emergency-form', 'View\ParentController::addEmergencyForm', ['filter' => 'auth:parent']);
 
 
 $routes->get('report/combined', 'View\ScorePredictor::combinedReport');
@@ -1096,11 +1141,11 @@ $routes->get('report/combined', 'View\ScorePredictor::combinedReport');
 
 //$routes->get('/parent/withdraw_success', 'View\ParentController::withdraw_success');
 
-$routes->get('/profile/(:num)', 'View\ParentController::profile/$1');
-$routes->post('/parent/updateProfile/(:num)', 'View\ParentController::updateProfile/$1');
+$routes->get('/profile/(:num)', 'View\ParentController::profile/$1', ['filter' => 'auth']);
+$routes->post('/parent/updateProfile/(:num)', 'View\ParentController::updateProfile/$1', ['filter' => 'auth']);
 
-$routes->get('/preferences/(:num)', 'View\PreferencesController::index/$1');
-$routes->post('/preferences/update/(:num)', 'View\PreferencesController::updatePreferences/$1');
+$routes->get('/preferences/(:num)', 'View\PreferencesController::index/$1', ['filter' => 'auth']);
+$routes->post('/preferences/update/(:num)', 'View\PreferencesController::updatePreferences/$1', ['filter' => 'auth']);
 
 // Route to view_add_edit the configuration page
 $routes->get('/configuration/configuration_view', 'View\ConfigurationController::index');
@@ -1109,6 +1154,23 @@ $routes->post('/configuration/addConfig', 'View\ConfigurationController::addConf
 $routes->match(['get', 'post'], '/configuration/editConfig/(:num)', 'View\ConfigurationController::editConfig/$1');
 $routes->post('/configuration/deleteConfig/(:num)', 'View\ConfigurationController::deleteConfig/$1');
 
+// School-year management
+$routes->group('administrator/school-years', ['filter' => 'auth:admin|administrator|principal|vice_principal'], static function ($routes) {
+    $routes->get('', 'Administrator\SchoolYearController::index');
+    $routes->post('store', 'Administrator\SchoolYearController::store');
+    $routes->post('(:num)/update', 'Administrator\SchoolYearController::update/$1');
+    $routes->post('(:num)/activate', 'Administrator\SchoolYearController::activate/$1');
+    $routes->post('(:num)/delete-draft', 'Administrator\SchoolYearController::deleteDraft/$1');
+    $routes->post('(:num)/archive', 'Administrator\SchoolYearController::archive/$1');
+    $routes->post('(:num)/reopen', 'Administrator\SchoolYearController::reopen/$1');
+    $routes->get('(:num)/closing/preview', 'Administrator\SchoolYearClosingController::preview/$1');
+    $routes->get('(:segment)/closing/preview', 'Administrator\SchoolYearClosingController::previewByName/$1');
+    $routes->post('(:num)/closing/start', 'Administrator\SchoolYearClosingController::start/$1');
+    $routes->post('(:num)/closing/execute', 'Administrator\SchoolYearClosingController::execute/$1');
+    $routes->post('(:num)/closing/complete', 'Administrator\SchoolYearClosingController::complete/$1');
+    $routes->post('(:num)/closing/cancel', 'Administrator\SchoolYearClosingController::cancel/$1');
+});
+
 // Route for Attendance Comment Templates
 $routes->get('/administrator/attendance-templates', 'View\AttendanceCommentTemplateController::index');
 $routes->get('/api/attendance-templates', 'View\AttendanceCommentTemplateController::listData');
@@ -1174,16 +1236,19 @@ $routes->get('/terms_of_service', 'View\PageController::termsOfService');
 $routes->get('/help_center', 'View\PageController::helpCenter');
 
 //payment
-$routes->get('/payment', 'View\PaymentController::redirectPage');
-$routes->get('/payment/paypal', 'View\PaymentController::paypal');
-$routes->get('/payment/manual', 'View\PaymentController::manual');
-$routes->post('/payment/manual', 'View\PaymentController::manual');
+$routes->get('/payment', 'View\PaymentController::redirectPage', ['filter' => 'auth:parent']);
+$routes->get('/payment/manual', 'View\PaymentController::manual', ['filter' => 'auth:view_invoice|view_payment|view_financial_reports|administrator|administrative staff|principal']);
+$routes->post('/payment/manual', 'View\PaymentController::manual', ['filter' => 'auth:create_payment|create_invoice|view_financial_reports|administrator|administrative staff|principal,create']);
 
 // Voucher management
-$routes->get('discounts/list', 'View\DiscountController::listVouchers');
-$routes->match(['get', 'post'], 'discount/create', 'View\DiscountController::createVoucher');
-$routes->match(['get', 'post'], 'discount/editVoucher/(:num)', 'View\DiscountController::editVoucher/$1');
-$routes->match(['get', 'post'], 'discount/apply', 'View\DiscountController::applyVoucher');
+$routes->get('discounts/list', 'View\DiscountController::listVouchers', ['filter' => 'auth:view_invoice|view_financial_reports|administrator|administrative staff|principal']);
+$routes->get('discount/create', 'View\DiscountController::createVoucher', ['filter' => 'auth:create_invoice|view_financial_reports|administrator|administrative staff|principal']);
+$routes->post('discount/create', 'View\DiscountController::createVoucher', ['filter' => 'auth:create_invoice|view_financial_reports|administrator|administrative staff|principal,create']);
+$routes->get('discount/editVoucher/(:num)', 'View\DiscountController::editVoucher/$1', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal']);
+$routes->post('discount/editVoucher/(:num)', 'View\DiscountController::editVoucher/$1', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->get('discount/voucher-form', 'View\DiscountController::applyVoucher', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal']);
+$routes->post('discount/voucher-form', 'View\DiscountController::applyVoucher', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
+$routes->post('discount/apply', 'View\DiscountController::applyVoucher', ['filter' => 'auth:update_invoice|view_financial_reports|administrator|administrative staff|principal,update']);
 
 
 
@@ -1202,7 +1267,7 @@ $routes->post('/register', 'View\RegisterController::register');
 $routes->get('/register/success', 'View\RegisterController::success');
 
 
-$routes->get('/parent/add-student-form', 'View\ParentController::addStudentForm');
+$routes->get('/parent/add-student-form', 'View\ParentController::addStudentForm', ['filter' => 'auth:parent']);
 
 
 $routes->get('/landing_page/admin_dashboard', 'View\LandingPageController::admin', ['filter' => 'auth:admin_dashboard,read']);
@@ -1215,7 +1280,6 @@ $routes->get('/access_denied', 'ErrorController::accessDenied');
 
 
 $routes->post('administrator/students/update', 'View\StudentController::editStudentData', ['filter' => 'auth:edit_student,update']);
-$routes->post('administrator/students/set-active', 'View\StudentController::setStudentActive', ['filter' => 'auth:edit_student,update']);
 
 /*
  * --------------------------------------------------------------------
@@ -1243,7 +1307,6 @@ $routes->get('flags/flags_management', 'View\FlagController::index');
 $routes->get('flags/processed_flags', 'View\FlagController::processedFlags');
 $routes->get('flags/incident_analysis', 'View\FlagController::incidentAnalysis');
 $routes->post('flags/add', 'View\FlagController::addFlag');
-$routes->get('/flags/update_state/(:num)', 'View\FlagController::updateState/$1');
 $routes->post('/flags/update_state/(:num)', 'View\FlagController::updateState/$1');
 $routes->get('flags/getStudentsByGrade/(:num)', 'View\FlagController::getStudentsByGrade/$1');
 $routes->get('flags/history', 'View\FlagController::history');
@@ -1327,14 +1390,11 @@ $routes->group('api/v1', ['filter' => 'apiAuth', 'namespace' => 'App\Controllers
     $routes->get('payments', 'View\UserController::index');
     $routes->get('payments/(:num)', 'View\SupportController::show/$1');
     $routes->get('payments/parent/(:num)', 'View\SupportController::getByParent/$1');
-    $routes->post('payments', 'View\TeacherController::create');
-    $routes->put('payments/(:num)', 'View\TeacherController::update/$1');
 
     // Invoices
     $routes->get('invoices', 'View\UserController::index');
     $routes->get('invoices/(:num)', 'View\SupportController::show/$1');
     $routes->get('invoices/parent/(:num)', 'View\SupportController::getByParent/$1');
-    $routes->put('invoices/(:num)', 'View\TeacherController::update/$1');
 
     // Notifications
     $routes->get('notifications', 'View\UserController::index');
@@ -1355,14 +1415,10 @@ $routes->group('api/v1', ['filter' => 'apiAuth', 'namespace' => 'App\Controllers
     // Expenses
     $routes->get('expenses', 'View\UserController::index');
     $routes->get('expenses/(:num)', 'View\SupportController::show/$1');
-    $routes->post('expenses', 'View\TeacherController::create');
-    $routes->put('expenses/(:num)', 'View\TeacherController::update/$1');
 
     // Reimbursements
     $routes->get('reimbursements', 'View\UserController::index');
     $routes->get('reimbursements/(:num)', 'View\SupportController::show/$1');
-    $routes->post('reimbursements', 'View\TeacherController::create');
-    $routes->put('reimbursements/(:num)', 'View\TeacherController::update/$1');
 
     // Dashboard Data
     $routes->get('dashboard', 'DashboardController::index');
@@ -1428,19 +1484,10 @@ $routes->group('api/v1', ['filter' => 'apiAuth', 'namespace' => 'App\Controllers
     // Refunds
     $routes->get('refunds', 'View\UserController::index');
     $routes->get('refunds/(:num)', 'View\SupportController::show/$1');
-    $routes->post('refunds', 'View\TeacherController::create');
-    $routes->put('refunds/(:num)', 'View\TeacherController::update/$1');
 
     // Discounts
     $routes->get('discounts', 'View\UserController::index');
     $routes->get('discounts/code/(:segment)', 'View\SupportController::getByCode/$1');
-    $routes->post('discounts/apply', 'View\SupportController::apply');
-
-    // Payment Transactions
-    $routes->get('payment-transactions', 'View\UserController::index');
-    $routes->get('payment-transactions/(:num)', 'View\SupportController::show/$1');
-    $routes->get('payment-transactions/payment/(:num)', 'View\SupportController::getByPayment/$1');
-    $routes->post('payment-transactions', 'View\TeacherController::create');
 
     // Emergency Contacts
     $routes->get('emergency-contacts', 'View\UserController::index');
@@ -1486,9 +1533,6 @@ $routes->group('api/v1', ['filter' => 'apiAuth', 'namespace' => 'App\Controllers
     // Extra Charges
     $routes->get('extra-charges', 'View\UserController::index');
     $routes->get('extra-charges/(:num)', 'View\SupportController::show/$1');
-    $routes->post('extra-charges', 'View\TeacherController::create');
-    $routes->put('extra-charges/(:num)', 'View\TeacherController::update/$1');
-    $routes->post('extra-charges/(:num)/void', 'View\SupportController::void/$1');
     $routes->get('extra-charges/parents', 'View\SupportController::parentOptions');
 
     // Flags
@@ -1527,11 +1571,6 @@ $routes->group('api/v1', ['filter' => 'apiAuth', 'namespace' => 'App\Controllers
     $routes->get('class-preparation/(:num)', 'View\SupportController::show/$1');
     $routes->post('class-preparation/(:num)/mark-printed', 'View\SupportController::markPrinted/$1');
 
-    // PayPal Transactions
-    $routes->get('paypal-transactions', 'View\UserController::index');
-    $routes->get('paypal-transactions/(:num)', 'View\SupportController::show/$1');
-    $routes->get('paypal-transactions/transaction/(:segment)', 'View\SupportController::getByTransactionId/$1');
-
     // Stats
     $routes->get('stats', 'View\UserController::index');
 
@@ -1544,7 +1583,6 @@ $routes->group('api/v1', ['filter' => 'apiAuth', 'namespace' => 'App\Controllers
 
     // Payment Notifications
     $routes->get('payment-notifications', 'View\UserController::index');
-    $routes->post('payment-notifications/send', 'View\SupportController::send');
 
     // RFID
     $routes->post('rfid/process', 'View\SupportController::process');
@@ -1561,9 +1599,6 @@ $routes->group('api/v1', ['filter' => 'apiAuth', 'namespace' => 'App\Controllers
     // Inventory
     $routes->get('inventory', 'View\UserController::index');
     $routes->get('inventory/(:num)', 'View\SupportController::show/$1');
-    $routes->post('inventory', 'View\TeacherController::create');
-    $routes->put('inventory/(:num)', 'View\TeacherController::update/$1');
-    $routes->delete('inventory/(:num)', 'View\TeacherController::delete/$1');
     $routes->get('inventory/movements', 'View\SupportController::movements');
 
     // Preferences
@@ -1615,8 +1650,6 @@ $routes->group('api/v1', ['filter' => 'apiAuth', 'namespace' => 'App\Controllers
     // Purchase Orders
     $routes->get('purchase-orders', 'View\UserController::index');
     $routes->get('purchase-orders/(:num)', 'View\SupportController::show/$1');
-    $routes->post('purchase-orders', 'View\TeacherController::create');
-    $routes->put('purchase-orders/(:num)', 'View\TeacherController::update/$1');
 
     // Grading
     $routes->get('grading/(:segment)/(:num)/(:num)', 'View\SupportController::show/$1/$2/$3');

app/Config/Services.php

@@ -36,7 +36,7 @@ class Services extends BaseService
     /**
      * Override CI Email service to enforce a global Reply-To.
      */
-    public static function email(array $config = null, bool $getShared = true)
+    public static function email(?array $config = null, bool $getShared = true)
     {
         if ($getShared) {
             return static::getSharedInstance('email', $config);
@@ -70,21 +70,26 @@ class Services extends BaseService
 
         $mail = new PHPMailer(true);
 
-        // Set up your PHPMailer configuration
+        $host = (string) env('MAIL_DEFAULT_HOST', env('SMTP_HOST', 'smtp.gmail.com'));
+        $user = (string) env('MAIL_DEFAULT_USER', env('SMTP_USER', ''));
+        $pass = (string) env('MAIL_DEFAULT_PASS', env('SMTP_PASS', ''));
+        $port = (int) env('MAIL_DEFAULT_PORT', env('SMTP_PORT', 465));
+        $encryption = strtolower((string) env('MAIL_DEFAULT_ENCRYPTION', env('SMTP_ENCRYPTION', 'ssl')));
+
         $mail->isSMTP();
-        $mail->Host = 'smtp.gmail.com'; // Your SMTP host
+        $mail->Host = $host;
         $mail->SMTPAuth = true;
-        $mail->Username = 'alrahma.sunday.school@gmail.com'; // Your email
-        $mail->Password = 'psnp emdq dykw ypul'; // Your email password
-        $mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS;
-        $mail->Port = 465;
+        $mail->Username = $user;
+        $mail->Password = $pass;
+        $mail->SMTPSecure = in_array($encryption, ['tls', 'starttls'], true)
+            ? PHPMailer::ENCRYPTION_STARTTLS
+            : PHPMailer::ENCRYPTION_SMTPS;
+        $mail->Port = $port > 0 ? $port : 465;
 
-        $mail->Timeout = 10;               // ⏱ 10-second timeout max
-        $mail->SMTPKeepAlive = false;     // Prevent hanging connections
-        $mail->SMTPDebug = 0;             // Set to 2 temporarily for debugging
-
-        $mail->SMTPDebug = 2; // You can set it to 1, 2, or 3 for increasing verbosity
-        $mail->Debugoutput = 'html'; // You can output it to 'html' or 'error_log'
+        $mail->Timeout = 10;
+        $mail->SMTPKeepAlive = false;
+        $mail->SMTPDebug = 0;
+        $mail->Debugoutput = 'error_log';
 
         return $mail;
     }
@@ -180,4 +185,341 @@ class Services extends BaseService
         $http = static::curlrequest($options);
         return new \App\Services\ApiClient($http, $apiConfig);
     }
+
+    public static function schoolYearContext(bool $getShared = true): \App\Services\SchoolYearContextService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('schoolYearContext');
+        }
+
+        return new \App\Services\SchoolYearContextService(
+            model(\App\Models\SchoolYearModel::class),
+            static::schoolYearAccessPolicy()
+        );
+    }
+
+    public static function schoolYearAccessPolicy(bool $getShared = true): \App\Services\SchoolYearAccessPolicy
+    {
+        if ($getShared) {
+            return static::getSharedInstance('schoolYearAccessPolicy');
+        }
+
+        return new \App\Services\SchoolYearAccessPolicy();
+    }
+
+    public static function schoolYearViewData(bool $getShared = true): \App\Services\SchoolYearViewDataService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('schoolYearViewData');
+        }
+
+        return new \App\Services\SchoolYearViewDataService(
+            static::schoolYearContext(),
+            static::schoolYearAccessPolicy()
+        );
+    }
+
+    public static function schoolYearWriteGuard(bool $getShared = true): \App\Services\SchoolYearWriteGuard
+    {
+        if ($getShared) {
+            return static::getSharedInstance('schoolYearWriteGuard');
+        }
+
+        return new \App\Services\SchoolYearWriteGuard();
+    }
+
+    public static function schoolYearValidation(bool $getShared = true): \App\Services\SchoolYearValidationService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('schoolYearValidation');
+        }
+
+        return new \App\Services\SchoolYearValidationService(
+            model(\App\Models\SchoolYearModel::class)
+        );
+    }
+
+    public static function staffDirectorySync(bool $getShared = true): \App\Services\StaffDirectorySyncService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('staffDirectorySync');
+        }
+
+        return new \App\Services\StaffDirectorySyncService(
+            model(\App\Models\StaffModel::class),
+            model(\App\Models\UserModel::class),
+            model(\App\Models\ConfigurationModel::class),
+            \Config\Database::connect()
+        );
+    }
+
+    public static function schoolYearManagement(bool $getShared = true): \App\Services\SchoolYearManagementService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('schoolYearManagement');
+        }
+
+        return new \App\Services\SchoolYearManagementService(
+            model(\App\Models\SchoolYearModel::class),
+            model(\App\Models\ConfigurationModel::class),
+            model(\App\Models\SchoolYearTransitionLogModel::class),
+            model(\App\Models\SchoolYearClosingBatchModel::class),
+            static::schoolYearValidation(),
+            \Config\Database::connect()
+        );
+    }
+
+    public static function schoolYearClosing(bool $getShared = true): \App\Services\SchoolYearClosingService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('schoolYearClosing');
+        }
+
+        return new \App\Services\SchoolYearClosingService(
+            model(\App\Models\SchoolYearModel::class),
+            model(\App\Models\SchoolYearClosingBatchModel::class),
+            model(\App\Models\SchoolYearClosingItemModel::class),
+            static::schoolYearManagement(),
+            \Config\Database::connect()
+        );
+    }
+
+    public static function enrollmentTransition(bool $getShared = true): \App\Services\EnrollmentTransitionService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('enrollmentTransition');
+        }
+
+        return new \App\Services\EnrollmentTransitionService(\Config\Database::connect());
+    }
+
+    public static function enrollmentStatus(bool $getShared = true): \App\Services\EnrollmentStatusService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('enrollmentStatus');
+        }
+
+        return new \App\Services\EnrollmentStatusService(\Config\Database::connect());
+    }
+
+    public static function enrollmentRegistrationEmail(bool $getShared = true): \App\Services\EnrollmentRegistrationEmailService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('enrollmentRegistrationEmail');
+        }
+
+        return new \App\Services\EnrollmentRegistrationEmailService(
+            \Config\Database::connect(),
+            static::enrollmentTransition(),
+            static::emailService(),
+            model(\App\Models\ConfigurationModel::class)
+        );
+    }
+
+    public static function financialAid(bool $getShared = true): \App\Services\FinancialAidService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('financialAid');
+        }
+
+        return new \App\Services\FinancialAidService(
+            model(\App\Models\FinancialAidRequestModel::class),
+            model(\App\Models\InvoiceModel::class),
+            model(\App\Models\DiscountVoucherModel::class),
+            model(\App\Models\DiscountUsageModel::class),
+            new \App\Libraries\InvoiceLedgerService()
+        );
+    }
+
+    public static function enrollmentWithdrawal(bool $getShared = true): \App\Services\EnrollmentWithdrawalService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('enrollmentWithdrawal');
+        }
+
+        $db = \Config\Database::connect();
+
+        return new \App\Services\EnrollmentWithdrawalService(
+            $db,
+            model(\App\Models\StudentModel::class),
+            model(\App\Models\EnrollmentModel::class),
+            model(\App\Models\StudentClassModel::class),
+            model(\App\Models\ClassSectionModel::class),
+            model(\App\Models\UserModel::class),
+            model(\App\Models\InvoiceModel::class),
+            model(\App\Models\RefundModel::class)
+        );
+    }
+
+    public static function teacherSubmissionReport(bool $getShared = true): \App\Services\TeacherSubmissionReportService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('teacherSubmissionReport');
+        }
+
+        return new \App\Services\TeacherSubmissionReportService(
+            \Config\Database::connect(),
+            model(\App\Models\ConfigurationModel::class),
+            model(\App\Models\StudentClassModel::class),
+            model(\App\Models\ClassSectionModel::class),
+            model(\App\Models\UserModel::class)
+        );
+    }
+
+    public static function administratorDashboard(bool $getShared = true): \App\Services\AdministratorDashboardService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('administratorDashboard');
+        }
+
+        return new \App\Services\AdministratorDashboardService(
+            \Config\Database::connect(),
+            model(\App\Models\UserModel::class),
+            model(\App\Models\LoginActivityModel::class)
+        );
+    }
+
+    public static function adminNotificationSettings(bool $getShared = true): \App\Services\AdminNotificationSettingsService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('adminNotificationSettings');
+        }
+
+        return new \App\Services\AdminNotificationSettingsService(
+            \Config\Database::connect(),
+            model(\App\Models\AdminNotificationSubjectModel::class)
+        );
+    }
+
+    public static function administratorDirectory(bool $getShared = true): \App\Services\AdministratorDirectoryService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('administratorDirectory');
+        }
+
+        return new \App\Services\AdministratorDirectoryService(
+            \Config\Database::connect(),
+            model(\App\Models\StudentClassModel::class),
+            model(\App\Models\UserModel::class),
+            model(\App\Models\UserRoleModel::class),
+            model(\App\Models\InvoiceModel::class),
+            model(\App\Models\StudentModel::class)
+        );
+    }
+
+    public static function gradingScore(bool $getShared = true): \App\Services\GradingScoreService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('gradingScore');
+        }
+
+        $configModel = model(\App\Models\ConfigurationModel::class);
+        $attendanceCalculator = new \App\Services\Calculators\AttendanceCalculator(
+            model(\App\Models\AttendanceRecordModel::class),
+            $configModel,
+            model(\App\Models\CalendarModel::class)
+        );
+
+        return new \App\Services\GradingScoreService(
+            \Config\Database::connect(),
+            $configModel,
+            model(\App\Models\HomeworkModel::class),
+            model(\App\Models\UserModel::class),
+            model(\App\Models\StudentClassModel::class),
+            model(\App\Models\StudentModel::class),
+            model(\App\Models\TeacherClassModel::class),
+            model(\App\Models\ClassSectionModel::class),
+            $attendanceCalculator,
+            model(\App\Models\GradingLockModel::class),
+            static::semesterScoreService(),
+            (string) $configModel->getConfig('school_year'),
+            (string) getSemester()
+        );
+    }
+
+    public static function placementGrading(bool $getShared = true): \App\Services\PlacementGradingService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('placementGrading');
+        }
+
+        $configModel = model(\App\Models\ConfigurationModel::class);
+
+        return new \App\Services\PlacementGradingService(
+            \Config\Database::connect(),
+            model(\App\Models\StudentModel::class),
+            model(\App\Models\PlacementLevelModel::class),
+            model(\App\Models\PlacementBatchModel::class),
+            model(\App\Models\PlacementScoreModel::class),
+            (string) $configModel->getConfig('school_year')
+        );
+    }
+
+    public static function belowSixty(bool $getShared = true): \App\Services\BelowSixtyService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('belowSixty');
+        }
+
+        $configModel = model(\App\Models\ConfigurationModel::class);
+
+        return new \App\Services\BelowSixtyService(
+            \Config\Database::connect(),
+            $configModel,
+            model(\App\Models\StudentModel::class),
+            model(\App\Models\StudentClassModel::class),
+            model(\App\Models\ParentMeetingScheduleModel::class),
+            model(\App\Models\UserModel::class),
+            (string) $configModel->getConfig('school_year'),
+            (string) getSemester()
+        );
+    }
+
+    public static function studentDecision(bool $getShared = true): \App\Services\StudentDecisionService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('studentDecision');
+        }
+
+        $configModel = model(\App\Models\ConfigurationModel::class);
+
+        return new \App\Services\StudentDecisionService(
+            \Config\Database::connect(),
+            $configModel,
+            model(\App\Models\StudentModel::class),
+            model(\App\Models\StudentClassModel::class),
+            model(\App\Models\UserModel::class),
+            (string) $configModel->getConfig('school_year'),
+            (string) getSemester()
+        );
+    }
+
+    public static function studentYearStatus(bool $getShared = true): \App\Services\StudentYearStatusService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('studentYearStatus');
+        }
+
+        return new \App\Services\StudentYearStatusService(
+            \Config\Database::connect(),
+            model(\App\Models\StudentYearStatusModel::class)
+        );
+    }
+
+    public static function withdrawalFinancial(bool $getShared = true): \App\Services\WithdrawalFinancialService
+    {
+        if ($getShared) {
+            return static::getSharedInstance('withdrawalFinancial');
+        }
+
+        $db = \Config\Database::connect();
+
+        return new \App\Services\WithdrawalFinancialService(
+            $db,
+            new \App\Services\WithdrawalRefundCalculator(),
+            new \App\Services\StudentBookIssueService($db),
+            new \App\Libraries\InvoiceLedgerService(),
+            new \App\Libraries\RefundEligibilityService()
+        );
+    }
 }

app/Config/Session.php

@@ -32,7 +32,7 @@ class Session extends BaseConfig
      */
     public string $cookieName = 'ci_session';
     public string $cookieDomain = ''; // Leave blank for localhost
-    public bool $cookieSecure = false; // Set to false if not using HTTPS
+    public bool $cookieSecure = false; // Forced on in production via constructor
 
     /**
      * --------------------------------------------------------------------------
@@ -101,4 +101,12 @@ class Session extends BaseConfig
      * DB Group for the database session.
      */
     public ?string $DBGroup = null;
+
+    public function __construct()
+    {
+        parent::__construct();
+        $isProduction = ENVIRONMENT === 'production';
+        $this->cookieSecure = $isProduction;
+        $this->cookieName = $isProduction ? '__Host-ci_session' : 'ci_session';
+    }
 }

app/Config/SessionTimeout.php

@@ -4,15 +4,18 @@ namespace Config;
 
 class SessionTimeout
 {
-    // Session timeout in seconds (12 hours)
-    public const TIMEOUT_DURATION = 43200;
-    
-    // Warning threshold in seconds (5 minutes before timeout)
-    public const WARNING_THRESHOLD = 42900;
-    
+    // Session timeout in seconds (30 minutes)
+    public const TIMEOUT_DURATION = 1800;
+
+    // Show warning during the last 30 seconds before timeout.
+    public const WARNING_THRESHOLD = 1770;
+
     // Server-side check interval (in seconds)
-    public const CHECK_INTERVAL = 300; // 5 minutes
-    
-    // Client-side check interval (in milliseconds)
-    public const CLIENT_CHECK_INTERVAL = 60000; // 1 minute
+    public const CHECK_INTERVAL = 30;
+
+    // Client-side session status check interval (in milliseconds)
+    public const CLIENT_CHECK_INTERVAL = 30000;
+
+    // Minimum interval between successful activity pings (in milliseconds)
+    public const CLIENT_PING_INTERVAL = 60000;
 }

app/Controllers/Admin/CompetitionWinnersController.php

@@ -54,6 +54,11 @@ class CompetitionWinnersController extends BaseController
     public function index()
     {
         $competitionModel = new CompetitionModel();
+        $schoolYear = $this->currentCompetitionSchoolYear();
+
+        if ($schoolYear !== '') {
+            $competitionModel->where('school_year', $schoolYear);
+        }
 
         $competitions = $competitionModel
             ->orderBy('id', 'DESC')
@@ -62,12 +67,13 @@ class CompetitionWinnersController extends BaseController
         return view('admin/competition_winners/index', [
             'competitions' => $competitions,
             'sectionMap'   => $this->getClassSectionMap(),
+            'schoolYear'   => $schoolYear,
         ]);
     }
 
     public function create()
     {
-        $schoolYear = $this->configModel->getConfig('school_year');
+        $schoolYear = $this->currentCompetitionSchoolYear();
         $classCounts = $this->getClassStudentCounts($schoolYear);
         $classSections = $this->classSectionModel
             ->orderBy('class_section_name', 'ASC')
@@ -81,7 +87,7 @@ class CompetitionWinnersController extends BaseController
             'errors'           => session('errors'),
             'classSections'    => $classSections,
             'classRows'        => $classRows,
-            'defaultSemester'  => $this->configModel->getConfig('semester'),
+            'defaultSemester'  => getSemester(),
             'defaultSchoolYear'=> $schoolYear,
         ]);
     }
@@ -113,7 +119,7 @@ class CompetitionWinnersController extends BaseController
             'errors'           => session('errors'),
             'classSections'    => $classSections,
             'classRows'        => $classRows,
-            'defaultSemester'  => $this->configModel->getConfig('semester'),
+            'defaultSemester'  => getSemester(),
             'defaultSchoolYear'=> $schoolYear,
         ]);
     }
@@ -385,7 +391,7 @@ class CompetitionWinnersController extends BaseController
         $semester   = session('semester');
         $schoolYear = session('school_year');
         if ($semester === null || $semester === '') {
-            $semester = $this->configModel->getConfig('semester');
+            $semester = getSemester();
         }
         if ($schoolYear === null || $schoolYear === '') {
             $schoolYear = $this->configModel->getConfig('school_year');
@@ -1088,6 +1094,11 @@ class CompetitionWinnersController extends BaseController
         return $questionCounts;
     }
 
+    private function currentCompetitionSchoolYear(): string
+    {
+        return $this->currentSchoolYearName((string) ($this->configModel->getConfig('school_year') ?? ''));
+    }
+
     private function getClassSectionMap(): array
     {
         $sections = $this->classSectionModel

app/Controllers/AdminProgressController.php

@@ -39,7 +39,13 @@ class AdminProgressController extends BaseController
 
     public function index()
     {
+        $schoolYear = trim((string) ($this->request->getGet('school_year') ?? ''));
+        if ($schoolYear === '') {
+            $schoolYear = $this->currentSchoolYearName((string) ($this->configModel->getConfig('school_year') ?? ''));
+        }
+
         $filters = [
+            'school_year' => $schoolYear,
             'from' => (string) $this->request->getGet('from'),
             'to' => (string) $this->request->getGet('to'),
             'class_section_id' => (string) $this->request->getGet('class_section_id'),
@@ -51,6 +57,8 @@ class AdminProgressController extends BaseController
             ->join('classSection cs', 'cs.class_section_id = class_progress_reports.class_section_id', 'left')
             ->join('users u', 'u.id = class_progress_reports.teacher_id', 'left');
 
+        $this->applyProgressSchoolYearScope($builder, $schoolYear);
+
         if ($filters['from']) {
             $builder->where('week_start >=', $filters['from']);
         }
@@ -91,16 +99,17 @@ class AdminProgressController extends BaseController
             $reportGroupsBySection[$sectionId] = $groups;
         }
 
-        $classSections = $this->classSectionModel->getClassSections();
-        $studentCounts = $this->studentClassModel->getStudentCountsBySection();
-        $filteredSections = array_values(array_filter($classSections, function ($section) use ($studentCounts) {
+        $classSections = $this->classSectionsForYear($schoolYear, $rows);
+        $studentCounts = $this->studentClassModel->getStudentCountsBySection($schoolYear !== '' ? $schoolYear : null);
+        $filteredSections = array_values(array_filter($classSections, function ($section) use ($studentCounts, $reportGroupsBySection) {
             $sectionId = (int) ($section['class_section_id'] ?? 0);
-            return isset($studentCounts[$sectionId]) && $studentCounts[$sectionId] > 0;
+            return (isset($studentCounts[$sectionId]) && $studentCounts[$sectionId] > 0)
+                || isset($reportGroupsBySection[$sectionId]);
         }));
 
         $filterStart = $this->normalizeDate($filters['from'] ?? '');
         $filterEnd = $this->normalizeDate($filters['to'] ?? '');
-        [$dateList, $noSchoolDays, $totalPassedDays, $passedDatesSet] = $this->buildSemesterDates();
+        [$dateList, $noSchoolDays, $totalPassedDays, $passedDatesSet] = $this->buildSemesterDates($schoolYear);
         [$expectedDays, $activeDatesSet] = $this->resolveExpectedDays(
             $dateList,
             $noSchoolDays,
@@ -132,6 +141,8 @@ class AdminProgressController extends BaseController
         return view('admin/class_progress_list', [
             'reportGroupsBySection' => $reportGroupsBySection,
             'filters' => $filters,
+            'schoolYear' => $schoolYear,
+            'schoolYears' => $this->availableSchoolYears($schoolYear),
             'classSections' => $filteredSections,
             'statusOptions' => ClassProgressController::STATUS_OPTIONS,
             'subjectSections' => ClassProgressController::SUBJECT_SECTIONS,
@@ -142,6 +153,162 @@ class AdminProgressController extends BaseController
         ]);
     }
 
+    private function classSectionsForYear(string $schoolYear, array $reportRows = []): array
+    {
+        $db = db_connect();
+
+        if ($schoolYear !== '' && $db->fieldExists('school_year', 'classSection')) {
+            $sections = $db->table('classSection')
+                ->select('classSection.class_section_id, classSection.class_section_name, classes.class_name')
+                ->join('classes', 'classSection.class_id = classes.id', 'left')
+                ->where('classSection.school_year', $schoolYear)
+                ->orderBy('classSection.class_section_name', 'ASC')
+                ->get()
+                ->getResultArray();
+        } else {
+            $sections = $this->classSectionModel->getClassSections();
+        }
+
+        $sectionsById = [];
+        foreach ($sections as $section) {
+            $sectionId = (int) ($section['class_section_id'] ?? 0);
+            if ($sectionId > 0) {
+                $sectionsById[$sectionId] = $section;
+            }
+        }
+
+        foreach ($reportRows as $row) {
+            $sectionId = (int) ($row['class_section_id'] ?? 0);
+            if ($sectionId <= 0 || isset($sectionsById[$sectionId])) {
+                continue;
+            }
+
+            $sectionsById[$sectionId] = [
+                'class_section_id' => $sectionId,
+                'class_section_name' => (string) ($row['class_section_name'] ?? ('Section #' . $sectionId)),
+                'class_name' => '',
+            ];
+        }
+
+        uasort($sectionsById, static function (array $a, array $b): int {
+            return strnatcasecmp((string) ($a['class_section_name'] ?? ''), (string) ($b['class_section_name'] ?? ''));
+        });
+
+        return array_values($sectionsById);
+    }
+
+    private function applyProgressSchoolYearScope($builder, string $schoolYear): void
+    {
+        if ($schoolYear === '') {
+            return;
+        }
+
+        $db = db_connect();
+        $hasReportYear = $db->fieldExists('school_year', 'class_progress_reports');
+        $hasSectionYear = $db->fieldExists('school_year', 'classSection');
+        [$rangeStart, $rangeEnd] = $this->semesterRangeService->getSchoolYearRange($schoolYear);
+
+        if ($hasReportYear) {
+            if ($this->hasAnyExplicitProgressSchoolYearRows()) {
+                $builder->where('class_progress_reports.school_year', $schoolYear);
+                return;
+            }
+
+            if ($rangeStart !== '' && $rangeEnd !== '') {
+                $builder
+                    ->groupStart()
+                        ->groupStart()
+                            ->where('class_progress_reports.school_year IS NULL', null, false)
+                            ->orWhere('class_progress_reports.school_year', '')
+                        ->groupEnd()
+                        ->where('class_progress_reports.week_start >=', $rangeStart)
+                        ->where('class_progress_reports.week_start <=', $rangeEnd)
+                    ->groupEnd();
+                return;
+            }
+
+            $builder->where('class_progress_reports.school_year', $schoolYear);
+            return;
+        }
+
+        if ($hasSectionYear) {
+            $builder->where('cs.school_year', $schoolYear);
+            return;
+        }
+
+        if ($rangeStart !== '' && $rangeEnd !== '') {
+            $builder
+                ->where('class_progress_reports.week_start >=', $rangeStart)
+                ->where('class_progress_reports.week_start <=', $rangeEnd);
+        }
+    }
+
+    private function hasAnyExplicitProgressSchoolYearRows(): bool
+    {
+        try {
+            return db_connect()
+                ->table('class_progress_reports')
+                ->where('school_year IS NOT NULL', null, false)
+                ->where('school_year !=', '')
+                ->limit(1)
+                ->get()
+                ->getRowArray() !== null;
+        } catch (\Throwable $e) {
+            log_message('warning', 'Unable to check explicit progress school-year rows: {message}', [
+                'message' => $e->getMessage(),
+            ]);
+            return true;
+        }
+    }
+
+    private function availableSchoolYears(string $selectedYear): array
+    {
+        $years = [];
+        $addYear = static function (mixed $value) use (&$years): void {
+            $year = trim((string) $value);
+            if ($year !== '' && ! in_array($year, $years, true)) {
+                $years[] = $year;
+            }
+        };
+
+        $addYear($selectedYear);
+        $addYear($this->currentSchoolYearName((string) ($this->configModel->getConfig('school_year') ?? '')));
+
+        $db = db_connect();
+        foreach ([
+            ['table' => 'school_years', 'column' => 'name'],
+            ['table' => 'class_progress_reports', 'column' => 'school_year'],
+            ['table' => 'classSection', 'column' => 'school_year'],
+            ['table' => 'student_class', 'column' => 'school_year'],
+        ] as $source) {
+            try {
+                if (! $db->tableExists($source['table']) || ! $db->fieldExists($source['column'], $source['table'])) {
+                    continue;
+                }
+
+                $rows = $db->table($source['table'])
+                    ->select($source['column'])
+                    ->distinct()
+                    ->where($source['column'] . ' IS NOT NULL', null, false)
+                    ->orderBy($source['column'], 'DESC')
+                    ->get()
+                    ->getResultArray();
+
+                foreach ($rows as $row) {
+                    $addYear($row[$source['column']] ?? '');
+                }
+            } catch (\Throwable $e) {
+                log_message('warning', 'Unable to load school-year options for admin progress: {message}', [
+                    'message' => $e->getMessage(),
+                ]);
+            }
+        }
+
+        rsort($years, SORT_NATURAL);
+
+        return $years;
+    }
+
     public function view($id)
     {
         $row = $this->reportModel
@@ -277,11 +444,15 @@ class AdminProgressController extends BaseController
         return checkdate($m, $d, $y) ? $value : '';
     }
 
-    protected function buildSemesterDates(): array
+    protected function buildSemesterDates(?string $schoolYear = null): array
     {
-        $schoolYear = (string) ($this->configModel->getConfig('school_year') ?? '');
-        $semester = (string) ($this->configModel->getConfig('semester') ?? '');
-        $schoolYearForRange = $schoolYear !== '' ? $schoolYear : (string) ($this->configModel->getConfig('school_year') ?? '');
+        $schoolYear = trim((string) ($schoolYear ?? ''));
+        if ($schoolYear === '') {
+            $schoolYear = $this->currentSchoolYearName((string) ($this->configModel->getConfig('school_year') ?? ''));
+        }
+
+        $semester = (string) (getSemester() ?? '');
+        $schoolYearForRange = $schoolYear !== '' ? $schoolYear : $this->currentSchoolYearName((string) ($this->configModel->getConfig('school_year') ?? ''));
         [$rangeStart, $rangeEnd] = $this->semesterRangeService->getSchoolYearRange($schoolYearForRange);
         $semesterNorm = $this->semesterRangeService->normalizeSemester($semester);
         if ($semesterNorm !== '' && $schoolYearForRange !== '') {

app/Controllers/Administrator/FinancialAidController.php

@@ -0,0 +1,193 @@
+<?php
+
+namespace App\Controllers\Administrator;
+
+use App\Controllers\BaseController;
+use App\Models\FinancialAidEstimateModel;
+use App\Models\FinancialAidRequestModel;
+use App\Models\InvoiceModel;
+use App\Models\StudentModel;
+use App\Models\UserModel;
+use InvalidArgumentException;
+use Throwable;
+
+class FinancialAidController extends BaseController
+{
+    public function index()
+    {
+        $schoolYear = $this->request->getGet('school_year');
+        $model = new FinancialAidRequestModel();
+        $builder = $model->orderBy('created_at', 'DESC');
+        if (is_string($schoolYear) && trim($schoolYear) !== '') {
+            $builder->where('school_year', trim($schoolYear));
+        }
+
+        $requests = $builder->findAll();
+        $parentIds = array_values(array_unique(array_filter(array_map('intval', array_column($requests, 'parent_id')))));
+        $parents = [];
+        if ($parentIds !== []) {
+            foreach ((new UserModel())->select('id, firstname, lastname, email')->whereIn('id', $parentIds)->findAll() as $parent) {
+                $parents[(int) $parent['id']] = $parent;
+            }
+        }
+
+        return view('administrator/financial_aid_queue', [
+            'requests' => $requests,
+            'parents' => $parents,
+            'schoolYear' => is_string($schoolYear) ? trim($schoolYear) : '',
+        ]);
+    }
+
+    public function show(int $id)
+    {
+        $request = (new FinancialAidRequestModel())->find($id);
+        if ($request === null) {
+            return redirect()->to('/administrator/financial-aid')->with('error', 'Financial aid request was not found.');
+        }
+
+        $parent = (new UserModel())->find((int) $request['parent_id']);
+        $studentIds = json_decode((string) ($request['student_ids_json'] ?? '[]'), true);
+        $studentIds = is_array($studentIds) ? array_map('intval', $studentIds) : [];
+        $students = $studentIds !== []
+            ? (new StudentModel())->whereIn('id', $studentIds)->findAll()
+            : [];
+
+        $schoolYear = (string) ($request['school_year'] ?? '');
+        $invoiceBalance = $this->invoiceBalanceForParent((int) ($request['parent_id'] ?? 0), $schoolYear);
+        $householdSize = max(1, (int) ($request['household_size'] ?? 1));
+        $householdIncome = (float) ($request['household_income'] ?? 0);
+        $requestedAmount = (float) ($request['requested_amount'] ?? 0);
+        $estimateModel = new FinancialAidEstimateModel();
+        $estimatedAid = $estimateModel->estimatedAid($invoiceBalance, $householdSize, $householdIncome);
+        $finalRebate = $estimateModel->finalRebate($invoiceBalance, $householdSize, $householdIncome, $requestedAmount);
+
+        return view('administrator/financial_aid_review', [
+            'requestRow' => $request,
+            'parent' => $parent,
+            'students' => $students,
+            'schoolYear' => $schoolYear,
+            'invoiceBalance' => $invoiceBalance,
+            'estimatedAid' => $estimatedAid,
+            'finalRebate' => $finalRebate,
+        ]);
+    }
+
+    public function estimate(int $id)
+    {
+        $request = (new FinancialAidRequestModel())->find($id);
+        if ($request === null) {
+            return $this->response->setStatusCode(404)->setJSON(['error' => 'Financial aid request was not found.']);
+        }
+
+        $householdIncomeRaw = trim((string) $this->request->getPost('household_income'));
+        $householdSizeRaw = (int) $this->request->getPost('household_size');
+        $schoolYear = (string) ($request['school_year'] ?? '');
+        $invoiceBalance = $this->invoiceBalanceForParent((int) ($request['parent_id'] ?? 0), $schoolYear);
+
+        if ($householdIncomeRaw === '' || ! is_numeric($householdIncomeRaw) || (float) $householdIncomeRaw < 0) {
+            return $this->response->setStatusCode(422)->setJSON(['error' => 'Enter a valid household income.']);
+        }
+        if ($householdSizeRaw < 1) {
+            return $this->response->setStatusCode(422)->setJSON(['error' => 'Household size must be at least 1.']);
+        }
+
+        try {
+            $estimateModel = new FinancialAidEstimateModel();
+            $householdIncome = round((float) $householdIncomeRaw, 2);
+            $estimatedAid = $estimateModel->estimatedAid($invoiceBalance, $householdSizeRaw, $householdIncome);
+            $finalRebate = $estimateModel->finalRebate(
+                $invoiceBalance,
+                $householdSizeRaw,
+                $householdIncome,
+                (float) ($request['requested_amount'] ?? 0)
+            );
+
+            return $this->response->setJSON([
+                'invoice_balance' => $invoiceBalance,
+                'estimated_aid' => $estimatedAid,
+                'final_rebate' => $finalRebate,
+                'csrf_token' => csrf_token(),
+                'csrf_hash' => csrf_hash(),
+            ]);
+        } catch (InvalidArgumentException $e) {
+            return $this->response->setStatusCode(422)->setJSON(['error' => $e->getMessage()]);
+        }
+    }
+
+    public function approve(int $id)
+    {
+        try {
+            $model = new FinancialAidRequestModel();
+            $request = $model->find($id);
+            if ($request === null) {
+                return redirect()->to('/administrator/financial-aid')->with('error', 'Financial aid request was not found.');
+            }
+            if (! in_array((string) ($request['status'] ?? ''), ['submitted', 'under_review'], true)) {
+                return redirect()->back()->with('error', 'Only open requests can be approved.');
+            }
+
+            $amount = $this->approvalAmount($request);
+            $note = trim((string) $this->request->getPost('admin_note'));
+            service('financialAid')->applyApprovedAmount($request, $amount, (int) session()->get('user_id'), $note);
+
+            return redirect()->to('/administrator/financial-aid')->with('success', 'Financial aid was approved and applied to the invoice.');
+        } catch (Throwable $e) {
+            return redirect()->back()->withInput()->with('error', $e->getMessage());
+        }
+    }
+
+    public function deny(int $id)
+    {
+        $model = new FinancialAidRequestModel();
+        $request = $model->find($id);
+        if ($request === null) {
+            return redirect()->to('/administrator/financial-aid')->with('error', 'Financial aid request was not found.');
+        }
+        if (! in_array((string) ($request['status'] ?? ''), ['submitted', 'under_review'], true)) {
+            return redirect()->back()->with('error', 'Only open requests can be denied.');
+        }
+
+        $note = trim((string) $this->request->getPost('admin_note'));
+        if ($note === '') {
+            return redirect()->back()->with('error', 'A denial note is required.');
+        }
+
+        $model->update($id, [
+            'status' => 'denied',
+            'admin_note' => $note,
+            'reviewed_by' => (int) session()->get('user_id'),
+            'reviewed_at' => date('Y-m-d H:i:s'),
+        ]);
+
+        return redirect()->to('/administrator/financial-aid')->with('success', 'Financial aid request was denied.');
+    }
+
+    private function approvalAmount(array $request): float
+    {
+        $postedAmount = trim((string) $this->request->getPost('admin_amount'));
+        if ($postedAmount !== '') {
+            return (float) $postedAmount;
+        }
+
+        return (float) ($request['requested_amount'] ?? 0);
+    }
+
+    private function invoiceBalanceForParent(int $parentId, string $schoolYear): float
+    {
+        if ($parentId <= 0 || $schoolYear === '') {
+            return 0.0;
+        }
+
+        $invoice = (new InvoiceModel())
+            ->where('parent_id', $parentId)
+            ->where('school_year', $schoolYear)
+            ->orderBy('id', 'DESC')
+            ->first();
+
+        if ($invoice === null) {
+            return 0.0;
+        }
+
+        return round((float) ($invoice['balance'] ?? 0), 2);
+    }
+}

app/Controllers/Administrator/SchoolYearClosingController.php

@@ -0,0 +1,261 @@
+<?php
+
+namespace App\Controllers\Administrator;
+
+use App\Controllers\BaseController;
+use App\Models\SchoolYearModel;
+use App\Support\SchoolYear\SchoolYearStatus;
+use Throwable;
+
+class SchoolYearClosingController extends BaseController
+{
+    public function preview(int $id)
+    {
+        try {
+            $targetId = $this->normalizeInt($this->request->getGet('target_school_year_id'));
+            $source = (new SchoolYearModel())->find($id);
+            if ($targetId === null && (string) ($source['status'] ?? '') === SchoolYearStatus::ACTIVE) {
+                $target = service('schoolYearManagement')->ensureNextDraftForClosing($id, $this->userId());
+                $targetId = (int) ($target['id'] ?? 0) ?: null;
+            }
+            $preview = service('schoolYearClosing')->preview($id, $targetId);
+            $promotionTable = $this->promotionTablePayload($preview['promotion']['rows'] ?? []);
+            $carryForwardTable = $this->carryForwardTablePayload($preview['carry_forward'] ?? []);
+            $latestBatch = service('schoolYearClosing')->latestBatch($id);
+
+            return view('school_years/closing_preview', [
+                'preview' => $preview,
+                'promotionTable' => $promotionTable,
+                'carryForwardTable' => $carryForwardTable,
+                'latestBatch' => $latestBatch,
+                'missingCarryForwardInvoices' => $this->missingCarryForwardInvoiceCount($latestBatch),
+                'schoolYears' => (new SchoolYearModel())->orderBy('name', 'DESC')->findAll(),
+            ]);
+        } catch (Throwable $e) {
+            return redirect()->to('/administrator/school-years')->with('error', $e->getMessage());
+        }
+    }
+
+    public function previewByName(string $name)
+    {
+        try {
+            $year = (new SchoolYearModel())
+                ->where('name', rawurldecode($name))
+                ->first();
+
+            if ($year === null) {
+                return redirect()->to('/administrator/school-years')->with('error', 'School year was not found.');
+            }
+
+            return $this->preview((int) $year['id']);
+        } catch (Throwable $e) {
+            return redirect()->to('/administrator/school-years')->with('error', $e->getMessage());
+        }
+    }
+
+    public function start(int $id)
+    {
+        try {
+            $targetId = $this->normalizeInt($this->request->getPost('target_school_year_id'));
+            if ($targetId === null) {
+                return redirect()->back()->with('error', 'Select a target school year.');
+            }
+
+            service('schoolYearClosing')->start($id, $targetId, $this->userId());
+            return redirect()->to('/administrator/school-years/' . $id . '/closing/preview?close_flow=1')->with('success', 'End-year process started.');
+        } catch (Throwable $e) {
+            return redirect()->back()->with('error', $e->getMessage());
+        }
+    }
+
+    public function execute(int $id)
+    {
+        try {
+            service('schoolYearClosing')->execute($id, $this->userId());
+            return redirect()->to('/administrator/school-years/' . $id . '/closing/preview?close_flow=1')->with('success', 'Carry-forward confirmed.');
+        } catch (Throwable $e) {
+            return redirect()->back()->with('error', $e->getMessage());
+        }
+    }
+
+    public function complete(int $id)
+    {
+        try {
+            service('schoolYearClosing')->complete($id, $this->userId());
+            return redirect()->to('/administrator/school-years/' . $id . '/closing/preview?close_flow=1')->with('success', 'School year ended and closed.');
+        } catch (Throwable $e) {
+            return redirect()->back()->with('error', $e->getMessage());
+        }
+    }
+
+    public function cancel(int $id)
+    {
+        try {
+            service('schoolYearClosing')->cancel($id, $this->userId());
+            return redirect()->to('/administrator/school-years')->with('success', 'End-year process cancelled.');
+        } catch (Throwable $e) {
+            return redirect()->back()->with('error', $e->getMessage());
+        }
+    }
+
+    private function normalizeInt(mixed $value): ?int
+    {
+        return is_numeric($value) && (int) $value > 0 ? (int) $value : null;
+    }
+
+    private function missingCarryForwardInvoiceCount(?array $batch): int
+    {
+        if ($batch === null || ! in_array((string) ($batch['status'] ?? ''), ['executed', 'completed'], true)) {
+            return 0;
+        }
+
+        $db = \Config\Database::connect();
+        if (! $db->tableExists('school_year_closing_items')) {
+            return 0;
+        }
+
+        return $db->table('school_year_closing_items')
+            ->where('closing_batch_id', (int) $batch['id'])
+            ->groupStart()
+                ->where('target_invoice_id', null)
+                ->orWhere('target_invoice_id', 0)
+            ->groupEnd()
+            ->countAllResults();
+    }
+
+    private function promotionTablePayload(array $rows): array
+    {
+        $allowedSorts = ['student', 'school_id', 'class', 'year_score', 'decision', 'source', 'queue', 'target', 'status'];
+        $sort = 'class';
+        $order = 'asc';
+        $perPage = 25;
+        $allowedPerPage = [10, 25, 50, 100];
+
+        usort($rows, function (array $a, array $b) use ($sort, $order): int {
+            $comparison = $this->comparePromotionRows($a, $b, $sort);
+            if ($comparison === 0 && $sort !== 'class') {
+                $comparison = $this->comparePromotionRows($a, $b, 'class');
+            }
+            if ($comparison === 0 && $sort !== 'student') {
+                $comparison = $this->comparePromotionRows($a, $b, 'student');
+            }
+            if ($comparison === 0) {
+                $comparison = ((int) ($a['student_id'] ?? 0)) <=> ((int) ($b['student_id'] ?? 0));
+            }
+
+            return $order === 'desc' ? -$comparison : $comparison;
+        });
+
+        $total = count($rows);
+
+        return [
+            'rows' => $rows,
+            'sort' => $sort,
+            'order' => $order,
+            'page' => 1,
+            'perPage' => $perPage,
+            'total' => $total,
+            'pageCount' => 1,
+            'allowedPerPage' => $allowedPerPage,
+            'from' => $total === 0 ? 0 : 1,
+            'to' => $total,
+        ];
+    }
+
+    private function comparePromotionRows(array $a, array $b, string $sort): int
+    {
+        $aValue = $this->promotionSortValue($a, $sort);
+        $bValue = $this->promotionSortValue($b, $sort);
+
+        if ($sort === 'year_score') {
+            if ($aValue === null && $bValue === null) {
+                return 0;
+            }
+            if ($aValue === null) {
+                return 1;
+            }
+            if ($bValue === null) {
+                return -1;
+            }
+
+            return $aValue <=> $bValue;
+        }
+
+        return strnatcasecmp((string) $aValue, (string) $bValue);
+    }
+
+    private function promotionSortValue(array $row, string $sort): mixed
+    {
+        return match ($sort) {
+            'student' => (string) ($row['student_name'] ?? ''),
+            'school_id' => (string) ($row['school_id'] ?? ''),
+            'class' => (string) ($row['class_section_name'] ?? ''),
+            'year_score' => is_numeric($row['year_score'] ?? null) ? (float) $row['year_score'] : null,
+            'decision' => (string) ($row['decision'] ?? ''),
+            'source' => (string) ($row['source'] ?? ''),
+            'queue' => (string) ($row['queue_status'] ?? ''),
+            'target' => trim((string) ($row['target_section'] ?? '') . ' ' . (string) ($row['target_class'] ?? '')),
+            'status' => (string) ($row['status'] ?? ''),
+            default => '',
+        };
+    }
+
+    private function carryForwardTablePayload(array $rows): array
+    {
+        $allowedSorts = ['family', 'parent', 'source_balance', 'credits', 'adjustments', 'net'];
+        $sort = (string) ($this->request->getGet('cf_sort') ?? 'family');
+        $sort = in_array($sort, $allowedSorts, true) ? $sort : 'family';
+        $order = strtolower((string) ($this->request->getGet('cf_order') ?? 'asc')) === 'desc' ? 'desc' : 'asc';
+
+        usort($rows, function (array $a, array $b) use ($sort, $order): int {
+            $comparison = $this->compareCarryForwardRows($a, $b, $sort);
+            if ($comparison === 0 && $sort !== 'family') {
+                $comparison = $this->compareCarryForwardRows($a, $b, 'family');
+            }
+            if ($comparison === 0) {
+                $comparison = ((int) ($a['family_id'] ?? 0)) <=> ((int) ($b['family_id'] ?? 0));
+            }
+
+            return $order === 'desc' ? -$comparison : $comparison;
+        });
+
+        return [
+            'rows' => $rows,
+            'sort' => $sort,
+            'order' => $order,
+        ];
+    }
+
+    private function compareCarryForwardRows(array $a, array $b, string $sort): int
+    {
+        $numericSorts = ['source_balance', 'credits', 'adjustments', 'net'];
+        $aValue = $this->carryForwardSortValue($a, $sort);
+        $bValue = $this->carryForwardSortValue($b, $sort);
+
+        if (in_array($sort, $numericSorts, true)) {
+            return (float) $aValue <=> (float) $bValue;
+        }
+
+        return strnatcasecmp((string) $aValue, (string) $bValue);
+    }
+
+    private function carryForwardSortValue(array $row, string $sort): mixed
+    {
+        return match ($sort) {
+            'family' => (string) ($row['family'] ?? ''),
+            'parent' => trim((string) ($row['parent'] ?? '') . ' ' . (string) ($row['parent_email'] ?? '')),
+            'source_balance' => (float) ($row['source_balance'] ?? 0),
+            'credits' => (float) ($row['credit_amount'] ?? 0),
+            'adjustments' => (float) ($row['adjustment_amount'] ?? 0),
+            'net' => (float) ($row['carry_forward_amount'] ?? 0),
+            default => '',
+        };
+    }
+
+    private function userId(): ?int
+    {
+        $id = session('user_id') ?? session('id');
+
+        return is_numeric($id) ? (int) $id : null;
+    }
+}

app/Controllers/Administrator/SchoolYearController.php

@@ -0,0 +1,221 @@
+<?php
+
+namespace App\Controllers\Administrator;
+
+use App\Controllers\BaseController;
+use App\Models\ConfigurationModel;
+use App\Models\SchoolYearModel;
+use App\Support\SchoolYear\SchoolYearStatus;
+use Throwable;
+
+class SchoolYearController extends BaseController
+{
+    private SchoolYearModel $schoolYearModel;
+
+    public function __construct()
+    {
+        $this->schoolYearModel = new SchoolYearModel();
+    }
+
+    public function index()
+    {
+        $schoolYears = $this->schoolYearModel
+            ->orderBy('name', 'DESC')
+            ->findAll();
+
+        $activeYear = null;
+        $nextDraftYear = null;
+        $closingYear = null;
+        $archivedCount = 0;
+
+        foreach ($schoolYears as $year) {
+            $status = (string) ($year['status'] ?? '');
+            if ($status === SchoolYearStatus::ACTIVE && $activeYear === null) {
+                $activeYear = $year;
+            }
+            if ($status === SchoolYearStatus::DRAFT && $nextDraftYear === null) {
+                $nextDraftYear = $year;
+            }
+            if ($status === SchoolYearStatus::CLOSING && $closingYear === null) {
+                $closingYear = $year;
+            }
+            if ($status === SchoolYearStatus::ARCHIVED) {
+                $archivedCount++;
+            }
+        }
+
+        $configurationModel = new ConfigurationModel();
+
+        return view('school_years/index', [
+            'schoolYears' => $schoolYears,
+            'statuses' => SchoolYearStatus::ALL,
+            'activeYear' => $activeYear,
+            'nextDraftYear' => $nextDraftYear,
+            'nextDraftDefaults' => service('schoolYearManagement')->nextDraftDefaults(),
+            'closingYear' => $closingYear,
+            'archivedCount' => $archivedCount,
+            'latestTransitions' => service('schoolYearManagement')->latestTransitionByYear(),
+            'yearVerification' => $this->verificationByYear($schoolYears),
+            'schoolYearNamesById' => array_column($schoolYears, 'name', 'id'),
+            'totalInstructionalWeeks' => $configurationModel->getConfigValueByKey('total_instructional_weeks'),
+        ]);
+    }
+
+    public function store()
+    {
+        try {
+            service('schoolYearManagement')->createDraft($this->request->getPost(), $this->userId());
+            return redirect()->to('/administrator/school-years')->with('success', 'Draft school year created.');
+        } catch (Throwable $e) {
+            return redirect()->back()->withInput()->with('error', $e->getMessage());
+        }
+    }
+
+    public function update(int $id)
+    {
+        try {
+            service('schoolYearManagement')->updateMetadata($id, $this->request->getPost(), $this->userId());
+            return redirect()->to('/administrator/school-years')->with('success', 'School year metadata updated.');
+        } catch (Throwable $e) {
+            return redirect()->back()->withInput()->with('error', $e->getMessage());
+        }
+    }
+
+    public function activate(int $id)
+    {
+        try {
+            if ($this->request->getPost('confirm_activation') !== '1') {
+                return redirect()->to('/administrator/school-years')->with('error', 'Activation confirmation is required.');
+            }
+
+            service('schoolYearManagement')->activate($id, $this->userId());
+            return redirect()->to('/administrator/school-years')->with('success', 'School year activated. Any previous active year is now in closing.');
+        } catch (Throwable $e) {
+            return redirect()->to('/administrator/school-years')->with('error', $e->getMessage());
+        }
+    }
+
+    public function deleteDraft(int $id)
+    {
+        try {
+            service('schoolYearManagement')->deleteDraft($id, $this->userId());
+            return redirect()->to('/administrator/school-years')->with('success', 'Draft school year deleted.');
+        } catch (Throwable $e) {
+            return redirect()->to('/administrator/school-years')->with('error', $e->getMessage());
+        }
+    }
+
+    public function archive(int $id)
+    {
+        try {
+            service('schoolYearManagement')->archive($id, $this->userId());
+            return redirect()->to('/administrator/school-years')->with('success', 'School year archived.');
+        } catch (Throwable $e) {
+            return redirect()->to('/administrator/school-years')->with('error', $e->getMessage());
+        }
+    }
+
+    public function reopen(int $id)
+    {
+        try {
+            service('schoolYearManagement')->reopen($id, (string) $this->request->getPost('reason'), $this->userId());
+            return redirect()->to('/administrator/school-years')->with('success', 'School year reopened.');
+        } catch (Throwable $e) {
+            return redirect()->to('/administrator/school-years')->with('error', $e->getMessage());
+        }
+    }
+
+    private function userId(): ?int
+    {
+        $id = session('user_id') ?? session('id');
+
+        return is_numeric($id) ? (int) $id : null;
+    }
+
+    private function verificationByYear(array $schoolYears): array
+    {
+        $db = db_connect();
+        $verification = [];
+
+        $hasStudentClass = $db->tableExists('student_class');
+        $hasStudentDecisions = $db->tableExists('student_decisions');
+        $hasPromotionQueue = $db->tableExists('promotion_queue');
+        $hasInvoices = $db->tableExists('invoices');
+        $hasClosingBatches = $db->tableExists('school_year_closing_batches');
+
+        foreach ($schoolYears as $year) {
+            $id = (int) ($year['id'] ?? 0);
+            $name = (string) ($year['name'] ?? '');
+            if ($id <= 0 || $name === '') {
+                continue;
+            }
+
+            $summary = [
+                'students' => 0,
+                'decisions' => 0,
+                'promoted' => 0,
+                'queued' => 0,
+                'carry_forward_balance' => 0.0,
+                'positive_balance' => 0.0,
+                'credit_balance' => 0.0,
+                'closing_status' => '',
+            ];
+
+            if ($hasStudentClass && $db->fieldExists('school_year', 'student_class')) {
+                $row = $db->table('student_class')
+                    ->select('COUNT(DISTINCT student_id) AS total', false)
+                    ->where('school_year', $name)
+                    ->get()
+                    ->getRowArray();
+                $summary['students'] = (int) ($row['total'] ?? 0);
+            }
+
+            if ($hasStudentDecisions && $db->fieldExists('school_year', 'student_decisions')) {
+                $row = $db->table('student_decisions')
+                    ->select('COUNT(DISTINCT student_id) AS decisions', false)
+                    ->select("COUNT(DISTINCT CASE WHEN LOWER(decision) = 'pass' THEN student_id END) AS promoted", false)
+                    ->where('school_year', $name)
+                    ->get()
+                    ->getRowArray();
+                $summary['decisions'] = (int) ($row['decisions'] ?? 0);
+                $summary['promoted'] = (int) ($row['promoted'] ?? 0);
+            }
+
+            if ($hasPromotionQueue && $db->fieldExists('school_year_from', 'promotion_queue')) {
+                $row = $db->table('promotion_queue')
+                    ->select('COUNT(DISTINCT student_id) AS total', false)
+                    ->where('school_year_from', $name)
+                    ->get()
+                    ->getRowArray();
+                $summary['queued'] = (int) ($row['total'] ?? 0);
+            }
+
+            if ($hasInvoices && $db->fieldExists('school_year', 'invoices')) {
+                $row = $db->table('invoices')
+                    ->select('COALESCE(SUM(balance), 0) AS carry_forward_balance')
+                    ->select('COALESCE(SUM(CASE WHEN balance > 0 THEN balance ELSE 0 END), 0) AS positive_balance', false)
+                    ->select('COALESCE(SUM(CASE WHEN balance < 0 THEN ABS(balance) ELSE 0 END), 0) AS credit_balance', false)
+                    ->where('school_year', $name)
+                    ->get()
+                    ->getRowArray();
+                $summary['carry_forward_balance'] = round((float) ($row['carry_forward_balance'] ?? 0), 2);
+                $summary['positive_balance'] = round((float) ($row['positive_balance'] ?? 0), 2);
+                $summary['credit_balance'] = round((float) ($row['credit_balance'] ?? 0), 2);
+            }
+
+            if ($hasClosingBatches) {
+                $batch = $db->table('school_year_closing_batches')
+                    ->select('status')
+                    ->where('source_school_year_id', $id)
+                    ->orderBy('id', 'DESC')
+                    ->get(1)
+                    ->getRowArray();
+                $summary['closing_status'] = (string) ($batch['status'] ?? '');
+            }
+
+            $verification[$id] = $summary;
+        }
+
+        return $verification;
+    }
+}

app/Controllers/Administrator/WithdrawalFinancialController.php

@@ -0,0 +1,126 @@
+<?php
+
+namespace App\Controllers\Administrator;
+
+use App\Controllers\BaseController;
+use Throwable;
+
+class WithdrawalFinancialController extends BaseController
+{
+    public function review(int $enrollmentId)
+    {
+        try {
+            $calculation = service('withdrawalFinancial')->latestForEnrollment($enrollmentId);
+            if ($calculation === null || ($calculation['status'] ?? '') === 'superseded') {
+                $calculation = service('withdrawalFinancial')->preview($enrollmentId, $this->userId());
+            } elseif ($this->hasStaleInstructionalWeeksBlocker($calculation)) {
+                $calculation = service('withdrawalFinancial')->preview($enrollmentId, $this->userId());
+            }
+
+            return view('withdrawals/review', [
+                'calculation' => $this->withPostingGateBlockers($calculation),
+            ]);
+        } catch (Throwable $e) {
+            return redirect()->back()->with('error', $e->getMessage());
+        }
+    }
+
+    public function recalculate(int $enrollmentId)
+    {
+        try {
+            $calculation = service('withdrawalFinancial')->preview($enrollmentId, $this->userId(), [
+                'enrollment_date' => (string) $this->request->getPost('enrollment_date'),
+                'withdrawal_request_date' => (string) $this->request->getPost('withdrawal_request_date'),
+                'override_reason' => (string) $this->request->getPost('override_reason'),
+                'legacy_invoice_confirmed' => (string) $this->request->getPost('legacy_invoice_confirmed') === '1',
+            ]);
+
+            return redirect()->to('/administrator/withdrawals/' . $enrollmentId . '/review')
+                ->with('success', 'Calculation preview version ' . (int) $calculation['version'] . ' saved.');
+        } catch (Throwable $e) {
+            return redirect()->back()->withInput()->with('error', $e->getMessage());
+        }
+    }
+
+    public function confirm(int $calculationId)
+    {
+        try {
+            $calculation = service('withdrawalFinancial')->post($calculationId, $this->userId());
+
+            return redirect()->to('/administrator/withdrawal-calculations/' . $calculationId)
+                ->with('success', ((int) ($calculation['new_refund_request_cents'] ?? 0)) > 0
+                    ? 'Withdrawal posted and the refund request was created.'
+                    : 'Withdrawal posted. No refund is due; the invoice balance was recalculated.');
+        } catch (Throwable $e) {
+            return redirect()->back()->with('error', $e->getMessage());
+        }
+    }
+
+    public function calculation(int $calculationId)
+    {
+        try {
+            $calculation = service('withdrawalFinancial')->details($calculationId);
+            if ($this->hasStaleInstructionalWeeksBlocker($calculation)) {
+                $calculation = service('withdrawalFinancial')->preview((int) $calculation['enrollment_id'], $this->userId());
+
+                return redirect()->to('/administrator/withdrawal-calculations/' . (int) $calculation['id'])
+                    ->with('success', 'Calculation preview refreshed with the configured total instructional weeks.');
+            }
+
+            return view('withdrawals/calculation', [
+                'calculation' => $calculation,
+            ]);
+        } catch (Throwable $e) {
+            return redirect()->back()->with('error', $e->getMessage());
+        }
+    }
+
+    public function invoiceSummary(int $invoiceId)
+    {
+        try {
+            return view('withdrawals/invoice_summary', [
+                'calculations' => service('withdrawalFinancial')->calculationsForInvoice($invoiceId),
+                'invoiceId' => $invoiceId,
+            ]);
+        } catch (Throwable $e) {
+            return redirect()->back()->with('error', $e->getMessage());
+        }
+    }
+
+    private function hasStaleInstructionalWeeksBlocker(array $calculation): bool
+    {
+        if (($calculation['status'] ?? '') !== 'requires_review' || ! empty($calculation['posted_at'])) {
+            return false;
+        }
+
+        $blockers = array_map('strval', (array) ($calculation['blockers'] ?? []));
+
+        return in_array('Set a positive total_instructional_weeks value for this school year.', $blockers, true)
+            || in_array('Set a positive total_instructional_weeks value in configuration.', $blockers, true);
+    }
+
+    /** @return array<string,mixed> */
+    private function withPostingGateBlockers(array $calculation): array
+    {
+        $blockers = array_values(array_filter(array_map('strval', (array) ($calculation['blockers'] ?? []))));
+        foreach (service('withdrawalFinancial')->postingGateBlockers($calculation) as $blocker) {
+            if (! in_array($blocker, $blockers, true)) {
+                $blockers[] = $blocker;
+            }
+        }
+
+        $calculation['blockers'] = $blockers;
+        if (isset($calculation['explanation']) && is_array($calculation['explanation'])) {
+            $calculation['explanation']['blockers'] = $blockers;
+        }
+
+        return $calculation;
+    }
+
+    private function userId(): ?int
+    {
+        $id = session()->get('user_id');
+
+        return $id === null || $id === '' ? null : (int) $id;
+    }
+}

app/Controllers/AuthController.php

@@ -5,7 +5,6 @@ namespace App\Controllers;
 use App\Models\LoginActivityModel;
 use App\Models\UserModel;
 use App\Models\UserRoleModel;
-use CodeIgniter\Controller;
 use CodeIgniter\Events\Events;
 use App\Models\IpAttemptModel;
 use App\Models\PasswordResetModel;
@@ -19,7 +18,7 @@ require_once APPPATH . 'Helpers/pbkdf2_helper.php';
 require_once APPPATH . 'Helpers/jwt_helper.php';
 
 
-class AuthController extends Controller
+class AuthController extends BaseController
 {
     protected $configModel;
     protected $userModel;
@@ -39,7 +38,7 @@ class AuthController extends Controller
         $this->loginActivityModel = new LoginActivityModel();
         $this->preferencesModel = new PreferencesModel();
         $this->schoolYear = $this->configModel->getConfig('school_year');
-        $this->semester = $this->configModel->getConfig('semester');
+        $this->semester = getSemester();
         
     }
 
@@ -83,9 +82,23 @@ class AuthController extends Controller
         log_message('info', 'Processing login form submission.');
         $redirectTo = $this->sanitizeRedirectTarget((string) ($this->request->getPost('redirect_to') ?? $this->request->getGet('redirect_to') ?? ''));
 
+        $validator = \Config\Services::validation();
+        $requestData = sanitize_request_value($this->request->getPost(['email', 'password']));
+        $validator->setRules([
+            'email' => 'required|valid_email|max_length[254]',
+            'password' => 'required|max_length[255]',
+        ]);
+
+        if (! $validator->run($requestData)) {
+            return redirect()
+                ->back()
+                ->with('error', 'Please enter a valid email and password.')
+                ->withInput();
+        }
+
         // Step 1: Get email, password, and IP from the request
-        $email = $this->request->getPost('email');
-        $password = $this->request->getPost('password');
+        $email = strtolower((string) $requestData['email']);
+        $password = (string) $requestData['password'];
         $ip = $this->request->getIPAddress();
 
         log_message('info', 'Login attempt from IP: ' . $ip . ' for email: ' . $email);
@@ -139,26 +152,29 @@ class AuthController extends Controller
     // JSON API: POST /api/login
     public function apiLogin()
     {
-        $requestData = $this->request->getJSON(true);
-        if (!$requestData) {
-            // fallback to form vars
-            $requestData = [
-                'email' => $this->request->getPost('email'),
-                'password' => $this->request->getPost('password'),
-            ];
-        }
+        $requestData = sanitize_request_value($this->request->getJSON(true) ?: [
+            'email' => $this->request->getPost('email'),
+            'password' => $this->request->getPost('password'),
+        ]);
 
-        $email = $requestData['email'] ?? '';
-        $password = $requestData['password'] ?? '';
-        $ip = $this->request->getIPAddress();
+        $validation = \Config\Services::validation();
+        $validation->setRules([
+            'email' => 'required|valid_email|max_length[254]',
+            'password' => 'required|max_length[255]',
+        ]);
 
-        if (!$email || !$password) {
-            return $this->response->setStatusCode(400)->setJSON([
+        if (! $validation->run($requestData)) {
+            return $this->response->setStatusCode(422)->setJSON([
                 'status' => false,
-                'message' => 'Email and password are required.'
+                'message' => 'Validation failed.',
+                'errors' => $validation->getErrors(),
             ]);
         }
 
+        $email = strtolower((string) ($requestData['email'] ?? ''));
+        $password = (string) ($requestData['password'] ?? '');
+        $ip = $this->request->getIPAddress();
+
         if ($this->isIpBlocked($ip)) {
             return $this->response->setStatusCode(429)->setJSON([
                 'status' => false,
@@ -195,13 +211,7 @@ class AuthController extends Controller
         $this->logLoginAttempt($user['id'], $user['email'], $ip, $this->request->getUserAgent());
 
         // Fetch roles
-        $userRoleModel = new UserRoleModel();
-        $rolesRows = $userRoleModel->select('roles.name')
-            ->join('roles', 'roles.id = user_roles.role_id')
-            ->where('user_roles.user_id', $user['id'])
-            ->get()
-            ->getResultArray();
-        $roleNames = array_column($rolesRows, 'name');
+        $roleNames = $this->getUserRoleNames((int) $user['id']);
 
         // Build roles map (object with keys per example)
         $rolesMap = [];
@@ -220,7 +230,15 @@ class AuthController extends Controller
             'exp' => $exp,
         ];
 
-        $secret = env('JWT_SECRET', 'change-me-in-env');
+        try {
+            $secret = require_env('JWT_SECRET');
+        } catch (\RuntimeException $e) {
+            return $this->response->setStatusCode(500)->setJSON([
+                'status' => false,
+                'message' => 'JWT configuration is missing.',
+            ]);
+        }
+
         $token = jwt_encode($payload, $secret, 'HS256');
 
         return $this->response->setJSON([
@@ -234,24 +252,46 @@ class AuthController extends Controller
         ]);
     }
 
+    public function adminAuthMe()
+    {
+        if (! session()->get('is_logged_in')) {
+            return $this->response->setStatusCode(401)->setJSON([
+                'status' => false,
+                'message' => 'Unauthenticated.',
+            ]);
+        }
+
+        $userId = (int) session()->get('user_id');
+        $roles = array_values(array_filter((array) (session()->get('roles') ?? [])));
+        $activeRole = session()->get('role');
+
+        return $this->response->setJSON([
+            'status' => true,
+            'user' => [
+                'id' => $userId,
+                'email' => session()->get('user_email'),
+                'name' => session()->get('user_name'),
+                'type' => session()->get('user_type'),
+                'roles' => $roles,
+                'role' => $activeRole,
+            ],
+        ]);
+    }
+
     /**
      * API Registration endpoint
      * POST /api/v1/register
      */
     public function apiRegister()
     {
-        $requestData = $this->request->getJSON(true);
-        if (!$requestData) {
-            // fallback to form vars
-            $requestData = $this->request->getPost();
-        }
+        $requestData = sanitize_request_value($this->request->getJSON(true) ?: $this->request->getPost());
 
         // Basic validation
         $rules = [
-            'firstname' => 'required|min_length[2]|max_length[30]',
-            'lastname' => 'required|min_length[2]|max_length[30]',
-            'email' => 'required|valid_email|is_unique[users.email]',
-            'password' => 'required|min_length[8]',
+            'firstname' => "required|regex_match[/^[\\p{L}\\s'\\-]+$/u]|min_length[2]|max_length[30]",
+            'lastname' => "required|regex_match[/^[\\p{L}\\s'\\-]+$/u]|min_length[2]|max_length[30]",
+            'email' => 'required|valid_email|max_length[254]|is_unique[users.email]',
+            'password' => 'required|min_length[8]|max_length[255]',
             'cellphone' => 'required|min_length[10]|max_length[20]',
         ];
 
@@ -292,7 +332,7 @@ class AuthController extends Controller
             'state' => $requestData['state'] ?? null,
             'zip' => $requestData['zip'] ?? null,
             'school_year' => $this->configModel->getConfig('school_year'),
-            'semester' => $this->configModel->getConfig('semester'),
+            'semester' => getSemester(),
             'status' => 'active',
             'is_verified' => 0, // Require email verification
         ];
@@ -332,7 +372,7 @@ class AuthController extends Controller
                 'exp' => $exp,
             ];
 
-            $secret = env('JWT_SECRET', 'change-me-in-env');
+            $secret = require_env('JWT_SECRET');
             $token = jwt_encode($payload, $secret, 'HS256');
 
             return $this->response->setStatusCode(201)->setJSON([
@@ -434,6 +474,18 @@ class AuthController extends Controller
         $this->userModel->update($userId, ['failed_attempts' => 0, 'last_failed_at' => null]);
     }
 
+    protected function getUserRoleNames(int $userId): array
+    {
+        $userRoleModel = new UserRoleModel();
+        $rolesRows = $userRoleModel->select('roles.name')
+            ->join('roles', 'roles.id = user_roles.role_id')
+            ->where('user_roles.user_id', $userId)
+            ->get()
+            ->getResultArray();
+
+        return array_column($rolesRows, 'name');
+    }
+
     public function logout()
     {
         // Get user ID and email from session
@@ -526,6 +578,7 @@ class AuthController extends Controller
 
         $roleNames = array_column($roles, 'name');
 
+        session()->regenerate(true);
         session()->set([
             'user_id'      => $user['id'],
             'user_email'   => $user['email'],
@@ -533,13 +586,12 @@ class AuthController extends Controller
             'user_type'    => $user['user_type'],
             'is_logged_in' => true,
             'login_time'   => time(),
+            'last_activity' => time(),
             'roles'        => $roleNames,
             'semester'     => $this->semester,
             'school_year'  => $this->schoolYear,
         ]);
         $this->applyStylePreferences((int) $user['id']);
-        log_message('debug', 'Session after login: ' . print_r(session()->get(), true));
-        //dd('Login successful. Roles:', $roleNames, session()->get());
 
         if (count($roleNames) === 1) {
             // One role → set and redirect directly

app/Controllers/BaseController.php

@@ -9,6 +9,9 @@ use CodeIgniter\HTTP\RequestInterface;
 use CodeIgniter\HTTP\ResponseInterface;
 use Psr\Log\LoggerInterface;
 use App\Services\ApiClient;
+use App\Exceptions\SchoolYear\SchoolYearConfigurationException;
+use App\Support\SchoolYear\SchoolYearContext;
+use Throwable;
 
 /**
  * Class BaseController
@@ -36,7 +39,7 @@ abstract class BaseController extends Controller
      *
      * @var list<string>
      */
-    protected $helpers = [];
+    protected $helpers = ['security'];
 
     /** @var ApiClient */
     protected ApiClient $api;
@@ -58,6 +61,8 @@ abstract class BaseController extends Controller
         // Preload any models, libraries, etc, here.
         // E.g.: $this->session = \Config\Services::session();
         session();
+        $this->syncSchoolYearPropertyFromContext();
+        $this->injectSchoolYearViewData();
 
         // Shared API client available to all controllers
         $this->api = service('apiClient');
@@ -73,6 +78,154 @@ abstract class BaseController extends Controller
         // Assuming the user role is stored in the session
         return session()->get('role');
     }
+
+    protected function validated(array $rules, ?array $data = null): array
+    {
+        $validation = service('validation');
+        $payload = $data ?? ($this->request->getJSON(true) ?: $this->request->getPost());
+        $payload = sanitize_request_value($payload);
+
+        $validation->setRules($rules);
+
+        if (! $validation->run($payload)) {
+            throw new \InvalidArgumentException(json_encode($validation->getErrors(), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) ?: 'Validation failed');
+        }
+
+        return $payload;
+    }
+
+    protected function resolveSchoolYearContext(?int $routeSchoolYearId = null): SchoolYearContext
+    {
+        try {
+            return service('schoolYearContext')->resolve($this->request, $routeSchoolYearId);
+        } catch (Throwable $e) {
+            log_message('warning', 'School-year resolution failed: {message}', [
+                'message' => $e->getMessage(),
+            ]);
+
+            throw $e;
+        }
+    }
+
+    protected function currentSchoolYearName(?string $fallback = null): string
+    {
+        try {
+            return $this->resolveSchoolYearContext()->yearName();
+        } catch (Throwable $e) {
+            if ($fallback !== null && $fallback !== '') {
+                return $fallback;
+            }
+
+            try {
+                return (string) ((new \App\Models\ConfigurationModel())->getConfig('school_year') ?? '');
+            } catch (Throwable) {
+                return '';
+            }
+        }
+    }
+
+    protected function assertSchoolYearWritable(
+        SchoolYearContext $context,
+        bool $allowDraftForAdmin = false,
+        bool $isAdmin = false
+    ): void {
+        service('schoolYearWriteGuard')->assertWritable($context, $allowDraftForAdmin, $isAdmin);
+    }
+
+    protected function assertSchoolYearNameWritable(
+        string $schoolYear,
+        bool $allowDraftForAdmin = false,
+        bool $isAdmin = false
+    ): void {
+        $context = service('schoolYearContext')->forYearName($schoolYear);
+
+        $this->assertSchoolYearWritable($context, $allowDraftForAdmin, $isAdmin);
+    }
+
+    private function syncSchoolYearPropertyFromContext(): void
+    {
+        if (! property_exists($this, 'schoolYear')) {
+            return;
+        }
+
+        if (! $this->request instanceof IncomingRequest || is_cli()) {
+            return;
+        }
+
+        if (! session()->get('user_id')) {
+            return;
+        }
+
+        try {
+            $this->schoolYear = $this->currentSchoolYearName((string) ($this->schoolYear ?? ''));
+        } catch (Throwable $e) {
+            log_message('warning', 'Unable to sync controller school-year property: {message}', [
+                'message' => $e->getMessage(),
+            ]);
+        }
+    }
+
+    private function injectSchoolYearViewData(): void
+    {
+        if (! config('Feature')->globalSchoolYearSelector) {
+            return;
+        }
+
+        if (! $this->request instanceof IncomingRequest || is_cli()) {
+            return;
+        }
+
+        if (! session()->get('user_id')) {
+            return;
+        }
+
+        if (! $this->shouldShowSchoolYearSelector()) {
+            return;
+        }
+
+        $accept = strtolower($this->request->getHeaderLine('Accept'));
+        if ($this->request->isAJAX() || str_contains($accept, 'application/json')) {
+            return;
+        }
+
+        try {
+            service('renderer')->setData(service('schoolYearViewData')->forCurrentRequest($this->request));
+        } catch (SchoolYearConfigurationException $e) {
+            log_message('warning', 'Unable to inject school-year view data: {message}', [
+                'message' => $e->getMessage(),
+            ]);
+        } catch (Throwable $e) {
+            log_message('warning', 'Unable to inject school-year view data: {message}', [
+                'message' => $e->getMessage(),
+            ]);
+        }
+    }
+
+    private function shouldShowSchoolYearSelector(): bool
+    {
+        $roles = (array) session()->get('roles');
+        $singleRole = session()->get('role');
+        if ($singleRole !== null && $singleRole !== '') {
+            $roles[] = $singleRole;
+        }
+
+        $roles = array_map(
+            static fn ($role): string => strtolower(trim((string) $role)),
+            $roles
+        );
+
+        return (bool) array_intersect($roles, [
+            'admin',
+            'administrator',
+            'administrative staff',
+            'parent',
+            'principal',
+            'teacher',
+            'teacher assistant',
+            'teacher_assistant',
+            'vice principal',
+        ]);
+    }
 }
 
-?>
+?>

app/Controllers/ClassProgressController.php

@@ -54,6 +54,7 @@ class ClassProgressController extends BaseController
 
     public function create()
     {
+        $context = $this->resolveSchoolYearContext();
         $teacherId = (int) session()->get('user_id');
         $assignments = $this->loadTeacherSections($teacherId);
         $first = $assignments[0] ?? null;
@@ -76,12 +77,15 @@ class ClassProgressController extends BaseController
             'classId' => $classId,
             'sundayOptions' => $sundayOptions,
             'defaultWeekStart' => $defaultWeekStart,
+            'isSchoolYearReadonly' => $context->isReadonly(),
         ];
         return view('teacher/class_progress_submit', $data);
     }
 
     public function store()
     {
+        $this->assertSchoolYearWritable($this->resolveSchoolYearContext());
+        [, $schoolYear] = $this->resolveCurrentTerm();
         $subjectSections = self::SUBJECT_SECTIONS;
         $rules = [
             'class_section_id' => 'required|integer',
@@ -132,8 +136,9 @@ class ClassProgressController extends BaseController
             ->select('id')
             ->where('class_section_id', $classSectionId)
             ->where('week_start', $weekStart)
-            ->where('teacher_id', $teacherId)
-            ->findAll();
+            ->where('teacher_id', $teacherId);
+        $this->applyProgressSchoolYearScope($existingReports, $schoolYear);
+        $existingReports = $existingReports->findAll();
 
         if (! $confirmOverwrite && ! empty($existingReports)) {
             return redirect()->back()
@@ -175,7 +180,7 @@ class ClassProgressController extends BaseController
                 'homework' => $homework ?: null,
                 'status' => $status,
                 'flags_json' => $this->normalizeFlags($this->request->getPost('flags')),
-            ];
+            ] + $this->progressReportSchoolYearData($schoolYear);
 
             $reportId = $this->reportModel->insert($data, true);
             $attachmentField = "attachment_$slug";
@@ -198,6 +203,7 @@ class ClassProgressController extends BaseController
     public function history()
     {
         $teacherId = (int) session()->get('user_id');
+        [$semester, $schoolYear] = $this->resolveCurrentTerm();
         $assignments = $this->loadTeacherSections($teacherId);
         $selectedSectionId = (int) $this->request->getGet('class_section_id');
         $validSectionIds = array_column($assignments, 'class_section_id');
@@ -207,7 +213,6 @@ class ClassProgressController extends BaseController
         if ($selectedSectionId && ! in_array($selectedSectionId, $validSectionIds, true)) {
             $selectedSectionId = $validSectionIds[0] ?? null;
         }
-        [$semester, $schoolYear] = $this->resolveCurrentTerm();
         $allowedTeacherIds = $this->resolveAssignedTeacherIds($selectedSectionId, $semester, $schoolYear);
         if (empty($allowedTeacherIds)) {
             $allowedTeacherIds = [$teacherId];
@@ -217,6 +222,7 @@ class ClassProgressController extends BaseController
             ->join('classSection cs', 'cs.class_section_id = class_progress_reports.class_section_id', 'left')
             ->join('users u', 'u.id = class_progress_reports.teacher_id', 'left')
             ->whereIn('teacher_id', $allowedTeacherIds);
+        $this->applyProgressSchoolYearScope($builder, $schoolYear, true);
         if ($selectedSectionId) {
             $builder->where('class_progress_reports.class_section_id', $selectedSectionId);
         }
@@ -251,24 +257,27 @@ class ClassProgressController extends BaseController
             'subjectSections' => self::SUBJECT_SECTIONS,
             'classSectionOptions' => $sectionOptions,
             'selectedSectionId' => $selectedSectionId,
+            'schoolYear' => $schoolYear,
+            'isSchoolYearReadonly' => $this->resolveSchoolYearContext()->isReadonly(),
         ]);
     }
 
     public function view($id)
     {
         $teacherId = (int) session()->get('user_id');
-        $row = $this->reportModel
+        [$semester, $schoolYear] = $this->resolveCurrentTerm();
+        $rowQuery = $this->reportModel
             ->select('class_progress_reports.*, cs.class_section_name, CONCAT(IFNULL(u.firstname, ""), " ", IFNULL(u.lastname, "")) AS teacher_name')
             ->join('classSection cs', 'cs.class_section_id = class_progress_reports.class_section_id', 'left')
             ->join('users u', 'u.id = class_progress_reports.teacher_id', 'left')
-            ->where('class_progress_reports.id', (int) $id)
-            ->first();
+            ->where('class_progress_reports.id', (int) $id);
+        $this->applyProgressSchoolYearScope($rowQuery, $schoolYear, true);
+        $row = $rowQuery->first();
 
         if (! $row) {
             throw new PageNotFoundException('Progress report not found.');
         }
 
-        [$semester, $schoolYear] = $this->resolveCurrentTerm();
         $allowedTeacherIds = $this->resolveAssignedTeacherIds((int) $row['class_section_id'], $semester, $schoolYear);
         if (empty($allowedTeacherIds)) {
             if ($teacherId !== (int) $row['teacher_id']) {
@@ -280,13 +289,15 @@ class ClassProgressController extends BaseController
         }
 
         $row['status_label'] = self::STATUS_OPTIONS[$row['status']] ?? 'Unknown';
-        $weeklyReports = $this->reportModel
+        $weeklyReportsQuery = $this->reportModel
             ->select('class_progress_reports.*, cs.class_section_name, CONCAT(IFNULL(u.firstname, ""), " ", IFNULL(u.lastname, "")) AS teacher_name')
             ->join('classSection cs', 'cs.class_section_id = class_progress_reports.class_section_id', 'left')
             ->join('users u', 'u.id = class_progress_reports.teacher_id', 'left')
             ->whereIn('teacher_id', $allowedTeacherIds)
             ->where('class_progress_reports.class_section_id', $row['class_section_id'])
-            ->where('week_start', $row['week_start'])
+            ->where('week_start', $row['week_start']);
+        $this->applyProgressSchoolYearScope($weeklyReportsQuery, $schoolYear);
+        $weeklyReports = $weeklyReportsQuery
             ->orderBy('subject', 'ASC')
             ->findAll();
 
@@ -313,17 +324,18 @@ class ClassProgressController extends BaseController
     public function edit($id)
     {
         $teacherId = (int) session()->get('user_id');
-        $row = $this->reportModel
+        [$semester, $schoolYear] = $this->resolveCurrentTerm();
+        $rowQuery = $this->reportModel
             ->select('class_progress_reports.*, cs.class_section_name')
             ->join('classSection cs', 'cs.class_section_id = class_progress_reports.class_section_id', 'left')
-            ->where('class_progress_reports.id', (int) $id)
-            ->first();
+            ->where('class_progress_reports.id', (int) $id);
+        $this->applyProgressSchoolYearScope($rowQuery, $schoolYear);
+        $row = $rowQuery->first();
 
         if (! $row) {
             throw new PageNotFoundException('Progress report not found.');
         }
 
-        [$semester, $schoolYear] = $this->resolveCurrentTerm();
         $allowedTeacherIds = $this->resolveAssignedTeacherIds((int) $row['class_section_id'], $semester, $schoolYear);
         if (empty($allowedTeacherIds)) {
             if ($teacherId !== (int) $row['teacher_id']) {
@@ -334,11 +346,13 @@ class ClassProgressController extends BaseController
             throw new PageNotFoundException('Progress report not found.');
         }
 
-        $weeklyReports = $this->reportModel
+        $weeklyReportsQuery = $this->reportModel
             ->select('class_progress_reports.*')
             ->whereIn('teacher_id', $allowedTeacherIds)
             ->where('class_section_id', $row['class_section_id'])
-            ->where('week_start', $row['week_start'])
+            ->where('week_start', $row['week_start']);
+        $this->applyProgressSchoolYearScope($weeklyReportsQuery, $schoolYear);
+        $weeklyReports = $weeklyReportsQuery
             ->orderBy('subject', 'ASC')
             ->findAll();
 
@@ -405,18 +419,23 @@ class ClassProgressController extends BaseController
             'isEdit' => true,
             'formAction' => base_url('teacher/progress/update/' . (int) $row['id']),
             'submitLabel' => 'Update Progress',
+            'isSchoolYearReadonly' => $this->resolveSchoolYearContext()->isReadonly(),
         ]);
     }
 
     public function update($id)
     {
+        $this->assertSchoolYearWritable($this->resolveSchoolYearContext());
         $teacherId = (int) session()->get('user_id');
-        $row = $this->reportModel->find((int) $id);
+        [$semester, $schoolYear] = $this->resolveCurrentTerm();
+        $rowQuery = $this->reportModel
+            ->where('class_progress_reports.id', (int) $id);
+        $this->applyProgressSchoolYearScope($rowQuery, $schoolYear);
+        $row = $rowQuery->first();
         if (! $row) {
             throw new PageNotFoundException('Progress report not found.');
         }
 
-        [$semester, $schoolYear] = $this->resolveCurrentTerm();
         $allowedTeacherIds = $this->resolveAssignedTeacherIds((int) $row['class_section_id'], $semester, $schoolYear);
         if (empty($allowedTeacherIds)) {
             if ($teacherId !== (int) $row['teacher_id']) {
@@ -473,8 +492,9 @@ class ClassProgressController extends BaseController
                 ->select('id')
                 ->where('class_section_id', $classSectionId)
                 ->where('week_start', $weekStart)
-                ->where('teacher_id', $teacherId)
-                ->findAll();
+                ->where('teacher_id', $teacherId);
+            $this->applyProgressSchoolYearScope($conflicts, $schoolYear);
+            $conflicts = $conflicts->findAll();
             if (! $confirmOverwrite && ! empty($conflicts)) {
                 return redirect()->back()
                     ->withInput()
@@ -493,11 +513,13 @@ class ClassProgressController extends BaseController
             }
         }
 
-        $weeklyReports = $this->reportModel
+        $weeklyReportsQuery = $this->reportModel
             ->select('class_progress_reports.*')
             ->whereIn('teacher_id', $allowedTeacherIds)
             ->where('class_section_id', $classSectionId)
-            ->where('week_start', $row['week_start'])
+            ->where('week_start', $row['week_start']);
+        $this->applyProgressSchoolYearScope($weeklyReportsQuery, $schoolYear);
+        $weeklyReports = $weeklyReportsQuery
             ->orderBy('subject', 'ASC')
             ->findAll();
 
@@ -533,7 +555,7 @@ class ClassProgressController extends BaseController
                 'unit_title' => $unitTitle,
                 'covered' => $covered,
                 'homework' => $homework ?: null,
-            ];
+            ] + $this->progressReportSchoolYearData($schoolYear);
             if ($flagsInput !== null) {
                 $data['flags_json'] = $this->normalizeFlags($flagsInput);
             }
@@ -698,8 +720,7 @@ class ClassProgressController extends BaseController
 
     protected function loadTeacherSections(int $teacherId): array
     {
-        $schoolYear = (string) ($this->configModel->getConfig('school_year') ?? '');
-        $semester = (string) ($this->configModel->getConfig('semester') ?? '');
+        [$semester, $schoolYear] = $this->resolveCurrentTerm();
         return $this->teacherClassModel->getClassAssignmentsByUserId($teacherId, $schoolYear, $semester);
     }
 
@@ -878,13 +899,13 @@ class ClassProgressController extends BaseController
 
     protected function resolveProgressDateRange(): ?array
     {
-        $schoolYear = (string) ($this->configModel->getConfig('school_year') ?? '');
+        $schoolYear = $this->currentSchoolYearName((string) ($this->configModel->getConfig('school_year') ?? ''));
         if ($schoolYear === '') {
             return null;
         }
 
         $semesterResolver = new SemesterRangeService($this->configModel);
-        $semester = $semesterResolver->normalizeSemester((string) ($this->configModel->getConfig('semester') ?? ''));
+        $semester = $semesterResolver->normalizeSemester((string) (getSemester() ?? ''));
         if ($semester === '') {
             $semester = $semesterResolver->getSemesterForDate();
         }
@@ -946,11 +967,65 @@ class ClassProgressController extends BaseController
 
     protected function resolveCurrentTerm(): array
     {
-        $schoolYear = (string) ($this->configModel->getConfig('school_year') ?? '');
-        $semester = (string) ($this->configModel->getConfig('semester') ?? '');
+        $schoolYear = $this->currentSchoolYearName((string) ($this->configModel->getConfig('school_year') ?? ''));
+        $semester = (string) (getSemester() ?? '');
         return [$semester, $schoolYear];
     }
 
+    protected function applyProgressSchoolYearScope($builder, string $schoolYear, bool $canScopeBySection = false): void
+    {
+        if ($schoolYear === '') {
+            return;
+        }
+
+        $db = db_connect();
+        $hasReportYear = $db->fieldExists('school_year', 'class_progress_reports');
+        $hasSectionYear = $db->fieldExists('school_year', 'classSection');
+        $semesterResolver = new SemesterRangeService($this->configModel);
+        [$rangeStart, $rangeEnd] = $semesterResolver->getSchoolYearRange($schoolYear);
+
+        if ($hasReportYear) {
+            if ($rangeStart !== '' && $rangeEnd !== '') {
+                $builder
+                    ->groupStart()
+                        ->where('class_progress_reports.school_year', $schoolYear)
+                        ->orGroupStart()
+                            ->groupStart()
+                                ->where('class_progress_reports.school_year IS NULL', null, false)
+                                ->orWhere('class_progress_reports.school_year', '')
+                            ->groupEnd()
+                            ->where('class_progress_reports.week_start >=', $rangeStart)
+                            ->where('class_progress_reports.week_start <=', $rangeEnd)
+                        ->groupEnd()
+                    ->groupEnd();
+                return;
+            }
+
+            $builder->where('class_progress_reports.school_year', $schoolYear);
+            return;
+        }
+
+        if ($canScopeBySection && $hasSectionYear) {
+            $builder->where('cs.school_year', $schoolYear);
+            return;
+        }
+
+        if ($rangeStart !== '' && $rangeEnd !== '') {
+            $builder
+                ->where('class_progress_reports.week_start >=', $rangeStart)
+                ->where('class_progress_reports.week_start <=', $rangeEnd);
+        }
+    }
+
+    protected function progressReportSchoolYearData(string $schoolYear): array
+    {
+        if ($schoolYear === '' || ! db_connect()->fieldExists('school_year', 'class_progress_reports')) {
+            return [];
+        }
+
+        return ['school_year' => $schoolYear];
+    }
+
     protected function resolveAssignedTeacherIds(?int $classSectionId, string $semester, string $schoolYear): array
     {
         if (! $classSectionId || $schoolYear === '') {

app/Controllers/InitializeRolesPermissions.php

@@ -115,9 +115,10 @@ class InitializeRolesPermissions extends Controller
 
         // Associating permissions with roles
         $rolePermissions = [
-            'administrator' => ['manage_users', 'view_reports', 'manage_settings', 'access_student_records', 'communicate_parents'],
-            'principal' => ['manage_users', 'view_reports', 'access_student_records', 'communicate_parents'],
-            'vice principal' => ['view_reports', 'access_student_records', 'communicate_parents'],
+            'administrator' => ['manage_users', 'view_reports', 'manage_settings', 'access_student_records', 'communicate_parents', 'update_curriculum'],
+            'principal' => ['manage_users', 'view_reports', 'access_student_records', 'communicate_parents', 'update_curriculum'],
+            'vice principal' => ['view_reports', 'access_student_records', 'communicate_parents', 'update_curriculum'],
+            'admin' => ['manage_users', 'view_reports', 'manage_settings', 'access_student_records', 'communicate_parents', 'update_curriculum'],
             'teacher' => ['access_student_records', 'communicate_parents', 'enter_grades', 'access_assignments'],
             'student' => ['view_own_records', 'access_assignments'],
             'parent' => ['view_own_records', 'communicate_parents'],

app/Controllers/ParentProgressController.php

@@ -5,7 +5,9 @@ namespace App\Controllers;
 use App\Controllers\ClassProgressController;
 use App\Models\ClassProgressAttachmentModel;
 use App\Models\ClassProgressReportModel;
+use App\Models\ConfigurationModel;
 use App\Models\EnrollmentModel;
+use App\Services\SemesterRangeService;
 use CodeIgniter\Database\BaseConnection;
 use CodeIgniter\Exceptions\PageNotFoundException;
 use Config\Database;
@@ -15,8 +17,10 @@ class ParentProgressController extends BaseController
     protected ClassProgressReportModel $reportModel;
     protected ClassProgressAttachmentModel $attachmentModel;
     protected EnrollmentModel $enrollmentModel;
+    protected ConfigurationModel $configModel;
     protected BaseConnection $db;
     private ?array $parentSectionIds = null;
+    private array $parentSectionIdsByYear = [];
 
     public function __construct()
     {
@@ -24,11 +28,13 @@ class ParentProgressController extends BaseController
         $this->reportModel = new ClassProgressReportModel();
         $this->attachmentModel = new ClassProgressAttachmentModel();
         $this->enrollmentModel = new EnrollmentModel();
+        $this->configModel = new ConfigurationModel();
         $this->db = Database::connect();
     }
 
     public function index()
     {
+        $schoolYear = $this->currentSchoolYearName();
         $students = $this->getParentStudents();
         $sectionIds = array_values(array_unique(array_filter(array_map(
             static fn (array $student): int => (int) ($student['class_section_id'] ?? 0),
@@ -43,6 +49,7 @@ class ParentProgressController extends BaseController
                 ->join('classSection cs', 'cs.class_section_id = class_progress_reports.class_section_id', 'left')
                 ->join('users u', 'u.id = class_progress_reports.teacher_id', 'left')
                 ->whereIn('class_progress_reports.class_section_id', $sectionIds);
+            $this->applyProgressSchoolYearScope($builder, $schoolYear);
 
             $rows = $builder
                 ->orderBy('week_start', 'DESC')
@@ -75,23 +82,34 @@ class ParentProgressController extends BaseController
 
     public function view($id)
     {
+        $schoolYear = $this->currentSchoolYearName();
         $row = $this->reportModel
             ->select('class_progress_reports.*, cs.class_section_name, CONCAT(IFNULL(u.firstname, ""), " ", IFNULL(u.lastname, "")) AS teacher_name')
             ->join('classSection cs', 'cs.class_section_id = class_progress_reports.class_section_id', 'left')
             ->join('users u', 'u.id = class_progress_reports.teacher_id', 'left')
-            ->find((int) $id);
+            ->where('class_progress_reports.id', (int) $id)
+            ->first();
 
-        if (! $row || ! $this->isSectionAccessible($row['class_section_id'] ?? null)) {
+        if (! $row) {
+            throw new PageNotFoundException('Progress report not found.');
+        }
+
+        $reportSchoolYear = trim((string) ($row['school_year'] ?? ''));
+        $effectiveSchoolYear = $reportSchoolYear !== '' ? $reportSchoolYear : $schoolYear;
+
+        if (! $this->isSectionAccessible($row['class_section_id'] ?? null, $effectiveSchoolYear)) {
             throw new PageNotFoundException('Progress report not found.');
         }
 
         $row['status_label'] = ClassProgressController::STATUS_OPTIONS[$row['status']] ?? 'Unknown';
         $row['flags'] = $this->decodeFlags($row['flags_json']);
 
-        $weeklyReports = $this->reportModel
+        $weeklyReportsQuery = $this->reportModel
             ->select('class_progress_reports.*')
             ->where('class_section_id', $row['class_section_id'])
-            ->where('week_start', $row['week_start'])
+            ->where('week_start', $row['week_start']);
+        $this->applyProgressSchoolYearScope($weeklyReportsQuery, $effectiveSchoolYear);
+        $weeklyReports = $weeklyReportsQuery
             ->orderBy('subject', 'ASC')
             ->findAll();
 
@@ -117,7 +135,14 @@ class ParentProgressController extends BaseController
     public function attachment($id)
     {
         $row = $this->reportModel->find((int) $id);
-        if (! $row || ! $this->isSectionAccessible($row['class_section_id'] ?? null) || empty($row['attachment_path'])) {
+        if (! $row) {
+            throw new PageNotFoundException('Attachment not found.');
+        }
+
+        $reportSchoolYear = trim((string) ($row['school_year'] ?? ''));
+        $effectiveSchoolYear = $reportSchoolYear !== '' ? $reportSchoolYear : $this->currentSchoolYearName();
+
+        if (! $this->isSectionAccessible($row['class_section_id'] ?? null, $effectiveSchoolYear) || empty($row['attachment_path'])) {
             throw new PageNotFoundException('Attachment not found.');
         }
 
@@ -137,7 +162,14 @@ class ParentProgressController extends BaseController
         }
 
         $report = $this->reportModel->find((int) ($attachment['report_id'] ?? 0));
-        if (! $report || ! $this->isSectionAccessible($report['class_section_id'] ?? null)) {
+        if (! $report) {
+            throw new PageNotFoundException('Attachment not found.');
+        }
+
+        $reportSchoolYear = trim((string) ($report['school_year'] ?? ''));
+        $effectiveSchoolYear = $reportSchoolYear !== '' ? $reportSchoolYear : $this->currentSchoolYearName();
+
+        if (! $this->isSectionAccessible($report['class_section_id'] ?? null, $effectiveSchoolYear)) {
             throw new PageNotFoundException('Attachment not found.');
         }
 
@@ -150,21 +182,30 @@ class ParentProgressController extends BaseController
         return $this->response->download($file, null)->setFileName($downloadName);
     }
 
-    protected function getParentSectionIds(): array
+    protected function getParentSectionIds(?string $schoolYear = null): array
     {
-        if ($this->parentSectionIds !== null) {
+        $schoolYear = trim((string) ($schoolYear ?? $this->currentSchoolYearName()));
+        if ($schoolYear === $this->currentSchoolYearName() && $this->parentSectionIds !== null) {
             return $this->parentSectionIds;
         }
 
+        if (isset($this->parentSectionIdsByYear[$schoolYear])) {
+            return $this->parentSectionIdsByYear[$schoolYear];
+        }
+
         $parentId = (int) session()->get('user_id');
         if ($parentId === 0) {
-            $this->parentSectionIds = [];
-            return $this->parentSectionIds;
+            $this->parentSectionIdsByYear[$schoolYear] = [];
+            if ($schoolYear === $this->currentSchoolYearName()) {
+                $this->parentSectionIds = [];
+            }
+            return [];
         }
 
         $rows = $this->enrollmentModel
             ->select('class_section_id')
             ->where('parent_id', $parentId)
+            ->where('school_year', $schoolYear)
             ->where('is_withdrawn', 0)
             ->groupBy('class_section_id')
             ->findAll();
@@ -177,8 +218,12 @@ class ParentProgressController extends BaseController
             }
         }
 
-        $this->parentSectionIds = array_values(array_unique($ids));
-        return $this->parentSectionIds;
+        $ids = array_values(array_unique($ids));
+        $this->parentSectionIdsByYear[$schoolYear] = $ids;
+        if ($schoolYear === $this->currentSchoolYearName()) {
+            $this->parentSectionIds = $ids;
+        }
+        return $ids;
     }
 
     protected function buildSectionOptions(array $sectionIds): array
@@ -213,6 +258,7 @@ class ParentProgressController extends BaseController
             ->join('students s', 's.id = e.student_id')
             ->join('classSection cs', 'cs.class_section_id = e.class_section_id', 'left')
             ->where('e.parent_id', $parentId)
+            ->where('e.school_year', $this->currentSchoolYearName())
             ->where('e.is_withdrawn', 0)
             ->orderBy('e.updated_at', 'DESC')
             ->orderBy('e.created_at', 'DESC')
@@ -256,12 +302,50 @@ class ParentProgressController extends BaseController
         return $reportGroups;
     }
 
-    protected function isSectionAccessible(?int $classSectionId): bool
+    protected function isSectionAccessible(?int $classSectionId, ?string $schoolYear = null): bool
     {
         if (! $classSectionId) {
             return false;
         }
-        return in_array((int) $classSectionId, $this->getParentSectionIds(), true);
+        return in_array((int) $classSectionId, $this->getParentSectionIds($schoolYear), true);
+    }
+
+    protected function applyProgressSchoolYearScope($builder, string $schoolYear): void
+    {
+        if ($schoolYear === '') {
+            return;
+        }
+
+        $hasReportYear = $this->db->fieldExists('school_year', 'class_progress_reports');
+        $semesterResolver = new SemesterRangeService($this->configModel);
+        [$rangeStart, $rangeEnd] = $semesterResolver->getSchoolYearRange($schoolYear);
+
+        if ($hasReportYear) {
+            if ($rangeStart !== '' && $rangeEnd !== '') {
+                $builder
+                    ->groupStart()
+                        ->where('class_progress_reports.school_year', $schoolYear)
+                        ->orGroupStart()
+                            ->groupStart()
+                                ->where('class_progress_reports.school_year IS NULL', null, false)
+                                ->orWhere('class_progress_reports.school_year', '')
+                            ->groupEnd()
+                            ->where('class_progress_reports.week_start >=', $rangeStart)
+                            ->where('class_progress_reports.week_start <=', $rangeEnd)
+                        ->groupEnd()
+                    ->groupEnd();
+                return;
+            }
+
+            $builder->where('class_progress_reports.school_year', $schoolYear);
+            return;
+        }
+
+        if ($rangeStart !== '' && $rangeEnd !== '') {
+            $builder
+                ->where('class_progress_reports.week_start >=', $rangeStart)
+                ->where('class_progress_reports.week_start <=', $rangeEnd);
+        }
     }
 
     protected function resolveAttachmentFile(array $row): ?string

app/Controllers/ParentReportCardController.php

@@ -2,6 +2,7 @@
 
 namespace App\Controllers;
 
+use App\Exceptions\SchoolYear\SchoolYearWriteConflictException;
 use App\Models\ConfigurationModel;
 use App\Models\ReportCardAcknowledgementModel;
 use App\Models\StudentModel;
@@ -31,8 +32,9 @@ class ParentReportCardController extends BaseController
             return redirect()->back()->with('error', 'Unable to retrieve student data. Please contact support.');
         }
 
-        $schoolYear = trim((string) ($this->request->getGet('school_year') ?? $this->configModel->getConfig('school_year') ?? ''));
-        $semester = trim((string) ($this->request->getGet('semester') ?? $this->configModel->getConfig('semester') ?? ''));
+        $schoolYearContext = $this->resolveSchoolYearContext();
+        $schoolYear = trim($schoolYearContext->yearName());
+        $semesterOptions = $this->semesterOptions($schoolYear, '');
 
         $builder = $this->db->table('students s')
             ->select('s.id, s.firstname, s.lastname, cs.class_section_name')
@@ -45,31 +47,44 @@ class ParentReportCardController extends BaseController
         if ($schoolYear !== '') {
             $builder->where('sc.school_year', $schoolYear);
         }
-        if ($semester !== '') {
-            $builder->where('sc.semester', $semester);
-        }
 
-        $students = $builder->get()->getResultArray();
+        $students = $this->uniqueStudentRows($builder->get()->getResultArray());
         $studentIds = array_values(array_filter(array_map(static fn ($s) => (int) ($s['id'] ?? 0), $students)));
 
         $ackMap = [];
+        $reportAvailableMap = $this->reportAvailabilityMap($studentIds, $schoolYear);
         if (! empty($studentIds)) {
-            $rows = $this->ackModel
+            $ackQuery = $this->ackModel
                 ->where('parent_id', $parentId)
                 ->where('school_year', $schoolYear)
-                ->where('semester', $semester)
-                ->whereIn('student_id', $studentIds)
-                ->findAll();
+                ->whereIn('student_id', $studentIds);
+
+            $rows = $ackQuery->findAll();
             foreach ($rows as $row) {
-                $ackMap[(int) $row['student_id']] = $row;
+                $semester = $this->selectedSemester($row['semester'] ?? '');
+                $ackMap[$this->semesterStudentKey((int) $row['student_id'], $semester)] = $row;
+            }
+        }
+
+        $reportRows = [];
+        foreach ($students as $student) {
+            foreach ($semesterOptions as $semester) {
+                $reportRows[] = [
+                    'student' => $student,
+                    'semester' => $semester,
+                    'key' => $this->semesterStudentKey((int) ($student['id'] ?? 0), $semester),
+                ];
             }
         }
 
         return view('parent/report_cards', [
             'students' => $students,
+            'reportRows' => $reportRows,
             'ackMap' => $ackMap,
+            'reportAvailableMap' => $reportAvailableMap,
             'schoolYear' => $schoolYear,
-            'semester' => $semester,
+            'semesterOptions' => $semesterOptions,
+            'isEditable' => ! $schoolYearContext->isReadonly(),
         ]);
     }
 
@@ -85,12 +100,20 @@ class ParentReportCardController extends BaseController
             throw new PageNotFoundException('Student not found.');
         }
 
-        $schoolYear = trim((string) ($this->request->getGet('school_year') ?? $this->configModel->getConfig('school_year') ?? ''));
-        $semester = trim((string) ($this->request->getGet('semester') ?? $this->configModel->getConfig('semester') ?? ''));
+        $schoolYearContext = $this->resolveSchoolYearContext();
+        $schoolYear = trim($schoolYearContext->yearName());
+        $semester = $this->selectedSemester($this->request->getGet('semester'));
 
-        $this->touchAcknowledgement($parentId, (int) $studentId, $schoolYear, $semester, [
-            'viewed_at' => date('Y-m-d H:i:s'),
-        ]);
+        if (! $this->reportExists((int) $studentId, $schoolYear, $semester)) {
+            return redirect()->to(site_url('parent/report-cards'))
+                ->with('error', 'No report card exists for the selected school year and semester.');
+        }
+
+        if (! $schoolYearContext->isReadonly()) {
+            $this->touchAcknowledgement($parentId, (int) $studentId, $schoolYear, $semester, [
+                'viewed_at' => date('Y-m-d H:i:s'),
+            ]);
+        }
 
         $url = site_url('report-card/student/' . (int) $studentId);
         $query = [];
@@ -114,6 +137,13 @@ class ParentReportCardController extends BaseController
             return redirect()->back()->with('error', 'Unable to retrieve student data. Please contact support.');
         }
 
+        $schoolYearContext = $this->resolveSchoolYearContext();
+        try {
+            $this->assertSchoolYearWritable($schoolYearContext);
+        } catch (SchoolYearWriteConflictException $e) {
+            return redirect()->back()->withInput()->with('error', $e->getMessage());
+        }
+
         $student = $this->studentModel->find((int) $studentId);
         if (! $student || (int) ($student['parent_id'] ?? 0) !== $parentId) {
             throw new PageNotFoundException('Student not found.');
@@ -124,8 +154,14 @@ class ParentReportCardController extends BaseController
             return redirect()->back()->with('error', 'Please type your full name to sign.');
         }
 
-        $schoolYear = trim((string) ($this->configModel->getConfig('school_year') ?? ''));
-        $semester = trim((string) ($this->configModel->getConfig('semester') ?? ''));
+        $schoolYear = trim($schoolYearContext->yearName());
+        $semester = $this->selectedSemester($this->request->getPost('semester'));
+
+        if (! $this->reportExists((int) $studentId, $schoolYear, $semester)) {
+            return redirect()->to(site_url('parent/report-cards'))
+                ->with('error', 'No report card exists for the selected school year and semester.');
+        }
+
         $now = date('Y-m-d H:i:s');
         $this->touchAcknowledgement($parentId, (int) $studentId, $schoolYear, $semester, [
             'viewed_at' => $now,
@@ -137,6 +173,78 @@ class ParentReportCardController extends BaseController
         return redirect()->to(site_url('parent/report-cards'))->with('success', 'Report card acknowledged.');
     }
 
+    protected function selectedSemester($semester): string
+    {
+        $selected = trim((string) ($semester ?? ''));
+        if ($selected === '') {
+            $selected = trim((string) (getSemester() ?? ''));
+        }
+
+        $normalized = strtolower($selected);
+        if ($normalized === 'fall' || $normalized === 'first' || str_contains($normalized, 'fall') || str_contains($normalized, '1')) {
+            return 'Fall';
+        }
+        if ($normalized === 'spring' || $normalized === 'second' || str_contains($normalized, 'spring') || str_contains($normalized, '2')) {
+            return 'Spring';
+        }
+
+        return $selected !== '' ? $selected : 'Fall';
+    }
+
+    protected function uniqueStudentRows(array $students): array
+    {
+        $unique = [];
+        foreach ($students as $student) {
+            $studentId = (int) ($student['id'] ?? 0);
+            if ($studentId <= 0) {
+                continue;
+            }
+
+            if (! isset($unique[$studentId])) {
+                $unique[$studentId] = $student;
+                continue;
+            }
+
+            if (
+                empty($unique[$studentId]['class_section_name'])
+                && ! empty($student['class_section_name'])
+            ) {
+                $unique[$studentId]['class_section_name'] = $student['class_section_name'];
+            }
+        }
+
+        return array_values($unique);
+    }
+
+    protected function semesterOptions(string $schoolYear, string $selectedSemester): array
+    {
+        $options = ['Fall', 'Spring'];
+
+        if ($schoolYear !== '') {
+            $rows = $this->db->table('semester_scores')
+                ->select('DISTINCT semester', false)
+                ->where('school_year', $schoolYear)
+                ->where('semester IS NOT NULL', null, false)
+                ->where('semester !=', '')
+                ->orderBy('semester', 'ASC')
+                ->get()
+                ->getResultArray();
+
+            foreach ($rows as $row) {
+                $semester = $this->selectedSemester($row['semester'] ?? '');
+                if ($semester !== '' && ! in_array($semester, $options, true)) {
+                    $options[] = $semester;
+                }
+            }
+        }
+
+        if ($selectedSemester !== '' && ! in_array($selectedSemester, $options, true)) {
+            $options[] = $selectedSemester;
+        }
+
+        return array_values(array_unique($options));
+    }
+
     protected function resolvePrimaryParentId(): ?int
     {
         $parentId = (int) (session()->get('user_id') ?? 0);
@@ -163,6 +271,81 @@ class ParentReportCardController extends BaseController
         return $parentId ?: null;
     }
 
+    protected function reportAvailabilityMap(array $studentIds, string $schoolYear): array
+    {
+        $studentIds = array_values(array_filter(array_map('intval', $studentIds), static fn ($id) => $id > 0));
+        if (empty($studentIds) || $schoolYear === '') {
+            return [];
+        }
+
+        $builder = $this->db->table('semester_scores')
+            ->select('student_id, semester')
+            ->whereIn('student_id', $studentIds)
+            ->where('school_year', $schoolYear);
+
+        $rows = $builder
+            ->groupBy('student_id, semester')
+            ->get()
+            ->getResultArray();
+
+        $map = [];
+        foreach ($rows as $row) {
+            $sid = (int) ($row['student_id'] ?? 0);
+            if ($sid > 0) {
+                $semester = $this->selectedSemester($row['semester'] ?? '');
+                $map[$this->semesterStudentKey($sid, $semester)] = true;
+            }
+        }
+
+        return $map;
+    }
+
+    protected function semesterStudentKey(int $studentId, string $semester): string
+    {
+        return $studentId . '|' . $this->selectedSemester($semester);
+    }
+
+    protected function reportExists(int $studentId, string $schoolYear, string $semester): bool
+    {
+        if ($studentId <= 0 || $schoolYear === '') {
+            return false;
+        }
+
+        $builder = $this->db->table('semester_scores')
+            ->select('id')
+            ->where('student_id', $studentId)
+            ->where('school_year', $schoolYear)
+            ->limit(1);
+
+        $semesterVariants = $this->semesterVariants($semester);
+        if (! empty($semesterVariants)) {
+            $builder->whereIn('semester', $semesterVariants);
+        }
+
+        return (bool) $builder->get()->getRowArray();
+    }
+
+    protected function semesterVariants(string $semester): array
+    {
+        $raw = trim($semester);
+        if ($raw === '') {
+            return [];
+        }
+
+        $normalized = strtolower($raw);
+        if ($normalized === 'fall' || $normalized === 'first' || str_contains($normalized, 'fall') || str_contains($normalized, '1')) {
+            $values = ['Fall', 'fall', 'First', 'first', 'Semester 1', 'semester 1', 'Semester1', 'semester1', 'Sem 1', 'sem 1', '1', '01', 'S1', 's1'];
+        } elseif ($normalized === 'spring' || $normalized === 'second' || str_contains($normalized, 'spring') || str_contains($normalized, '2')) {
+            $values = ['Spring', 'spring', 'Second', 'second', 'Semester 2', 'semester 2', 'Semester2', 'semester2', 'Sem 2', 'sem 2', '2', '02', 'S2', 's2'];
+        } else {
+            $values = [$raw];
+        }
+
+        $values[] = $raw;
+
+        return array_values(array_unique($values));
+    }
+
     protected function touchAcknowledgement(
         int $parentId,
         int $studentId,

app/Controllers/PrintRequests.php

@@ -12,6 +12,7 @@ use App\Models\TeacherClassModel;
 use App\Models\AdminNotificationSubjectModel;
 use App\Models\NotificationModel;
 use App\Models\UserNotificationModel;
+use App\Services\SemesterRangeService;
 use CodeIgniter\Exceptions\PageNotFoundException;
 
 class PrintRequests extends BaseController
@@ -46,54 +47,76 @@ class PrintRequests extends BaseController
     public function teacher_index()
     {
         $teacher_id = session()->get('user_id');
+        $context = $this->resolveSchoolYearContext();
+        $schoolYear = $context->yearName();
         
-        $data['print_requests'] = $this->printRequestModel
+        $printRequestsQuery = $this->printRequestModel
+            ->distinct()
             ->select('print_requests.*, admins.firstname as admin_firstname, admins.lastname as admin_lastname')
             ->join('users as admins', 'admins.id = print_requests.admin_id', 'left')
-            ->where('print_requests.teacher_id', $teacher_id)
+            ->join('classSection cs', 'cs.class_section_id = print_requests.class_id', 'left')
+            ->where('print_requests.teacher_id', $teacher_id);
+        $this->applyPrintRequestSchoolYearScope($printRequestsQuery, $schoolYear);
+        $data['print_requests'] = $printRequestsQuery
+            ->orderBy('print_requests.required_by', 'DESC')
+            ->orderBy('print_requests.id', 'DESC')
             ->findAll();
 
-        $teacher_classes = $this->teacherClassModel->getClassByTeacherId($teacher_id);
+        $teacher_classes = $this->teacherClassModel->getClassAssignmentsByUserId((int) $teacher_id, $schoolYear);
         $data['class_id'] = !empty($teacher_classes) ? $teacher_classes[0]['class_section_id'] : null;
         $dateOptions = $this->buildRequiredByOptions();
         $data['sundays'] = $dateOptions['sundays'];
         $data['times'] = $dateOptions['times'];
+        $data['isSchoolYearReadonly'] = $context->isReadonly();
+        $data['printRequestToken'] = $this->issuePrintRequestToken('print');
+        $data['copyRequestToken'] = $this->issuePrintRequestToken('copy');
 
         return view('print_requests/teacher_index', $data);
     }
 
     public function admin_index()
     {
-        $db = \Config\Database::connect();
-        $query = $db->query("
-            SELECT 
-                pr.*, 
-                u.firstname, 
-                u.lastname, 
+        $context = $this->resolveSchoolYearContext();
+        $schoolYear = $context->yearName();
+
+        $printRequestsQuery = $this->printRequestModel
+            ->distinct()
+            ->select('
+                print_requests.*,
+                u.firstname,
+                u.lastname,
                 cs.class_section_name,
                 admins.firstname AS admin_firstname,
                 admins.lastname AS admin_lastname
-            FROM print_requests pr
-            LEFT JOIN users u ON u.id = pr.teacher_id
-            LEFT JOIN classSection cs ON cs.class_section_id = pr.class_id
-            LEFT JOIN users admins ON admins.id = pr.admin_id
-            ORDER BY
+            ')
+            ->join('users u', 'u.id = print_requests.teacher_id', 'left')
+            ->join('classSection cs', 'cs.class_section_id = print_requests.class_id', 'left')
+            ->join('users admins', 'admins.id = print_requests.admin_id', 'left');
+
+        $this->applyPrintRequestSchoolYearScope($printRequestsQuery, $schoolYear);
+
+        $data['print_requests'] = $printRequestsQuery
+            ->orderBy("
                 CASE
-                    WHEN pr.status = 'not_assigned' THEN 1
-                    WHEN pr.status = 'assigned' THEN 2
-                    WHEN pr.status = 'done' THEN 3
-                    WHEN pr.status = 'delivered' THEN 4
+                    WHEN print_requests.status = 'not_assigned' THEN 1
+                    WHEN print_requests.status = 'assigned' THEN 2
+                    WHEN print_requests.status = 'done' THEN 3
+                    WHEN print_requests.status = 'delivered' THEN 4
                     ELSE 5
-                END ASC,
-                pr.required_by ASC
-        ");
-        $data['print_requests'] = $query->getResultArray();
+                END
+            ", 'ASC', false)
+            ->orderBy('print_requests.required_by', 'ASC')
+            ->findAll();
+        $data['isSchoolYearReadonly'] = $context->isReadonly();
 
         return view('print_requests/admin_index', $data);
     }
 
     public function create()
     {
+        $context = $this->resolveSchoolYearContext();
+        $this->assertSchoolYearWritable($context);
+        $schoolYear = $context->yearName();
         $validationRules = [
             'file' => 'uploaded[file]|max_size[file,5120]|ext_in[file,pdf,jpg,png,jpeg,doc,docx,txt]',
             'page_selection' => 'permit_empty|regex_match[/^\\s*\\d+(?:\\s*-\\s*\\d+)?(?:\\s*,\\s*\\d+(?:\\s*-\\s*\\d+)?)*\\s*$/]',
@@ -106,6 +129,10 @@ class PrintRequests extends BaseController
             return redirect()->back()->withInput()->with('errors', $this->validator->getErrors());
         }
 
+        if (! $this->consumePrintRequestToken('print')) {
+            return redirect()->to('teacher/print-requests')->with('error', 'This print request was already submitted. Please refresh the page before submitting another request.');
+        }
+
         $teacher_id = session()->get('user_id');
 
         $file = $this->request->getFile('file');
@@ -125,7 +152,7 @@ class PrintRequests extends BaseController
             'required_by' => $this->request->getPost('required_by'),
             'pickup_method' => $this->request->getPost('pickup_method'),
             'status' => 'not_assigned',
-        ];
+        ] + $this->printRequestSchoolYearData($schoolYear);
 
         $printRequestId = (int) $this->printRequestModel->insert($data, true);
         if ($printRequestId > 0) {
@@ -144,6 +171,7 @@ class PrintRequests extends BaseController
 
         // Case 1: Admin status update
         if ($this->request->getPost('status')) {
+            $this->assertSchoolYearWritable($this->resolveSchoolYearContext());
             $user_id = session()->get('user_id');
             $current_status = $request['status'];
             $new_status = $this->request->getPost('status');
@@ -175,6 +203,7 @@ class PrintRequests extends BaseController
 
         // Case 2: Teacher edit
         if ($this->request->getPost('num_copies')) {
+            $this->assertSchoolYearWritable($this->resolveSchoolYearContext());
             $user_id = session()->get('user_id');
             if ($request['teacher_id'] != $user_id) {
                 return redirect()->to('teacher/print-requests')->with('error', 'You are not authorized to edit this request.');
@@ -230,6 +259,7 @@ class PrintRequests extends BaseController
     
     public function delete($id)
     {
+        $this->assertSchoolYearWritable($this->resolveSchoolYearContext());
         $teacher_id = session()->get('user_id');
         $request = $this->printRequestModel->find($id);
 
@@ -260,6 +290,9 @@ class PrintRequests extends BaseController
     public function copy($id)
     {
         $teacher_id = session()->get('user_id');
+        $context = $this->resolveSchoolYearContext();
+        $this->assertSchoolYearWritable($context);
+        $schoolYear = $context->yearName();
         $request = $this->printRequestModel->find($id);
 
         if (!$request) {
@@ -296,7 +329,7 @@ class PrintRequests extends BaseController
             'required_by' => $request['required_by'],
             'pickup_method' => $request['pickup_method'],
             'status' => 'not_assigned',
-        ];
+        ] + $this->printRequestSchoolYearData($schoolYear);
 
         $copiedId = (int) $this->printRequestModel->insert($data, true);
         if ($copiedId > 0) {
@@ -308,6 +341,9 @@ class PrintRequests extends BaseController
 
     public function createCopy()
     {
+        $context = $this->resolveSchoolYearContext();
+        $this->assertSchoolYearWritable($context);
+        $schoolYear = $context->yearName();
         $validationRules = [
             'num_copies' => 'required|integer|greater_than[0]',
             'required_by' => 'required|valid_date',
@@ -318,6 +354,10 @@ class PrintRequests extends BaseController
             return redirect()->back()->withInput()->with('errors', $this->validator->getErrors());
         }
 
+        if (! $this->consumePrintRequestToken('copy')) {
+            return redirect()->to('teacher/print-requests')->with('error', 'This copy request was already submitted. Please refresh the page before submitting another request.');
+        }
+
         $teacher_id = session()->get('user_id');
 
         $data = [
@@ -329,7 +369,7 @@ class PrintRequests extends BaseController
             'required_by' => $this->request->getPost('required_by'),
             'pickup_method' => $this->request->getPost('pickup_method'),
             'status' => 'not_assigned',
-        ];
+        ] + $this->printRequestSchoolYearData($schoolYear);
 
         $printRequestId = (int) $this->printRequestModel->insert($data, true);
         if ($printRequestId > 0) {
@@ -374,6 +414,143 @@ class PrintRequests extends BaseController
         ];
     }
 
+    private function issuePrintRequestToken(string $type): string
+    {
+        $key = $this->printRequestTokenSessionKey($type);
+        $tokens = session()->get($key);
+
+        if (! is_array($tokens)) {
+            $tokens = [];
+        }
+
+        $token = bin2hex(random_bytes(16));
+        $tokens[$token] = time();
+
+        if (count($tokens) > 20) {
+            asort($tokens);
+            $tokens = array_slice($tokens, -20, null, true);
+        }
+
+        session()->set($key, $tokens);
+
+        return $token;
+    }
+
+    private function consumePrintRequestToken(string $type): bool
+    {
+        $token = (string) $this->request->getPost('request_token');
+
+        if ($token === '') {
+            return false;
+        }
+
+        $key = $this->printRequestTokenSessionKey($type);
+        $tokens = session()->get($key);
+
+        if (! is_array($tokens) || ! array_key_exists($token, $tokens)) {
+            return false;
+        }
+
+        unset($tokens[$token]);
+        session()->set($key, $tokens);
+
+        return true;
+    }
+
+    private function printRequestTokenSessionKey(string $type): string
+    {
+        return 'print_request_' . $type . '_tokens';
+    }
+
+    private function applyPrintRequestSchoolYearScope($query, string $schoolYear): void
+    {
+        if ($schoolYear === '') {
+            return;
+        }
+
+        $hasPrintRequestYear = $this->printRequestsHaveSchoolYearColumn();
+        $hasClassSectionYear = db_connect()->fieldExists('school_year', 'classSection');
+        $range = (new SemesterRangeService($this->configModel))->getSchoolYearRange($schoolYear);
+        [$rangeStart, $rangeEnd] = $range;
+
+        if ($hasPrintRequestYear && $hasClassSectionYear) {
+            $query->groupStart()
+                ->where('print_requests.school_year', $schoolYear)
+                ->orGroupStart()
+                    ->groupStart()
+                        ->where('print_requests.school_year IS NULL', null, false)
+                        ->orWhere('print_requests.school_year', '')
+                    ->groupEnd()
+                    ->where('cs.school_year', $schoolYear)
+                ->groupEnd();
+
+            if ($rangeStart !== '' && $rangeEnd !== '') {
+                $query
+                    ->orGroupStart()
+                        ->groupStart()
+                            ->where('print_requests.school_year IS NULL', null, false)
+                            ->orWhere('print_requests.school_year', '')
+                        ->groupEnd()
+                        ->groupStart()
+                            ->where('cs.school_year IS NULL', null, false)
+                            ->orWhere('cs.school_year', '')
+                        ->groupEnd()
+                        ->where('print_requests.required_by >=', $rangeStart . ' 00:00:00')
+                        ->where('print_requests.required_by <=', $rangeEnd . ' 23:59:59')
+                    ->groupEnd();
+            }
+
+            $query->groupEnd();
+            return;
+        }
+
+        if (! $hasPrintRequestYear && $hasClassSectionYear) {
+            $query->where('cs.school_year', $schoolYear);
+            return;
+        }
+
+        if ($rangeStart !== '' && $rangeEnd !== '') {
+            if ($hasPrintRequestYear) {
+                $query
+                    ->groupStart()
+                        ->where('print_requests.school_year', $schoolYear)
+                        ->orGroupStart()
+                            ->groupStart()
+                                ->where('print_requests.school_year IS NULL', null, false)
+                                ->orWhere('print_requests.school_year', '')
+                            ->groupEnd()
+                            ->where('print_requests.required_by >=', $rangeStart . ' 00:00:00')
+                            ->where('print_requests.required_by <=', $rangeEnd . ' 23:59:59')
+                        ->groupEnd()
+                    ->groupEnd();
+                return;
+            }
+
+            $query
+                ->where('print_requests.required_by >=', $rangeStart . ' 00:00:00')
+                ->where('print_requests.required_by <=', $rangeEnd . ' 23:59:59');
+            return;
+        }
+
+        if ($hasPrintRequestYear) {
+            $query->where('print_requests.school_year', $schoolYear);
+        }
+    }
+
+    private function printRequestSchoolYearData(string $schoolYear): array
+    {
+        if ($schoolYear === '' || ! $this->printRequestsHaveSchoolYearColumn()) {
+            return [];
+        }
+
+        return ['school_year' => $schoolYear];
+    }
+
+    private function printRequestsHaveSchoolYearColumn(): bool
+    {
+        return db_connect()->fieldExists('school_year', 'print_requests');
+    }
+
     public function serveFile(string $filename, string $mode = 'inline')
     {
         $safeName = basename(trim($filename));
@@ -503,7 +680,7 @@ class PrintRequests extends BaseController
             'action_url' => $isCopyRequest ? '' : $actionUrl,
             'scheduled_at' => utc_now(),
             'school_year' => $this->configModel->getConfig('school_year'),
-            'semester' => $this->configModel->getConfig('semester'),
+            'semester' => getSemester(),
         ];
 
         $notificationFields = $db->getFieldNames('notifications');

app/Controllers/ProofreadController.php

@@ -10,8 +10,13 @@ class ProofreadController extends ResourceController
     {
         // Basic per-IP throttling: 10 requests per minute
         $throttler = service('throttler');
-        $key = 'proofread-' . $this->request->getIPAddress();
-        if (!$throttler->check($key, 10, MINUTE)) {
+
+        // Cache/throttler keys cannot contain reserved characters.
+        // Raw IPv6 addresses contain ":", so hash the IP first.
+        $ip = $this->request->getIPAddress();
+        $key = 'proofread-' . hash('sha256', $ip);
+
+        if (! $throttler->check($key, 10, MINUTE)) {
             return $this->respond([
                 'ok' => false,
                 'error' => 'Too many requests. Try again in a minute.',
@@ -20,29 +25,51 @@ class ProofreadController extends ResourceController
         }
 
         // Accept form-urlencoded payload to play nicely with CSRF protection
-        $text = (string) ($this->request->getPost('text') ?? '');
-        if ($text === '' || mb_strlen($text) > 20000) {
+        $payload = sanitize_request_value($this->request->getPost(['text']));
+
+        $validation = service('validation');
+        $validation->setRules([
+            'text' => 'required|min_length[1]|max_length[20000]',
+        ]);
+
+        if (! $validation->run($payload)) {
             return $this->respond([
                 'ok' => false,
-                'error' => 'Invalid text (empty or too long).',
+                'error' => 'Invalid text payload.',
                 'csrfHash' => csrf_hash(),
             ], 422);
         }
 
-        $client = \Config\Services::curlrequest(['timeout' => 10]);
+        $text = (string) $payload['text'];
+
+        $client = \Config\Services::curlrequest([
+            'timeout' => 10,
+        ]);
 
         try {
             $resp = $client->post('https://api.languagetool.org/v2/check', [
-                'headers' => ['Content-Type' => 'application/x-www-form-urlencoded'],
+                'headers' => [
+                    'Content-Type' => 'application/x-www-form-urlencoded',
+                ],
                 'form_params' => [
                     'text'     => $text,
                     'language' => 'en-US',
                 ],
             ]);
 
+            $result = json_decode($resp->getBody(), true);
+
+            if (json_last_error() !== JSON_ERROR_NONE) {
+                return $this->respond([
+                    'ok' => false,
+                    'error' => 'Invalid response from proofread service.',
+                    'csrfHash' => csrf_hash(),
+                ], 502);
+            }
+
             return $this->respond([
                 'ok' => true,
-                'result' => json_decode($resp->getBody(), true),
+                'result' => $result,
                 'csrfHash' => csrf_hash(),
             ]);
         } catch (\Throwable $e) {
@@ -53,4 +80,4 @@ class ProofreadController extends ResourceController
             ], 502);
         }
     }
-}
+}

app/Controllers/View/AssignmentController.php

@@ -33,7 +33,7 @@ class AssignmentController extends BaseController
         $this->teacherClassModel  = new TeacherClassModel();
         $this->studentClassModel  = new StudentClassModel();
 
-        $this->semester = $this->configModel->getConfig('semester');
+        $this->semester = getSemester();
         $this->schoolYear = $this->configModel->getConfig('school_year');
         
     }
@@ -46,7 +46,35 @@ class AssignmentController extends BaseController
 
         // Apply school year filter (default to current config) but avoid semester filtering so the full year is visible
         $selectedSemester = (string)($this->request->getGet('semester') ?? $this->semester ?? '');
-        $year = (string)($this->request->getGet('school_year') ?? $this->schoolYear ?? '');
+        $year = trim((string)($this->request->getGet('schoolYear') ?? $this->request->getGet('school_year') ?? ''));
+        if ($year === '') {
+            $year = $this->currentSchoolYearName((string)($this->schoolYear ?? ''));
+        }
+
+        $this->applyPendingDistributionDraftsForEnrolledStudents($year);
+        $this->repairMissingEnrollmentClassAssignments($year);
+        $distributedSectionIds = array_values(array_unique(array_merge(
+            $this->distributedClassSectionIds($year),
+            $this->enrollmentAssignedClassSectionIds($year)
+        )));
+
+        $classSectionsAll = [];
+        if (!empty($distributedSectionIds)) {
+            $classSectionsAll = $this->classSectionModel
+                ->select('id, class_section_id, class_section_name, school_year')
+                ->where('school_year', $year)
+                ->whereIn('class_section_id', $distributedSectionIds)
+                ->orderBy('class_section_name', 'ASC')
+                ->findAll();
+        }
+
+        $classSectionById = [];
+        foreach ($classSectionsAll as $section) {
+            $sectionId = (int)($section['class_section_id'] ?? 0);
+            if ($sectionId > 0) {
+                $classSectionById[$sectionId] = $section;
+            }
+        }
 
         $tcQ = $this->teacherClassModel;
         if ($year !== '') {
@@ -71,20 +99,26 @@ class AssignmentController extends BaseController
         $studentsBySection[$sc['class_section_id']][] = $sc;
     }
 
-    $allSectionIds = array_unique(array_merge(array_keys($teacherBySection), array_keys($studentsBySection)));
+    $allSectionIds = array_unique(array_merge(array_keys($classSectionById), array_keys($teacherBySection), array_keys($studentsBySection)));
+    $distributedSectionSet = array_fill_keys($distributedSectionIds, true);
 
     foreach ($allSectionIds as $classSectionId) {
+        if (!isset($distributedSectionSet[(int)$classSectionId])) {
+            continue;
+        }
+
         $teacherClasses = $teacherBySection[$classSectionId] ?? [];
         $studentClasses = $studentsBySection[$classSectionId] ?? [];
 
         $hasTeacher  = !empty($teacherClasses);
         $hasStudents = !empty($studentClasses);
+        $hasClassSection = isset($classSectionById[(int)$classSectionId]);
 
-        if (!$hasTeacher && !$hasStudents) {
+        if (!$hasClassSection && !$hasTeacher && !$hasStudents) {
             continue;
         }
 
-        $classSectionName = (string) ($this->classSectionModel->getClassSectionNameBySectionId($classSectionId) ?? '');
+        $classSectionName = (string) ($classSectionById[(int)$classSectionId]['class_section_name'] ?? $this->classSectionModel->getClassSectionNameBySectionId($classSectionId) ?? '');
 
         $mainTeachers = [];
         $teacherAssistants = [];
@@ -172,14 +206,21 @@ class AssignmentController extends BaseController
     }
 
     $schoolYearsList = [];
-    try {
-        $db = Database::connect();
-        $yearsQuery = $db->table('teacher_class')
+        try {
+            $db = Database::connect();
+            $yearsQuery = $db->table('classSection')
+                ->select('DISTINCT school_year', false)
+                ->where('school_year IS NOT NULL', null, false)
+            ->orderBy('school_year', 'DESC')
+            ->get()
+            ->getResultArray();
+        $studentYearsQuery = $db->table('student_class')
             ->select('DISTINCT school_year', false)
             ->where('school_year IS NOT NULL', null, false)
             ->orderBy('school_year', 'DESC')
             ->get()
             ->getResultArray();
+        $yearsQuery = array_merge($yearsQuery, $studentYearsQuery);
         foreach ($yearsQuery as $row) {
             $val = (string)($row['school_year'] ?? '');
             if ($val !== '' && !in_array($val, $schoolYearsList, true)) {
@@ -189,12 +230,12 @@ class AssignmentController extends BaseController
     } catch (\Throwable $e) {
         // ignore fallback below
     }
-    if (empty($schoolYearsList) && $this->schoolYear !== null && $this->schoolYear !== '') {
-        $schoolYearsList[] = (string)$this->schoolYear;
+    if ($this->schoolYear !== null && $this->schoolYear !== '' && !in_array((string)$this->schoolYear, $schoolYearsList, true)) {
+        array_unshift($schoolYearsList, (string)$this->schoolYear);
     }
 
     // Sort sections
-    usort($data['classSections'], fn($a, $b) => strcmp((string) $a['class_section_name'], (string) $b['class_section_name']));
+    usort($data['classSections'], fn($a, $b) => strnatcasecmp((string) $a['class_section_name'], (string) $b['class_section_name']));
 
     $data['schoolYears'] = $schoolYearsList;
     $data['schoolYear'] = $year;
@@ -204,6 +245,477 @@ class AssignmentController extends BaseController
     return view('administrator/class_assignment', $data);
 }
 
+    private function distributedClassSectionIds(string $year): array
+    {
+        $year = trim($year);
+        if ($year === '') {
+            return [];
+        }
+
+        try {
+            $db = Database::connect();
+            if (! $db->tableExists('student_section_distribution_drafts')) {
+                return [];
+            }
+
+            $baseRows = $db->table('classSection')
+                ->select('class_id, class_section_id, class_section_name')
+                ->where('school_year', $year)
+                ->where("class_section_name NOT LIKE '%-%'", null, false)
+                ->orderBy('class_id', 'ASC')
+                ->get()
+                ->getResultArray();
+
+            $draftRows = $db->table('student_section_distribution_drafts d')
+                ->select('d.class_id, d.class_section_id, COALESCE(cs.class_section_name, d.class_section_id) AS class_section_name', false)
+                ->join(
+                    'classSection cs',
+                    'cs.class_section_id = d.class_section_id AND cs.school_year = d.school_year',
+                    'left',
+                    false
+                )
+                ->where('d.school_year', $year)
+                ->where('d.class_section_id >', 0)
+                ->whereIn('status', ['pending', 'applied'])
+                ->get()
+                ->getResultArray();
+
+            $draftsByClassId = [];
+            foreach ($draftRows as $row) {
+                $classId = (int)($row['class_id'] ?? 0);
+                $sectionId = (int)($row['class_section_id'] ?? 0);
+                if ($classId <= 0 || $sectionId <= 0) {
+                    continue;
+                }
+
+                $draftsByClassId[$classId][$sectionId] = [
+                    'class_section_id' => $sectionId,
+                    'class_section_name' => (string)($row['class_section_name'] ?? ''),
+                ];
+            }
+
+            $allowed = [];
+            $seenClassIds = [];
+            foreach ($baseRows as $row) {
+                $classId = (int)($row['class_id'] ?? 0);
+                $baseSectionId = (int)($row['class_section_id'] ?? 0);
+                $baseName = trim((string)($row['class_section_name'] ?? ''));
+                if ($classId <= 0 || $baseSectionId <= 0 || $baseName === '') {
+                    continue;
+                }
+
+                $normalized = strtolower($baseName);
+                $isAutoDistributeBase = $normalized === 'youth'
+                    || (ctype_digit($normalized) && (int)$normalized >= 1 && (int)$normalized <= 10);
+                if (!$isAutoDistributeBase) {
+                    continue;
+                }
+
+                $seenClassIds[$classId] = true;
+                $classDrafts = $draftsByClassId[$classId] ?? [];
+                $hasBaseDraft = false;
+                $letteredDraftIds = [];
+                foreach ($classDrafts as $draft) {
+                    $draftSectionId = (int)($draft['class_section_id'] ?? 0);
+                    $draftName = trim((string)($draft['class_section_name'] ?? ''));
+                    if ($draftSectionId === $baseSectionId || $draftName === '' || strpos($draftName, '-') === false) {
+                        $hasBaseDraft = true;
+                        continue;
+                    }
+
+                    $letteredDraftIds[] = $draftSectionId;
+                }
+
+                if ($hasBaseDraft || empty($letteredDraftIds)) {
+                    $allowed[] = $baseSectionId;
+                    continue;
+                }
+
+                foreach ($letteredDraftIds as $draftSectionId) {
+                    $allowed[] = $draftSectionId;
+                }
+            }
+
+            foreach ($draftsByClassId as $classId => $classDrafts) {
+                if (isset($seenClassIds[$classId])) {
+                    continue;
+                }
+
+                foreach ($classDrafts as $draft) {
+                    $sectionId = (int)($draft['class_section_id'] ?? 0);
+                    if ($sectionId > 0) {
+                        $allowed[] = $sectionId;
+                    }
+                }
+            }
+
+            return array_values(array_unique(array_filter(
+                $allowed,
+                static fn(int $sectionId): bool => $sectionId > 0
+            )));
+        } catch (\Throwable $e) {
+            log_message('error', 'distributedClassSectionIds failed: ' . $e->getMessage());
+            return [];
+        }
+    }
+
+    private function enrollmentAssignedClassSectionIds(string $year): array
+    {
+        $year = trim($year);
+        if ($year === '') {
+            return [];
+        }
+
+        try {
+            $db = Database::connect();
+            $allowedStatuses = ['admission under review', 'review & decision', 'payment pending', 'enrolled'];
+            $ids = [];
+
+            if ($db->tableExists('enrollments')) {
+                $builder = $db->table('enrollments e')
+                    ->select('e.class_section_id')
+                    ->join('students s', 's.id = e.student_id', 'inner')
+                    ->where('e.school_year', $year)
+                    ->whereIn('e.enrollment_status', $allowedStatuses)
+                    ->where('e.class_section_id IS NOT NULL', null, false)
+                    ->where('e.class_section_id >', 0);
+
+                if ($db->fieldExists('is_active', 'students')) {
+                    $builder->where('s.is_active', 1);
+                }
+                if ($db->fieldExists('is_withdrawn', 'enrollments')) {
+                    $builder->groupStart()
+                        ->where('e.is_withdrawn', 0)
+                        ->orWhere('e.is_withdrawn', null)
+                        ->groupEnd();
+                }
+
+                foreach ($builder->groupBy('e.class_section_id')->get()->getResultArray() as $row) {
+                    $sectionId = (int)($row['class_section_id'] ?? 0);
+                    if ($sectionId > 0) {
+                        $ids[] = $sectionId;
+                    }
+                }
+            }
+
+            if ($db->tableExists('student_class') && $db->tableExists('enrollments')) {
+                $builder = $db->table('student_class sc')
+                    ->select('sc.class_section_id')
+                    ->join(
+                        'enrollments e',
+                        'e.student_id = sc.student_id AND e.school_year = sc.school_year',
+                        'inner',
+                        false
+                    )
+                    ->join('students s', 's.id = sc.student_id', 'inner')
+                    ->where('sc.school_year', $year)
+                    ->whereIn('e.enrollment_status', $allowedStatuses)
+                    ->where('sc.class_section_id IS NOT NULL', null, false)
+                    ->where('sc.class_section_id >', 0);
+
+                if ($db->fieldExists('is_active', 'students')) {
+                    $builder->where('s.is_active', 1);
+                }
+                if ($db->fieldExists('is_event_only', 'student_class')) {
+                    $builder->groupStart()
+                        ->where('sc.is_event_only', 0)
+                        ->orWhere('sc.is_event_only', null)
+                        ->groupEnd();
+                }
+                if ($db->fieldExists('is_withdrawn', 'enrollments')) {
+                    $builder->groupStart()
+                        ->where('e.is_withdrawn', 0)
+                        ->orWhere('e.is_withdrawn', null)
+                        ->groupEnd();
+                }
+
+                foreach ($builder->groupBy('sc.class_section_id')->get()->getResultArray() as $row) {
+                    $sectionId = (int)($row['class_section_id'] ?? 0);
+                    if ($sectionId > 0) {
+                        $ids[] = $sectionId;
+                    }
+                }
+            }
+
+            return array_values(array_unique($ids));
+        } catch (\Throwable $e) {
+            log_message('error', 'enrollmentAssignedClassSectionIds failed: ' . $e->getMessage());
+            return [];
+        }
+    }
+
+    private function applyPendingDistributionDraftsForEnrolledStudents(string $year): void
+    {
+        if ($year === '') {
+            return;
+        }
+
+        try {
+            $db = Database::connect();
+            if (! $db->tableExists('student_section_distribution_drafts')) {
+                return;
+            }
+
+            $rows = $db->table('student_section_distribution_drafts d')
+                ->select('d.id, d.student_id, d.class_section_id')
+                ->join(
+                    'enrollments e',
+                    'e.student_id = d.student_id AND e.school_year = d.school_year',
+                    'inner'
+                )
+                ->where('d.school_year', $year)
+                ->where('d.status', 'pending')
+                ->whereIn('e.enrollment_status', ['admission under review', 'payment pending', 'enrolled'])
+                ->groupBy('d.id, d.student_id, d.class_section_id')
+                ->get()
+                ->getResultArray();
+
+            if (empty($rows)) {
+                return;
+            }
+
+            $now = utc_now();
+            $updatedBy = (int)(session()->get('user_id') ?? 0) ?: null;
+
+            $db->transStart();
+            foreach ($rows as $row) {
+                $studentId = (int)($row['student_id'] ?? 0);
+                $sectionId = (int)($row['class_section_id'] ?? 0);
+                if ($studentId <= 0 || $sectionId <= 0) {
+                    continue;
+                }
+
+                $existing = $db->table('student_class')
+                    ->select('id')
+                    ->where('student_id', $studentId)
+                    ->where('school_year', $year)
+                    ->get()
+                    ->getRowArray();
+
+                $payload = [
+                    'student_id'       => $studentId,
+                    'class_section_id' => $sectionId,
+                    'school_year'      => $year,
+                    'updated_by'       => $updatedBy,
+                    'updated_at'       => $now,
+                ];
+
+                if ($existing) {
+                    $db->table('student_class')
+                        ->where('id', (int)$existing['id'])
+                        ->update($payload);
+                } else {
+                    $payload['created_at'] = $now;
+                    $db->table('student_class')->insert($payload);
+                }
+
+                $db->table('enrollments')
+                    ->where('student_id', $studentId)
+                    ->where('school_year', $year)
+                    ->whereIn('enrollment_status', ['admission under review', 'payment pending', 'enrolled'])
+                    ->update([
+                        'class_section_id'          => $sectionId,
+                        'assigned_class_section_id' => $sectionId,
+                        'placement_status'          => 'automatic_distribution_applied',
+                        'updated_at'                => $now,
+                    ]);
+
+                $db->table('student_section_distribution_drafts')
+                    ->where('id', (int)$row['id'])
+                    ->update([
+                        'status'     => 'applied',
+                        'applied_at' => $now,
+                        'updated_at' => $now,
+                    ]);
+            }
+            $db->transComplete();
+        } catch (\Throwable $e) {
+            log_message('error', 'applyPendingDistributionDraftsForEnrolledStudents failed: ' . $e->getMessage());
+        }
+    }
+
+    private function repairMissingEnrollmentClassAssignments(string $year): void
+    {
+        if ($year === '') {
+            return;
+        }
+
+        try {
+            $db = Database::connect();
+            $this->ensureClassSectionsForYear($db, $year);
+            if (! $db->tableExists('enrollments') || ! $db->tableExists('student_class')) {
+                return;
+            }
+
+            $previousYear = $this->previousSchoolYearName($year);
+            if ($previousYear === null) {
+                return;
+            }
+
+            $rows = $db->table('enrollments e')
+                ->select('e.student_id, e.school_year, e.enrollment_status, e.class_section_id, sc.id AS student_class_id')
+                ->join('student_class sc', 'sc.student_id = e.student_id AND sc.school_year = e.school_year', 'left')
+                ->where('e.school_year', $year)
+                ->whereIn('e.enrollment_status', ['admission under review', 'payment pending', 'enrolled'])
+                ->groupStart()
+                    ->where('e.class_section_id', null)
+                    ->orWhere('e.class_section_id', 0)
+                    ->orWhere('sc.id', null)
+                ->groupEnd()
+                ->groupBy('e.student_id, e.school_year, e.enrollment_status, e.class_section_id, sc.id')
+                ->get()
+                ->getResultArray();
+
+            foreach ($rows as $row) {
+                $studentId = (int)($row['student_id'] ?? 0);
+                if ($studentId <= 0) {
+                    continue;
+                }
+
+                $evaluation = service('enrollmentTransition')->evaluate($studentId, $previousYear, $year, 'admin');
+                if (!($evaluation['academic_eligible'] ?? false) || ($evaluation['blockers'] ?? []) !== []) {
+                    continue;
+                }
+
+                $targetSectionId = (int)($evaluation['assigned_class_section_id'] ?? 0);
+                if ($targetSectionId <= 0 && (int)($evaluation['assigned_grade_id'] ?? 0) > 0) {
+                    $base = $this->baseSectionForClassYear((int)$evaluation['assigned_grade_id'], $year);
+                    $targetSectionId = (int)($base['class_section_id'] ?? 0);
+                }
+
+                if ($targetSectionId <= 0) {
+                    continue;
+                }
+
+                $placementStatus = match ((string)($evaluation['placement_status'] ?? '')) {
+                    'automatic_distribution_pending' => 'base_section_pending_distribution',
+                    'same_class_assigned', 'temporary_same_grade' => (string)$evaluation['placement_status'],
+                    default => 'manual_class_assigned',
+                };
+
+                $existing = $db->table('student_class')
+                    ->select('id')
+                    ->where('student_id', $studentId)
+                    ->where('school_year', $year)
+                    ->orderBy('id', 'DESC')
+                    ->limit(1)
+                    ->get()
+                    ->getRowArray();
+
+                $studentClassPayload = [
+                    'student_id' => $studentId,
+                    'class_section_id' => $targetSectionId,
+                    'school_year' => $year,
+                    'updated_by' => (int)(session()->get('user_id') ?? 0) ?: null,
+                    'updated_at' => utc_now(),
+                ];
+
+                if ($existing !== null) {
+                    $db->table('student_class')->where('id', (int)$existing['id'])->update($studentClassPayload);
+                } else {
+                    $studentClassPayload['created_at'] = utc_now();
+                    $db->table('student_class')->insert($studentClassPayload);
+                }
+
+                $db->table('enrollments')
+                    ->where('student_id', $studentId)
+                    ->where('school_year', $year)
+                    ->whereIn('enrollment_status', ['admission under review', 'payment pending', 'enrolled'])
+                    ->update([
+                        'class_section_id' => $targetSectionId,
+                        'assigned_class_section_id' => $targetSectionId,
+                        'placement_status' => $placementStatus,
+                        'updated_at' => utc_now(),
+                    ]);
+            }
+        } catch (\Throwable $e) {
+            log_message('error', 'repairMissingEnrollmentClassAssignments failed: ' . $e->getMessage());
+        }
+    }
+
+    private function baseSectionForClassYear(int $classId, string $schoolYear): ?array
+    {
+        $db = Database::connect();
+        $this->ensureClassSectionsForYear($db, $schoolYear);
+        if ($classId <= 0 || $schoolYear === '' || ! $db->tableExists('classSection')) {
+            return null;
+        }
+
+        $builder = $db->table('classSection')
+            ->select('class_section_id, class_section_name, class_id')
+            ->where('class_id', $classId)
+            ->where("class_section_name NOT LIKE '%-%'", null, false)
+            ->orderBy('id', 'ASC')
+            ->limit(1);
+
+        if ($db->fieldExists('school_year', 'classSection')) {
+            $builder->where('school_year', $schoolYear);
+        }
+
+        $row = $builder->get()->getRowArray();
+
+        return $row !== null && (int)($row['class_section_id'] ?? 0) > 0 ? $row : null;
+    }
+
+    private function ensureClassSectionsForYear($db, string $targetSchoolYear): void
+    {
+        $targetSchoolYear = trim($targetSchoolYear);
+        if ($targetSchoolYear === '' || ! $db->tableExists('classSection') || ! $db->fieldExists('school_year', 'classSection')) {
+            return;
+        }
+
+        if ($db->table('classSection')->where('school_year', $targetSchoolYear)->countAllResults() > 0) {
+            return;
+        }
+
+        $sourceSchoolYear = $this->previousSchoolYearName($targetSchoolYear);
+        if ($sourceSchoolYear === null) {
+            return;
+        }
+
+        $sourceRows = $db->table('classSection')
+            ->select('class_id, class_section_id, class_section_name')
+            ->where('school_year', $sourceSchoolYear)
+            ->orderBy('id', 'ASC')
+            ->get()
+            ->getResultArray();
+
+        $now = utc_now();
+        foreach ($sourceRows as $row) {
+            $classSectionId = (int)($row['class_section_id'] ?? 0);
+            if ($classSectionId <= 0) {
+                continue;
+            }
+
+            $exists = $db->table('classSection')
+                ->where('school_year', $targetSchoolYear)
+                ->where('class_section_id', $classSectionId)
+                ->countAllResults();
+            if ($exists > 0) {
+                continue;
+            }
+
+            $db->table('classSection')->insert([
+                'class_id' => (int)($row['class_id'] ?? 0),
+                'class_section_id' => $classSectionId,
+                'class_section_name' => (string)($row['class_section_name'] ?? ''),
+                'school_year' => $targetSchoolYear,
+                'created_at' => $now,
+                'updated_at' => $now,
+            ]);
+        }
+    }
+
+    private function previousSchoolYearName(string $schoolYear): ?string
+    {
+        $schoolYear = trim($schoolYear);
+        if (! preg_match('/^(\d{4})-(\d{4})$/', $schoolYear, $matches)) {
+            return null;
+        }
+
+        return ((int)$matches[1] - 1) . '-' . ((int)$matches[2] - 1);
+    }
+
 
 
     public function save()
@@ -226,8 +738,46 @@ class AssignmentController extends BaseController
     // API: JSON payload for Classes List page
     public function classAssignmentData()
     {
-        $teacherClassesAll = $this->teacherClassModel->findAll();
-        $studentClassesAll = $this->studentClassModel->findAll();
+        $year = trim((string)($this->request->getGet('schoolYear') ?? $this->request->getGet('school_year') ?? ''));
+        if ($year === '') {
+            $year = $this->currentSchoolYearName((string)($this->schoolYear ?? ''));
+        }
+        $this->applyPendingDistributionDraftsForEnrolledStudents($year);
+        $this->repairMissingEnrollmentClassAssignments($year);
+        $distributedSectionIds = array_values(array_unique(array_merge(
+            $this->distributedClassSectionIds($year),
+            $this->enrollmentAssignedClassSectionIds($year)
+        )));
+
+        $classSectionsAll = [];
+        if (!empty($distributedSectionIds)) {
+            $classSectionsAll = $this->classSectionModel
+                ->select('id, class_section_id, class_section_name, school_year')
+                ->where('school_year', $year)
+                ->whereIn('class_section_id', $distributedSectionIds)
+                ->orderBy('class_section_name', 'ASC')
+                ->findAll();
+        }
+
+        $classSectionById = [];
+        foreach ($classSectionsAll as $section) {
+            $sectionId = (int)($section['class_section_id'] ?? 0);
+            if ($sectionId > 0) {
+                $classSectionById[$sectionId] = $section;
+            }
+        }
+
+        $tcQ = $this->teacherClassModel;
+        if ($year !== '') {
+            $tcQ = $tcQ->where('school_year', $year);
+        }
+        $teacherClassesAll = $tcQ->findAll();
+
+        $scQ = $this->studentClassModel->active();
+        if ($year !== '') {
+            $scQ = $scQ->where('student_class.school_year', $year);
+        }
+        $studentClassesAll = $scQ->findAll();
 
         // Group by section
         $teacherBySection = [];
@@ -241,16 +791,22 @@ class AssignmentController extends BaseController
             if ($secId) $studentsBySection[$secId][] = $sc;
         }
 
-        $allSectionIds = array_values(array_unique(array_merge(array_keys($teacherBySection), array_keys($studentsBySection))));
+        $allSectionIds = array_values(array_unique(array_merge(array_keys($classSectionById), array_keys($teacherBySection), array_keys($studentsBySection))));
+        $distributedSectionSet = array_fill_keys($distributedSectionIds, true);
 
         $classSections = [];
 
         foreach ($allSectionIds as $classSectionId) {
+            if (!isset($distributedSectionSet[(int)$classSectionId])) {
+                continue;
+            }
+
             $hasTeacher  = !empty($teacherBySection[$classSectionId]);
             $hasStudents = !empty($studentsBySection[$classSectionId]);
-            if (!$hasTeacher && !$hasStudents) continue;
+            $hasClassSection = isset($classSectionById[(int)$classSectionId]);
+            if (!$hasClassSection && !$hasTeacher && !$hasStudents) continue;
 
-            $classSectionName = (string) ($this->classSectionModel->getClassSectionNameBySectionId($classSectionId) ?? '');
+            $classSectionName = (string) ($classSectionById[(int)$classSectionId]['class_section_name'] ?? $this->classSectionModel->getClassSectionNameBySectionId($classSectionId) ?? '');
 
             $mainTeachers = [];
             $teacherAssistants = [];
@@ -284,12 +840,18 @@ class AssignmentController extends BaseController
 
             // Load students for the section
             $students = [];
-            foreach ($this->studentClassModel->active()->where('student_class.class_section_id', $classSectionId)->findAll() as $studentClass) {
+            $seenStudentIds = [];
+            foreach ($studentsBySection[$classSectionId] ?? [] as $studentClass) {
+                $sid = (int)($studentClass['student_id'] ?? 0);
+                if ($sid <= 0 || isset($seenStudentIds[$sid])) {
+                    continue;
+                }
                 $stu = $this->studentModel
-                    ->where('id', (int)$studentClass['student_id'])
+                    ->where('id', $sid)
                     ->where('is_active', 1)
                     ->first();
                 if (!$stu) continue;
+
                 $students[] = [
                     'id'                  => (int)$stu['id'],
                     'firstname'           => (string)($stu['firstname'] ?? ''),
@@ -301,6 +863,7 @@ class AssignmentController extends BaseController
                     'tuition_paid'        => (bool)($stu['tuition_paid'] ?? false),
                     'school_id'           => (string)($stu['school_id'] ?? ''),
                 ];
+                $seenStudentIds[$sid] = true;
             }
 
             $classSections[] = [
@@ -316,7 +879,7 @@ class AssignmentController extends BaseController
         }
 
         // Sort by class_section_name
-        usort($classSections, fn($a, $b) => strcmp((string)($a['class_section_name'] ?? ''), (string)($b['class_section_name'] ?? '')));
+        usort($classSections, fn($a, $b) => strnatcasecmp((string)($a['class_section_name'] ?? ''), (string)($b['class_section_name'] ?? '')));
 
         return $this->response->setJSON([
             'classSections' => $classSections,

app/Controllers/View/AttendanceController.php

@@ -63,12 +63,21 @@ class AttendanceController extends Controller
         $this->calendarModel       = model(CalendarModel::class); 
         $this->userRoleModel       = new UserRoleModel();
         $this->semesterScoreService = service('semesterScoreService');
-        $this->semester = $this->configModel->getConfig('semester');
-        $this->schoolYear = $this->configModel->getConfig('school_year');
+        $this->semester = getSemester();
+        $this->schoolYear = $this->currentSchoolYearName();
         $this->enableAttendance = $this->configModel->getConfig('enable_attendance');
         $this->semesterRangeService = new SemesterRangeService($this->configModel);
     }
 
+    private function currentSchoolYearName(): string
+    {
+        try {
+            return service('schoolYearContext')->resolve(service('request'))->yearName();
+        } catch (\Throwable $e) {
+            return (string) ($this->configModel->getConfig('school_year') ?? '');
+        }
+    }
+
 
     /**
      * GET: filter + grid for a single date/section.
@@ -258,9 +267,9 @@ public function showUpdateAttendanceForm()
     $currentSunday = $sundayDates[2];
 
     // Students roster for this section/year/semester (try section code, then PK fallback)
-    $students = $this->studentModel->getByClassAndYear($class_section_id, $schoolYear, $semester);
+    $students = $this->studentModel->getActiveByClassAndYear($class_section_id, $schoolYear, $semester);
     if (empty($students) && $classSectionPk > 0 && $classSectionPk !== $class_section_id) {
-        $students = $this->studentModel->getByClassAndYear($classSectionPk, $schoolYear, $semester);
+        $students = $this->studentModel->getActiveByClassAndYear($classSectionPk, $schoolYear, $semester);
     }
 
     // Build student attendance rows
@@ -525,19 +534,19 @@ public function showUpdateAttendanceForm()
         // If there are no assignments yet for the requested semester (e.g., Spring roster not populated),
         // fall back to the school year only so the roster still renders and can be used for the new term.
         $classSections = $this->classSectionModel
-            ->select('classSection.id, classSection.class_id, classSection.class_section_id, classSection.class_section_name')
+            ->select('MIN(classSection.id) AS id, classSection.class_id, classSection.class_section_id, classSection.class_section_name', false)
             ->join('student_class sc', 'sc.class_section_id = classSection.class_section_id', 'inner')
             ->where('sc.school_year', $termYear)
-            ->groupBy(['classSection.id', 'classSection.class_id', 'classSection.class_section_id', 'classSection.class_section_name'])
+            ->groupBy(['classSection.class_id', 'classSection.class_section_id', 'classSection.class_section_name'])
             ->findAll();
 
         $useRosterFallback = false;
         if (empty($classSections) && $termYear !== '') {
             $classSections = $this->classSectionModel
-                ->select('classSection.id, classSection.class_id, classSection.class_section_id, classSection.class_section_name')
+                ->select('MIN(classSection.id) AS id, classSection.class_id, classSection.class_section_id, classSection.class_section_name', false)
                 ->join('student_class sc', 'sc.class_section_id = classSection.class_section_id', 'inner')
                 ->where('sc.school_year', $termYear)
-                ->groupBy(['classSection.id', 'classSection.class_id', 'classSection.class_section_id', 'classSection.class_section_name'])
+                ->groupBy(['classSection.class_id', 'classSection.class_section_id', 'classSection.class_section_name'])
                 ->findAll();
             $useRosterFallback = !empty($classSections);
         }
@@ -579,15 +588,22 @@ public function showUpdateAttendanceForm()
             }
 
             $hasRoster = false;
+            $seenStudentIds = [];
 
             foreach ($students as $sc) {
                 $studentId = (int)$sc['student_id'];
+                if ($studentId <= 0 || isset($seenStudentIds[$studentId])) {
+                    continue;
+                }
+                $seenStudentIds[$studentId] = true;
+
                 $student   = $this->studentModel
-                    ->select('id, firstname, lastname, school_id')
+                    ->select('id, firstname, lastname, school_id, is_active')
                     ->where('id', $studentId)
-                    ->where('is_active', 1)
                     ->first();
                 if (!$student) continue;
+                $student['enrollment_status'] = $sc['enrollment_status'] ?? '';
+                $student['is_withdrawn'] = (int)($sc['is_withdrawn'] ?? 0);
 
                 $studentsBySection[$secCode][] = $student;
                 $hasRoster = true;
@@ -1012,9 +1028,11 @@ public function showUpdateAttendanceForm()
                     continue;
                 }
                 $student   = $this->studentModel
-                    ->select('id, firstname, lastname, school_id')
+                    ->select('id, firstname, lastname, school_id, is_active')
                     ->find($studentId);
                 if (!$student) continue;
+                $student['enrollment_status'] = $sc['enrollment_status'] ?? '';
+                $student['is_withdrawn'] = (int)($sc['is_withdrawn'] ?? 0);
 
                 $studentsBySection[$secCode][] = $student;
                 $hasRoster = true;
@@ -1588,7 +1606,7 @@ public function showUpdateAttendanceForm()
 
             // optional score updates (never bubble)
             try {
-                $studentUserInfo = $this->studentModel->getStudentInfoByClassSectionId(
+                $studentUserInfo = $this->studentModel->getActiveStudentInfoByClassSectionId(
                     $classSectionId,
                     $semester,
                     $schoolYear
@@ -1707,6 +1725,19 @@ public function showUpdateAttendanceForm()
         $semester   = (string)($this->semester   ?? '');
         $schoolYear = (string)($this->schoolYear ?? '');
 
+        $activeStudents = $this->studentModel->getActiveByClassAndYear($classSectionId, $schoolYear, $semester);
+        $activeStudentIds = array_fill_keys(array_map(static fn(array $row): int => (int)($row['id'] ?? 0), $activeStudents), true);
+        $attendanceData = array_values(array_filter($attendanceData, static function ($row) use ($activeStudentIds): bool {
+            $sid = (int)($row['student_id'] ?? 0);
+            return $sid > 0 && isset($activeStudentIds[$sid]);
+        }));
+
+        if (empty($attendanceData)) {
+            return redirect()->to('/teacher/showupdate_attendance?class_section_id=' . $classSectionId)
+                ->with('status', 'error')
+                ->with('message', 'No active student attendance data provided.');
+        }
+
         // Existing attendance rows for today (used to lock parent/admin submissions)
         $existingRows = $this->attendanceDataModel
             ->where('class_section_id', $classSectionId)
@@ -2012,7 +2043,7 @@ public function showUpdateAttendanceForm()
             }
 
             try {
-                $studentUserInfo = $this->studentModel->getStudentInfoByClassSectionId($classSectionId, $this->semester, $this->schoolYear);
+                $studentUserInfo = $this->studentModel->getActiveStudentInfoByClassSectionId($classSectionId, $this->semester, $this->schoolYear);
                 $this->semesterScoreService->updateScoresForStudents($studentUserInfo);
             } catch (\Throwable $e) {
                 // ignore

app/Controllers/View/AttendanceTrackingController.php

@@ -40,7 +40,7 @@ class AttendanceTrackingController extends BaseController
         $this->db                      = \Config\Database::connect();
         $this->notificationModel       = new ParentNotificationModel();
         $this->attendanceEmailTemplateModel = new AttendanceEmailTemplateModel();
-        $this->semester   = (string) $this->configModel->getConfig('semester');
+        $this->semester   = (string) getSemester();
         $this->schoolYear = (string) $this->configModel->getConfig('school_year');
     }
 
@@ -49,7 +49,8 @@ class AttendanceTrackingController extends BaseController
         $syParam = $this->request->getGet('school_year');
         $semParam = $this->request->getGet('semester');
         $schoolYear = (is_string($syParam) && $syParam !== '') ? (string)$syParam : (string)$this->schoolYear;
-        $semester   = (is_string($semParam) && $semParam !== '') ? (string)$semParam : null; // semester filter disabled
+        $semester   = (is_string($semParam) && $semParam !== '') ? (string)$semParam : (string)$this->semester;
+        $semesterWasRequested = is_string($semParam) && $semParam !== '';
 
         $debugInfo = [
             'school_year_param' => $schoolYear,
@@ -70,28 +71,6 @@ class AttendanceTrackingController extends BaseController
             ->findAll();
         $debugInfo['class_students'] = count($classStudents);
 
-        // Fallback: if the configured school_year has no class assignments, look up the latest term
-        if (empty($classStudents)) {
-            $latestTerm = $this->db->table('student_class')
-                ->select('school_year, semester')
-                ->orderBy('id', 'DESC')
-                ->limit(1)
-                ->get()
-                ->getRowArray();
-
-            if ($latestTerm && !empty($latestTerm['school_year'])) {
-                $schoolYear = (string)$latestTerm['school_year'];
-                if (!empty($latestTerm['semester'])) {
-                    $semester = (string)$latestTerm['semester'];
-                }
-
-                $classStudents = $this->studentClassModel
-                    ->active()
-                    ->where('student_class.school_year', $schoolYear)
-                    ->findAll();
-            }
-        }
-
         // Gather candidate student identifiers (numeric IDs and code-like IDs)
         $studentIds = [];
         $studentCodes = [];
@@ -347,7 +326,8 @@ class AttendanceTrackingController extends BaseController
                 'semester'    => $semester,
                 'student_ids' => $studentIds,
             ]);
-            // Second chance: detect the latest attendance_data term for these students
+            // Second chance: detect the latest attendance_data term only when the user has not
+            // requested a semester and the date-based current semester is unavailable.
             $latestAttendanceTerm = $this->db->table('attendance_data')
                 ->select('school_year, semester, date')
                 ->whereIn('student_id', $studentIds)
@@ -356,7 +336,7 @@ class AttendanceTrackingController extends BaseController
                 ->get()
                 ->getRowArray();
 
-            if ($latestAttendanceTerm) {
+            if ($latestAttendanceTerm && !$semesterWasRequested && trim($semester) === '') {
                 $schoolYear = !empty($latestAttendanceTerm['school_year'])
                     ? (string)$latestAttendanceTerm['school_year']
                     : $schoolYear;
@@ -2003,6 +1983,58 @@ class AttendanceTrackingController extends BaseController
         return [$subject, $body];
     }
 
+    private function buildFallbackTemplate(string $code, string $variant, array $context): array
+    {
+        $studentName = (string) ($context['{{student_name}}'] ?? 'the student');
+        $incident    = (string) ($context['{{incident_date}}'] ?? date('Y-m-d'));
+        $parentName  = (string) ($context['{{parent_name}}'] ?? 'Parent/Guardian');
+        $phone       = (string) ($context['{{school_phone}}'] ?? 'the school office');
+        $voicemail   = (string) ($context['{{voicemail_phone}}'] ?? 'your voicemail');
+
+        $subject = match (true) {
+            str_starts_with($code, 'ABS_1')  => 'Attendance Notice: Unreported Absence',
+            str_starts_with($code, 'ABS_2')  => 'Attendance Follow-Up: Two Consecutive Absences',
+            str_starts_with($code, 'ABS_3')  => 'Attendance Follow-Up: Three Absences',
+            str_starts_with($code, 'LATE_2') => 'Attendance Notice: Repeated Lateness',
+            str_starts_with($code, 'LATE_3'),
+            str_starts_with($code, 'LATE_4'),
+            str_starts_with($code, 'MIX')    => 'Attendance Follow-Up: Repeated Lateness and Absence',
+            default                          => 'Attendance Notice',
+        };
+
+        $intro = "<p>Insha Allah this email finds you well";
+        if ($variant === 'answered') {
+            $intro .= ", <strong>{$parentName}</strong>. Jazakum Allahu khayran for taking the time to speak with us today.</p>";
+        } elseif ($variant === 'no_answer') {
+            $intro .= ".</p><p>We tried to reach you but could not connect and left a voice message at <strong>{$voicemail}</strong>.</p>";
+        } else {
+            $intro .= ".</p>";
+        }
+
+        $details = match (true) {
+            str_starts_with($code, 'ABS_1')
+                => "<p>This is to let you know that <strong>{$studentName}</strong> was absent on <strong>{$incident}</strong> without prior notice.</p>",
+            str_starts_with($code, 'ABS_2')
+                => "<p>This is a reminder that <strong>{$studentName}</strong> has had repeated absences, most recently on <strong>{$incident}</strong>, without prior notice.</p>",
+            str_starts_with($code, 'ABS_3')
+                => "<p>This is a reminder that <strong>{$studentName}</strong> has been absent three times, most recently on <strong>{$incident}</strong>, without prior notice.</p>",
+            str_starts_with($code, 'LATE_2')
+                => "<p>This is a reminder that <strong>{$studentName}</strong> has been late multiple times, most recently on <strong>{$incident}</strong>.</p>",
+            str_starts_with($code, 'LATE_3'),
+            str_starts_with($code, 'LATE_4')
+                => "<p>This is a follow-up that <strong>{$studentName}</strong> has had repeated lateness concerns, most recently on <strong>{$incident}</strong>.</p>",
+            str_starts_with($code, 'MIX')
+                => "<p>This is a follow-up that <strong>{$studentName}</strong> has had a mix of repeated lateness and absence concerns, most recently on <strong>{$incident}</strong>.</p>",
+            default
+                => "<p>We'd like to inform you about <strong>{$studentName}</strong>'s recent attendance concern dated <strong>{$incident}</strong>.</p>",
+        };
+
+        $closing = "<p>If your child will be absent or late due to illness or family commitments, please let us know ahead of time.</p>"
+            . "<p>You can email/call/text us at <strong>{$phone}</strong>.</p>";
+
+        return [$subject, $intro . $details . $closing];
+    }
+
 
     public function compose()
     {
@@ -2033,8 +2065,8 @@ class AttendanceTrackingController extends BaseController
         $rendered = $this->renderTemplate($code, $variant, $ctx);
 
         if (!$rendered) {
-            return redirect()->to(site_url('attendance/violations'))
-                ->with('error', 'Template not found for ' . $code . ' (' . $variant . ').');
+            log_message('warning', 'Attendance email template missing; using fallback compose body. code=' . $code . ' variant=' . $variant);
+            $rendered = $this->buildFallbackTemplate($code, $variant, $ctx);
         }
 
         [$subject, $body] = $rendered;
@@ -2110,7 +2142,7 @@ class AttendanceTrackingController extends BaseController
     $wrapped = $this->renderWithEmailLayout($subject, $safeHtmlBody);
 
     // Resolve term (prefer controller properties if set)
-    $semester   = $this->semester   ?? (new \App\Models\ConfigurationModel())->getConfig('semester');
+    $semester   = $this->semester   ?? getSemester();
     $schoolYear = $this->schoolYear ?? (new \App\Models\ConfigurationModel())->getConfig('school_year');
 
     try {

app/Controllers/View/AuthorizedUsersController.php

@@ -15,7 +15,7 @@ class AuthorizedUsersController extends ResourceController
     protected $userModel;
     protected $authorizedUserModel;
 
-    public function __construct(private \CodeIgniter\HTTP\IncomingRequest $request)
+    public function __construct()
     {
         $this->userModel = new UserModel();
         $this->authorizedUserModel = new AuthorizedUserModel();

app/Controllers/View/CertificateController.php

@@ -0,0 +1,673 @@
+<?php
+
+namespace App\Controllers\View;
+
+use App\Controllers\BaseController;
+use App\Models\ClassSectionModel;
+use App\Models\ConfigurationModel;
+use App\Models\CertificateRecordModel;
+
+class CertificateController extends BaseController
+{
+    protected $classSectionModel;
+    protected $configModel;
+    protected $certRecordModel;
+    protected $schoolYear;
+
+    public function __construct()
+    {
+        $this->classSectionModel = new ClassSectionModel();
+        $this->configModel       = new ConfigurationModel();
+        $this->certRecordModel   = new CertificateRecordModel();
+        $this->schoolYear        = $this->configModel->getConfig('school_year');
+    }
+
+    // ─── Admin UI ──────────────────────────────────────────────────────────────
+
+    public function index()
+    {
+        $db           = \Config\Database::connect();
+        $selectedCsid = $this->request->getGet('class_section_id');
+        $schoolYear   = $this->request->getGet('school_year') ?? $this->schoolYear;
+
+        // ── All enrolled students across every class section ───────────────────
+        $allEnrolled = $db->table('student_class sc')
+            ->select('s.id AS student_id, s.firstname, s.lastname, sc.class_section_id, cs.class_section_name')
+            ->join('students s', 's.id = sc.student_id')
+            ->join('classSection cs', 'cs.class_section_id = sc.class_section_id')
+            ->where('s.is_active', 1)
+            ->where('sc.school_year', $schoolYear)
+            ->groupBy('s.id, s.firstname, s.lastname, sc.class_section_id, cs.class_section_name')
+            ->orderBy('s.firstname', 'ASC')
+            ->orderBy('s.lastname', 'ASC')
+            ->get()
+            ->getResultArray();
+
+        $allIds = array_values(array_unique(array_map('intval', array_column($allEnrolled, 'student_id'))));
+
+        // ── Saved generated YEAR decisions from student_decisions ──────────────
+        //
+        // Source of truth:
+        // student_decisions.year_score
+        // student_decisions.decision
+        //
+        // Do NOT recalculate certificate decisions here from semester_scores.
+        $decisionsByStudent = [];
+
+        if (!empty($allIds)) {
+            $decisionRows = $db->table('student_decisions')
+                ->whereIn('student_id', $allIds)
+                ->where('school_year', $schoolYear)
+                ->get()
+                ->getResultArray();
+
+            foreach ($decisionRows as $d) {
+                $sid = (int)($d['student_id'] ?? 0);
+
+                if ($sid <= 0) {
+                    continue;
+                }
+
+                $decision = trim((string)($d['decision'] ?? ''));
+                $source   = trim((string)($d['source'] ?? ''));
+
+                if ($source === '') {
+                    $source = $decision === '' ? 'pending' : 'manual';
+                }
+
+                $decisionsByStudent[$sid]['Year'] = [
+                    'decision'   => $decision,
+                    'source'     => $source,
+                    'notes'      => (string)($d['notes'] ?? ''),
+                    'year_score' => $d['year_score'] ?? null,
+                ];
+            }
+        }
+
+        // ── Certificate records: most recent per student ───────────────────────
+        $certsByStudent = [];
+
+        if (!empty($allIds)) {
+            foreach ($db->table('certificate_records')
+                ->select('student_id, certificate_number, issued_at')
+                ->whereIn('student_id', $allIds)
+                ->where('school_year', $schoolYear)
+                ->orderBy('issued_at', 'DESC')
+                ->get()
+                ->getResultArray() as $c) {
+                $sid = (int)$c['student_id'];
+
+                if (!isset($certsByStudent[$sid])) {
+                    $certsByStudent[$sid] = $c['certificate_number'];
+                }
+            }
+        }
+
+        // ── Build per-class buckets and stats ──────────────────────────────────
+        $studentsByClass = [];
+        $statsPerClass   = [];
+        $seenEnrollments = [];
+
+        foreach ($allEnrolled as $row) {
+            $sid  = (int)$row['student_id'];
+            $csid = (int)$row['class_section_id'];
+            $enrollmentKey = $csid . ':' . $sid;
+
+            if (isset($seenEnrollments[$enrollmentKey])) {
+                continue;
+            }
+
+            $seenEnrollments[$enrollmentKey] = true;
+
+            if (!isset($statsPerClass[$csid])) {
+                $statsPerClass[$csid] = [
+                    'name'  => $row['class_section_name'],
+                    'total' => 0,
+                    'pass'  => 0,
+                    'cert'  => 0,
+                ];
+            }
+
+            $statsPerClass[$csid]['total']++;
+
+            // If no generated decision exists yet, explicitly mark pending.
+            if (!isset($decisionsByStudent[$sid])) {
+                $decisionsByStudent[$sid]['Decision'] = [
+                    'decision'   => '',
+                    'source'     => 'pending',
+                    'notes'      => '',
+                    'year_score' => null,
+                ];
+            }
+
+            // Certificate eligibility:
+            // A student is eligible only if the saved final generated decision is Pass.
+            $studentDecisions = $decisionsByStudent[$sid] ?? [];
+            $isPass           = !empty($studentDecisions);
+
+            foreach ($studentDecisions as $decisionRow) {
+                $decision = trim((string)($decisionRow['decision'] ?? ''));
+
+                if (strcasecmp($decision, 'Pass') !== 0) {
+                    $isPass = false;
+                    break;
+                }
+            }
+
+            if ($isPass) {
+                $statsPerClass[$csid]['pass']++;
+            }
+
+            if (isset($certsByStudent[$sid])) {
+                $statsPerClass[$csid]['cert']++;
+            }
+
+            $studentsByClass[$csid][] = $row;
+        }
+
+        // ── Determine default active tab ───────────────────────────────────────
+        $firstCsid = !empty($allEnrolled) ? (int)$allEnrolled[0]['class_section_id'] : null;
+
+        if ($selectedCsid === null && $firstCsid !== null) {
+            $selectedCsid = (string)$firstCsid;
+        }
+
+        return view('admin/certificates/index', [
+            'studentsByClass'    => $studentsByClass,
+            'selectedClassId'    => $selectedCsid,
+            'schoolYear'         => $schoolYear,
+            'certDate'           => date('m/d/Y'),
+            'decisionsByStudent' => $decisionsByStudent,
+            'certsByStudent'     => $certsByStudent,
+            'statsPerClass'      => $statsPerClass,
+        ]);
+    }
+
+    public function auditLog()
+    {
+        $schoolYear  = $this->request->getGet('school_year') ?? $this->schoolYear;
+        $records     = $this->certRecordModel->getAuditLog($schoolYear);
+        $yearSummary = $this->certRecordModel->yearSummary();
+
+        return view('admin/certificates/audit_log', [
+            'records'     => $records,
+            'schoolYear'  => $schoolYear,
+            'yearSummary' => $yearSummary,
+        ]);
+    }
+
+    public function csrfToken()
+    {
+        return $this->response
+            ->setHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0')
+            ->setHeader('Pragma', 'no-cache')
+            ->setJSON([
+                'csrf_token' => csrf_token(),
+                'csrf_hash'  => csrf_hash(),
+            ]);
+    }
+
+    // ─── Public verification page ──────────────────────────────────────────────
+
+    public function verify(string $certNumber)
+    {
+        $record = \Config\Database::connect()
+            ->table('certificate_records cr')
+            ->select('cr.*, u.firstname AS admin_firstname, u.lastname AS admin_lastname')
+            ->join('users u', 'u.id = cr.issued_by', 'left')
+            ->groupStart()
+                ->where('cr.verification_token', $certNumber)
+                ->orWhere('cr.certificate_number', strtoupper($certNumber))
+            ->groupEnd()
+            ->get()
+            ->getRowArray();
+
+        return view('certificates/verify', [
+            'record' => $record ?: null,
+        ]);
+    }
+
+    // ─── Reprint an existing certificate ──────────────────────────────────────
+
+    public function reprint(string $certNumber)
+    {
+        $record = \Config\Database::connect()
+            ->table('certificate_records')
+            ->where('certificate_number', strtoupper($certNumber))
+            ->get()
+            ->getRowArray();
+
+        if (!$record) {
+            return redirect()->to('administrator/certificates/log')
+                ->with('error', 'Certificate not found: ' . $certNumber);
+        }
+
+        $certDateFormatted = '';
+
+        if (!empty($record['cert_date'])) {
+            $ts = strtotime((string)$record['cert_date']);
+
+            if ($ts) {
+                $certDateFormatted = date('m/d/Y', $ts);
+            }
+        }
+
+        $student = [
+            'firstname'    => (string)($record['student_name'] ?? ''),
+            'lastname'     => '',
+            'grade'        => (string)($record['grade'] ?? ''),
+            'cert_number'  => (string)($record['certificate_number'] ?? ''),
+            'verify_token' => $this->ensureVerificationTokenForRecord($record),
+        ];
+
+        // student_name is stored as "Firstname Lastname" — split for the PDF builder.
+        $parts = explode(' ', trim($student['firstname']), 2);
+
+        if (count($parts) === 2) {
+            $student['firstname'] = $parts[0];
+            $student['lastname']  = $parts[1];
+        }
+
+        $pdfData  = $this->buildPdf([$student], $certDateFormatted ?: date('m/d/Y'));
+        $filename = 'Certificate_' . strtoupper($certNumber) . '.pdf';
+
+        return $this->response
+            ->setHeader('Content-Type', 'application/pdf')
+            ->setHeader('Content-Disposition', 'inline; filename="' . $filename . '"')
+            ->setBody($pdfData);
+    }
+
+    // ─── PDF generation ────────────────────────────────────────────────────────
+
+    public function generate()
+    {
+        $studentIds     = $this->request->getPost('student_ids') ?? [];
+        $certDate       = trim($this->request->getPost('cert_date') ?? date('m/d/Y'));
+        $classSectionId = $this->request->getPost('class_section_id');
+        $schoolYear     = $this->request->getPost('school_year') ?? $this->schoolYear;
+
+        if (empty($studentIds)) {
+            if ($this->request->isAJAX()) {
+                return $this->response
+                    ->setStatusCode(422)
+                    ->setJSON([
+                        'ok'         => false,
+                        'error'      => 'Please select at least one student.',
+                        'csrf_token' => csrf_token(),
+                        'csrf_hash'  => csrf_hash(),
+                    ]);
+            }
+
+            return redirect()->to('administrator/certificates')
+                ->with('error', 'Please select at least one student.');
+        }
+
+        $studentIds = array_values(array_unique(array_filter(array_map('intval', $studentIds))));
+        $certDate   = preg_replace('/[^0-9\/\-]/', '', $certDate);
+
+        if (empty($studentIds)) {
+            if ($this->request->isAJAX()) {
+                return $this->response
+                    ->setStatusCode(422)
+                    ->setJSON([
+                        'ok'         => false,
+                        'error'      => 'Invalid student selection.',
+                        'csrf_token' => csrf_token(),
+                        'csrf_hash'  => csrf_hash(),
+                    ]);
+            }
+
+            return redirect()->to('administrator/certificates')
+                ->with('error', 'Invalid student selection.');
+        }
+
+        $db       = \Config\Database::connect();
+        $students = [];
+
+        foreach ($studentIds as $id) {
+            $row = null;
+
+            if ($classSectionId) {
+                $row = $db->table('student_class sc')
+                    ->select('s.id, s.firstname, s.lastname, cs.class_section_name AS grade')
+                    ->join('students s', 's.id = sc.student_id')
+                    ->join('classSection cs', 'cs.class_section_id = sc.class_section_id')
+                    ->where('sc.class_section_id', (int)$classSectionId)
+                    ->where('sc.school_year', $schoolYear)
+                    ->where('s.id', $id)
+                    ->get()
+                    ->getRowArray();
+            }
+
+            if (!$row) {
+                $s = $db->table('students')
+                    ->select('id, firstname, lastname, registration_grade AS grade')
+                    ->where('id', $id)
+                    ->get()
+                    ->getRowArray();
+
+                $row = $s ?: null;
+            }
+
+            if ($row) {
+                $students[] = $row;
+            }
+        }
+
+        if (empty($students)) {
+            if ($this->request->isAJAX()) {
+                return $this->response
+                    ->setStatusCode(422)
+                    ->setJSON([
+                        'ok'         => false,
+                        'error'      => 'No valid students found.',
+                        'csrf_token' => csrf_token(),
+                        'csrf_hash'  => csrf_hash(),
+                    ]);
+            }
+
+            return redirect()->to('administrator/certificates')
+                ->with('error', 'No valid students found.');
+        }
+
+        $issuedAt = date('Y-m-d H:i:s');
+
+        // Load existing certificates for these students this school year.
+        $existingCerts = $db->table('certificate_records')
+            ->select('id, student_id, certificate_number, verification_token')
+            ->whereIn('student_id', array_column($students, 'id'))
+            ->where('school_year', $schoolYear)
+            ->get()
+            ->getResultArray();
+
+        $existingCertMap = [];
+
+        foreach ($existingCerts as $ec) {
+            $existingCertMap[(int)$ec['student_id']] = $ec;
+        }
+
+        foreach ($students as &$student) {
+            $sid = (int)$student['id'];
+
+            if (isset($existingCertMap[$sid])) {
+                // Reuse existing certificate number — do not create a new record.
+                $existing = $existingCertMap[$sid];
+
+                $student['cert_number']  = (string)($existing['certificate_number'] ?? '');
+                $student['verify_token'] = $this->ensureVerificationTokenForRecord($existing);
+            } else {
+                $certNumber  = $this->certRecordModel->nextNumber($schoolYear);
+                $verifyToken = $this->certRecordModel->generateVerificationToken();
+
+                $this->certRecordModel->insert([
+                    'certificate_number' => $certNumber,
+                    'verification_token' => $verifyToken,
+                    'student_id'         => $sid,
+                    'student_name'       => $student['firstname'] . ' ' . $student['lastname'],
+                    'grade'              => $this->formatGrade($student['grade'] ?? ''),
+                    'school_year'        => $schoolYear,
+                    'class_section_id'   => $classSectionId ?: null,
+                    'issued_at'          => $issuedAt,
+                ]);
+
+                $student['cert_number']  = $certNumber;
+                $student['verify_token'] = $verifyToken;
+            }
+        }
+
+        unset($student);
+
+        $pdfData  = $this->buildPdf($students, $certDate);
+        $filename = 'Certificates_' . date('Ymd_His') . '.pdf';
+
+        return $this->response
+            ->setHeader('Content-Type', 'application/pdf')
+            ->setHeader('Content-Disposition', 'inline; filename="' . $filename . '"')
+            ->setHeader('X-CSRF-TOKEN-NAME', csrf_token())
+            ->setHeader('X-CSRF-TOKEN', csrf_hash())
+            ->setBody($pdfData);
+    }
+
+    // ─── Helpers ───────────────────────────────────────────────────────────────
+
+    private function parseCertDate(string $certDate): ?string
+    {
+        if (preg_match('#^(\d{2})/(\d{2})/(\d{4})$#', $certDate, $m)) {
+            return $m[3] . '-' . $m[1] . '-' . $m[2];
+        }
+
+        if (preg_match('#^\d{4}-\d{2}-\d{2}$#', $certDate)) {
+            return $certDate;
+        }
+
+        return null;
+    }
+
+    private function formatGrade(string $raw): string
+    {
+        $clean = trim($raw);
+        $lower = strtolower($clean);
+
+        // Strip section suffix: "Grade 1-A" → "Grade 1", "Grade 2-B" → "Grade 2".
+        if (preg_match('/^grade\s*(\d+)/i', $clean, $m)) {
+            return 'Grade ' . (int)$m[1];
+        }
+
+        if ($lower === 'youth') {
+            return 'Youth';
+        }
+
+        if ($lower === 'kg' || $lower === 'kindergarten') {
+            return 'Kindergarten';
+        }
+
+        // Raw number or number-section: "1", "1-A", "2-B" → keep number only.
+        if (preg_match('/^(\d+)([- ][A-Za-z0-9]+)?$/', $clean, $m)) {
+            return 'Grade ' . (int)$m[1];
+        }
+
+        return $clean;
+    }
+
+    private function ensureVerificationTokenForRecord(array $record): string
+    {
+        $token = trim((string)($record['verification_token'] ?? ''));
+
+        if ($token !== '') {
+            return $token;
+        }
+
+        $recordId = (int)($record['id'] ?? 0);
+
+        if ($recordId <= 0) {
+            return '';
+        }
+
+        $token = $this->certRecordModel->generateVerificationToken();
+
+        $this->certRecordModel->update($recordId, [
+            'verification_token' => $token,
+        ]);
+
+        return $token;
+    }
+
+    // ─── PDF rendering ─────────────────────────────────────────────────────────
+
+    private function buildPdf(array $students, string $certDate): string
+    {
+        $fontDir = FCPATH . 'assets' . DIRECTORY_SEPARATOR . 'certificates' . DIRECTORY_SEPARATOR . 'fonts' . DIRECTORY_SEPARATOR;
+        $imgDir  = FCPATH . 'assets' . DIRECTORY_SEPARATOR . 'certificates' . DIRECTORY_SEPARATOR . 'images' . DIRECTORY_SEPARATOR;
+
+        $edwardianFont = \TCPDF_FONTS::addTTFfont($fontDir . 'Edwardian Script ITC Regular.ttf', 'TrueTypeUnicode', '', 32);
+        $garamondBold  = \TCPDF_FONTS::addTTFfont($fontDir . 'Garamond Bold.ttf', 'TrueTypeUnicode', '', 32);
+        $ebGaramond    = \TCPDF_FONTS::addTTFfont($fontDir . 'EBGaramond-Regular.ttf', 'TrueTypeUnicode', '', 32);
+
+        $pdf = new \TCPDF('L', 'pt', 'A4', true, 'UTF-8', false);
+
+        $pdf->SetCreator('Al Rahma Sunday School');
+        $pdf->SetTitle('Student Certificates');
+        $pdf->SetMargins(0, 0, 0, true);
+        $pdf->SetAutoPageBreak(false, 0);
+        $pdf->setPrintHeader(false);
+        $pdf->setPrintFooter(false);
+        $pdf->SetHeaderMargin(0);
+        $pdf->SetFooterMargin(0);
+
+        $W = $pdf->getPageWidth();
+        $H = $pdf->getPageHeight();
+
+        foreach ($students as $student) {
+            $pdf->AddPage();
+
+            $name        = trim((string)($student['firstname'] ?? '') . ' ' . (string)($student['lastname'] ?? ''));
+            $grade       = $this->formatGrade($student['grade'] ?? '');
+            $certNumber  = $student['cert_number'] ?? '';
+            $verifyToken = $student['verify_token'] ?? '';
+
+            $verifyUrl = $verifyToken !== ''
+                ? site_url('verify/' . rawurlencode($verifyToken))
+                : null;
+
+            $this->drawCertificate(
+                $pdf,
+                $W,
+                $H,
+                $name,
+                $grade,
+                $certDate,
+                $certNumber,
+                $verifyUrl,
+                $imgDir,
+                $edwardianFont,
+                $garamondBold,
+                $ebGaramond
+            );
+        }
+
+        return $pdf->Output('', 'S');
+    }
+
+    /**
+     * Coordinate mapping: iTextSharp origin bottom-left → TCPDF origin top-left.
+     * y_tcpdf ≈ H − y_iTextSharp
+     */
+    private function drawCertificate(
+        \TCPDF $pdf,
+        float $W,
+        float $H,
+        string $name,
+        string $grade,
+        string $certDate,
+        string $certNumber,
+        ?string $verifyUrl,
+        string $imgDir,
+        string $edwardianFont,
+        string $garamondBold,
+        string $ebGaramond
+    ): void {
+        // ── Images
+        $pdf->Image($imgDir . 'title.png', 126, 0, 600);
+        $pdf->Image($imgDir . 'background.png', 280, 176, 291, 340);
+        $pdf->Image($imgDir . 'signature.png', 140, 410, 90, 80);
+
+        // ── "Presented to:"
+        $pdf->SetFont('times', 'B', 24);
+        $pdf->SetTextColor(0, 0, 0);
+        $pdf->SetXY(0, 151);
+        $pdf->Cell($W, 24, 'Presented to:', 0, 0, 'C');
+
+        // ── QR code — left-aligned with "Presented to:", vertically centred on that line.
+        $qrSize = 42;
+
+        if (!empty($verifyUrl)) {
+            $qrX = 120;
+            $qrY = 171 + (24 - $qrSize) / 2;
+
+            $style = [
+                'border'  => false,
+                'padding' => 0,
+                'fgcolor' => [0, 0, 0],
+                'bgcolor' => false,
+            ];
+
+            $pdf->write2DBarcode($verifyUrl, 'QRCODE,L', $qrX, $qrY, $qrSize, $qrSize, $style, 'N');
+        }
+
+        // ── Student name — center based on actual string width.
+        $pdf->SetFont($edwardianFont, '', 38);
+        $nameX = ($W - $pdf->GetStringWidth($name)) / 2;
+        $this->drawGradientText($pdf, $edwardianFont, 38, $name, $nameX, 221.5);
+
+        // ── Line under name
+        $pdf->SetFont('times', '', 20);
+        $pdf->SetXY(0, 236);
+        $pdf->Cell(600, 20, '___________________________________', 0, 0, 'R');
+
+        // ── Description
+        $pdf->SetFont($ebGaramond, '', 20);
+        $pdf->SetXY(0, 273);
+        $pdf->Cell($W, 20, 'for successfully completing the requirements of', 0, 0, 'C');
+
+        // ── Grade
+        $pdf->SetFont($garamondBold, '', 20);
+        $pdf->SetXY(0, 310);
+        $pdf->Cell($W, 20, $grade, 0, 0, 'C');
+
+        // ── "at"
+        $pdf->SetFont('times', '', 20);
+        $pdf->SetXY(0, 343);
+        $pdf->Cell($W, 20, 'at', 0, 0, 'C');
+
+        // ── School name
+        $pdf->SetFont($garamondBold, '', 20);
+        $pdf->SetXY(0, 375);
+        $pdf->Cell($W, 20, 'Al Rahma Sunday School', 0, 0, 'C');
+
+        // ── Date
+        $this->drawGradientText($pdf, $edwardianFont, 26, $certDate, 586, 456);
+
+        // ── Date underline + label
+        $pdf->SetFont('times', '', 20);
+        $pdf->SetXY(0, 463);
+        $pdf->Cell(742, 20, '_________________', 0, 0, 'R');
+        $pdf->SetXY(650, 492);
+        $pdf->Cell(80, 20, 'Date', 0, 0, 'C');
+
+        // ── Signature underline + label
+        $pdf->SetXY(106, 463);
+        $pdf->Cell(200, 20, '_________________', 0, 0, 'L');
+        $pdf->SetXY(106, 492);
+        $pdf->Cell(168, 20, 'Signature', 0, 0, 'C');
+
+        // ── Certificate number — 1.4 cm from bottom, 2.5 cm from left.
+        if ($certNumber !== '') {
+            $pdf->SetFont('helvetica', '', 8);
+            $pdf->SetTextColor(150, 150, 150);
+            $pdf->SetXY(70.86, $H - 39.68);
+            $pdf->Cell(200, 12, 'Certificate No. ' . $certNumber, 0, 0, 'L');
+            $pdf->SetTextColor(0, 0, 0);
+        }
+    }
+
+    private function drawGradientText(
+        \TCPDF $pdf,
+        string $fontName,
+        float $fontSize,
+        string $text,
+        float $x,
+        float $y
+    ): void {
+        $pdf->SetFont($fontName, '', $fontSize);
+
+        for ($i = 0; $i < 6; $i++) {
+            $pdf->setAlpha(($i + 1) * 25 / 255);
+            $pdf->SetTextColor(0, 0, 0);
+            $pdf->Text($x + $i / 4, $y + $i / 4, $text);
+        }
+
+        $pdf->setAlpha(1);
+        $pdf->SetTextColor(0, 0, 0);
+        $pdf->Text($x, $y, $text);
+    }
+}

app/Controllers/View/ClassController.php

@@ -18,7 +18,7 @@ class ClassController extends BaseController
 
     protected $db;
 
-    public function __construct(private \CodeIgniter\HTTP\IncomingRequest $request)
+    public function __construct()
     {
         $this->db = \Config\Database::connect();
         $this->classsectionModel = new ClassSectionModel();
@@ -29,7 +29,7 @@ class ClassController extends BaseController
         $this->configModel = new ConfigurationModel();
 
         // Get the semester from the configuration table
-        $this->semester  = $this->configModel->getConfig('semester');
+        $this->semester  = getSemester();
         $this->schoolYear = $this->configModel->getConfig('school_year');
     }
 

app/Controllers/View/ClassPrepController.php

@@ -26,8 +26,9 @@ class ClassPrepController extends PrintablesBaseController
         $isGrade5     = static fn(string $g) => (bool) preg_match('/^5(\-|$)/', trim($g));
 
         $b = $this->db->table('student_class sc')
-            ->select('sc.student_id, s.firstname, s.lastname, s.is_new, cs.class_section_name AS grade_label')
+            ->select('sc.student_id, s.firstname, s.lastname, COALESCE(sys.is_new, s.is_new, 1) AS is_new, cs.class_section_name AS grade_label', false)
             ->join('students s', 's.id = sc.student_id', 'inner')
+            ->join('student_year_status sys', 'sys.student_id = s.id AND sys.school_year = sc.school_year', 'left')
             ->join('classSection cs', 'cs.class_section_id = sc.class_section_id', 'inner')
             ->join('classes c', 'c.id = cs.class_id', 'inner')
             ->where('sc.school_year', $schoolYear);
@@ -122,14 +123,9 @@ class ClassPrepController extends PrintablesBaseController
 
         // --- Pull roster: student_class -> classSection -> classes -> students ---
         $builder = $this->db->table('student_class sc')
-            ->select([
-                'sc.student_id',
-                's.firstname',
-                's.lastname',
-                's.is_new',
-                'cs.class_section_name AS grade_label',
-            ])
+            ->select('sc.student_id, s.firstname, s.lastname, COALESCE(sys.is_new, s.is_new, 1) AS is_new, cs.class_section_name AS grade_label', false)
             ->join('students s', 's.id = sc.student_id')
+            ->join('student_year_status sys', 'sys.student_id = s.id AND sys.school_year = sc.school_year', 'left')
             ->join('classSection cs', 'cs.class_section_id = sc.class_section_id')
             ->join('classes c', 'c.id = cs.class_id')
             ->where('sc.school_year', $schoolYear);
@@ -217,8 +213,9 @@ class ClassPrepController extends PrintablesBaseController
         $isGrade5     = static fn($g) => (bool) preg_match('/^5(\-|$)/', trim($g));
 
         $b = $this->db->table('student_class sc')
-            ->select('sc.student_id, s.firstname, s.lastname, s.is_new, cs.class_section_name AS grade_label')
+            ->select('sc.student_id, s.firstname, s.lastname, COALESCE(sys.is_new, s.is_new, 1) AS is_new, cs.class_section_name AS grade_label', false)
             ->join('students s', 's.id = sc.student_id')
+            ->join('student_year_status sys', 'sys.student_id = s.id AND sys.school_year = sc.school_year', 'left')
             ->join('classSection cs', 'cs.class_section_id = sc.class_section_id')
             ->join('classes c', 'c.id = cs.class_id')
             ->where('sc.school_year', $schoolYear)

app/Controllers/View/ClassPreparationController.php

@@ -21,8 +21,10 @@ class ClassPreparationController extends BaseController
     protected $schoolYear;
     protected $semester;
     protected $adjustmentModel;
-    /** cache for roster presence per term */
+    /** Cache for roster presence per school year. */
     private array $rosterPresenceCache = [];
+    /** Cache table-column checks to avoid repeated schema queries. */
+    private array $columnExistsCache = [];
     // Inside ClassPreparationController (class scope, not inside a method)
     private array $allowedPrepCategories = [
         'Grade Box',
@@ -48,7 +50,7 @@ class ClassPreparationController extends BaseController
         $this->db = \Config\Database::connect();
 
         $this->schoolYear = $this->configModel->getConfig('school_year');
-        $this->semester = $this->configModel->getConfig('semester');
+        $this->semester = getSemester();
     }
 
     public function index()
@@ -57,7 +59,7 @@ class ClassPreparationController extends BaseController
         $semParam   = $this->request->getGet('semester');
         $semester   = (is_string($semParam) && $semParam !== '') ? (string)$semParam : (string)$this->semester;
         $allowed    = $this->allowedPrepCategories;
-        $limitToSemester = $this->hasRosterForSemester($schoolYear, $semester);
+        $hasRoster  = $this->hasRosterForSchoolYear($schoolYear);
 
         // 1) Get student count per class-section (distinct students, correct semester)
         $scQ = $this->db->table('student_class sc')
@@ -65,13 +67,12 @@ class ClassPreparationController extends BaseController
             ->join('students s', 's.id = sc.student_id', 'inner')
             ->where('s.is_active', 1)
             ->where('sc.school_year', $schoolYear);
-        if ($limitToSemester && $semester !== '') {
-            $scQ->where('sc.semester', $semester);
-        }
-        $classSections = $scQ->groupBy('sc.class_section_id')->get()->getResultArray();
+        $classSections = $hasRoster
+            ? $scQ->groupBy('sc.class_section_id')->get()->getResultArray()
+            : [];
 
         // 2) Inventory availability — prefer good_qty when present, else condition='good' quantity.
-        $inventoryMap = $this->buildInventoryAvailability($schoolYear, $semester, $limitToSemester, $allowed);
+        $inventoryMap = $this->buildInventoryAvailability($schoolYear, $semester, $allowed);
 
         // Seed totals with allowed categories for stable ordering
         $requiredTotals = array_fill_keys($allowed, 0);
@@ -85,14 +86,10 @@ class ClassPreparationController extends BaseController
             $className      = $this->classSectionModel->getClassSectionNameBySectionId($classSectionId);
 
             // Calculate required items (whitelist inside)
-            $baseItems = $this->calculatePrepItems($studentCount, $classLevel, $classSectionId);
+            $baseItems = $this->calculatePrepItems($studentCount, $classLevel, $classSectionId, $schoolYear);
 
             // --- Apply adjustments (only Small/Large Table), clamp >= 0 ---
-            $rawAdjustments = $this->adjustmentModel
-                ->where('class_section_id', $classSectionId)
-                ->where('school_year', $schoolYear)
-                ->where('adjustable', 1)
-                ->findAll();
+            $rawAdjustments = $this->getAdjustments((string) $classSectionId, (string) $schoolYear);
 
             $adjMap = ['Large Table' => 0, 'Small Table' => 0];
 
@@ -117,11 +114,7 @@ class ClassPreparationController extends BaseController
             }
 
             // 5) Compare with last snapshot; do not save here — only on print or explicit API
-            $oldSnap = $this->prepLogModel
-                ->where('class_section_id', $classSectionId)
-                ->where('school_year', $schoolYear)
-                ->orderBy('created_at', 'DESC')
-                ->first();
+            $oldSnap = $this->getLatestPrepSnapshot((string) $classSectionId, (string) $schoolYear);
 
             $oldPrep    = $oldSnap ? json_decode($oldSnap['prep_data'], true) : [];
             $hasChanged = $this->hasPrepChanged($baseItems, $oldPrep);
@@ -175,7 +168,7 @@ class ClassPreparationController extends BaseController
         return (int)($row['cnt'] ?? 0);
     }
 
-    private function calculatePrepItems(int $students, int $classLevel, string $classSectionId): array
+    private function calculatePrepItems(int $students, int $classLevel, string $classSectionId, ?string $schoolYear = null): array
     {
         // 1) Stable keys: your whitelist, all zero to start
         $allowed = $this->allowedPrepCategories;
@@ -192,7 +185,7 @@ class ClassPreparationController extends BaseController
 
         // 3) Rules
         $isLowerGrades = in_array($classLevel, [1, 2], true);
-        $teacherCount  = $this->getTeacherCountForSection($classSectionId, $this->schoolYear);
+        $teacherCount  = $this->getTeacherCountForSection($classSectionId, $schoolYear ?? $this->schoolYear);
 
         foreach ($categories as $cat) {
             $name     = $cat['name'];      // e.g., 'Small Table'
@@ -253,24 +246,35 @@ class ClassPreparationController extends BaseController
         $adjustments = $data['adjustments'] ?? [];
 
         foreach ($adjustments as $itemName => $adjustment) {
-            $row = $this->adjustmentModel
+            $adjustmentQuery = $this->adjustmentModel
                 ->where('class_section_id', $sectionId)
-                ->where('school_year', $schoolYear)
-                ->where('item_name', $itemName)
-                ->first();
+                ->where('item_name', $itemName);
+
+            $adjustmentTable = $this->adjustmentModel->getTable();
+
+            if ($schoolYear !== '' && $this->tableHasColumn($adjustmentTable, 'school_year')) {
+                $adjustmentQuery->where('school_year', $schoolYear);
+            }
+
+            $row = $adjustmentQuery->first();
 
             if ($row) {
                 // Update
                 $this->adjustmentModel->update($row['id'], ['adjustment' => (int)$adjustment, 'adjustable' => 1]);
             } else {
                 // Insert
-                $this->adjustmentModel->insert([
+                $insertData = [
                     'class_section_id' => $sectionId,
                     'item_name'        => $itemName,
-                    'adjustment'       => (int)$adjustment,
-                    'school_year'      => $schoolYear,
+                    'adjustment'       => (int) $adjustment,
                     'adjustable'       => 1,
-                ]);
+                ];
+
+                if ($schoolYear !== '' && $this->tableHasColumn($adjustmentTable, 'school_year')) {
+                    $insertData['school_year'] = $schoolYear;
+                }
+
+                $this->adjustmentModel->insert($insertData);
             }
         }
 
@@ -292,10 +296,6 @@ class ClassPreparationController extends BaseController
 
     public function print($classSectionId, $schoolYear)
     {
-        $semParam = $this->request->getGet('semester');
-        $semester = (is_string($semParam) && $semParam !== '') ? (string) $semParam : (string) $this->semester;
-        $limitToSemester = $this->hasRosterForSemester((string) $schoolYear, $semester);
-
         // Friendly label (if you have this helper)
         $className = $this->classSectionModel->getClassSectionNameBySectionId($classSectionId) ?? $classSectionId;
 
@@ -306,15 +306,12 @@ class ClassPreparationController extends BaseController
             ->where('s.is_active', 1)
             ->where('sc.class_section_id', $classSectionId)
             ->where('sc.school_year', $schoolYear);
-        if ($limitToSemester && $semester !== '') {
-            $studentQ->where('sc.semester', $semester);
-        }
         $studentRow = $studentQ->get()->getRowArray();
         $studentCount = (int)($studentRow['cnt'] ?? 0);
 
         // Live calc + adjustments
         $classLevel = $this->getClassLevelBySection((string)$classSectionId);
-        $items      = $this->calculatePrepItems($studentCount, $classLevel, (string)$classSectionId);
+        $items      = $this->calculatePrepItems($studentCount, $classLevel, (string)$classSectionId, (string)$schoolYear);
 
         $rawAdjustments = $this->adjustmentModel
             ->where('class_section_id', $classSectionId)
@@ -328,13 +325,15 @@ class ClassPreparationController extends BaseController
         }
 
         // Record a snapshot at print time as the new baseline
-        $this->prepLogModel->insert([
-            'class_section_id' => (string)$classSectionId,
-            'class_section'    => $className,
-            'school_year'      => $schoolYear,
-            'prep_data'        => json_encode($items),
-            'created_at'       => utc_now(),
-        ]);
+        $this->prepLogModel->insert(
+            $this->buildPrepLogData(
+                (string) $classSectionId,
+                (string) $className,
+                (string) $schoolYear,
+                $items,
+                utc_now()
+            )
+        );
 
         // Return PRINT view (HTML) that auto-opens the print dialog
         return view('class_prep/print', [
@@ -356,7 +355,7 @@ class ClassPreparationController extends BaseController
         $semParam   = $this->request->getGet('semester');
         $semester   = (is_string($semParam) && $semParam !== '') ? (string)$semParam : (string)$this->semester;
         $allowed    = $this->allowedPrepCategories;
-        $limitToSemester = $this->hasRosterForSemester($schoolYear, $semester);
+        $hasRoster  = $this->hasRosterForSchoolYear($schoolYear);
 
         // Student counts
         $scQ = $this->db->table('student_class sc')
@@ -364,13 +363,12 @@ class ClassPreparationController extends BaseController
             ->join('students s', 's.id = sc.student_id', 'inner')
             ->where('s.is_active', 1)
             ->where('sc.school_year', $schoolYear);
-        if ($limitToSemester && $semester !== '') {
-            $scQ->where('sc.semester', $semester);
-        }
-        $classSections = $scQ->groupBy('sc.class_section_id')->get()->getResultArray();
+        $classSections = $hasRoster
+            ? $scQ->groupBy('sc.class_section_id')->get()->getResultArray()
+            : [];
 
         // Build inventory availability maps
-        $inventoryMap = $this->buildInventoryAvailability($schoolYear, $semester, $limitToSemester, $allowed);
+        $inventoryMap = $this->buildInventoryAvailability($schoolYear, $semester, $allowed);
 
         $requiredTotals = array_fill_keys($allowed, 0);
         $results = [];
@@ -381,12 +379,8 @@ class ClassPreparationController extends BaseController
             $classLevel     = $this->getClassLevelBySection($classSectionId);
             $className      = $this->classSectionModel->getClassSectionNameBySectionId($classSectionId);
 
-            $baseItems = $this->calculatePrepItems($studentCount, $classLevel, $classSectionId);
-            $rawAdjustments = $this->adjustmentModel
-                ->where('class_section_id', $classSectionId)
-                ->where('school_year', $schoolYear)
-                ->where('adjustable', 1)
-                ->findAll();
+            $baseItems = $this->calculatePrepItems($studentCount, $classLevel, $classSectionId, $schoolYear);
+            $rawAdjustments = $this->getAdjustments((string) $classSectionId, (string) $schoolYear);
             $adjMap = ['Large Table' => 0, 'Small Table' => 0];
             foreach ($rawAdjustments as $a) {
                 $item  = $a['item_name'];
@@ -399,11 +393,7 @@ class ClassPreparationController extends BaseController
                 $requiredTotals[$cat] += (int)($baseItems[$cat] ?? 0);
             }
 
-            $oldSnap = $this->prepLogModel
-                ->where('class_section_id', $classSectionId)
-                ->where('school_year', $schoolYear)
-                ->orderBy('created_at', 'DESC')
-                ->first();
+            $oldSnap = $this->getLatestPrepSnapshot((string) $classSectionId, (string) $schoolYear);
             $oldPrep    = $oldSnap ? json_decode($oldSnap['prep_data'], true) : [];
             $hasChanged = $this->hasPrepChanged($baseItems, $oldPrep);
 
@@ -446,7 +436,6 @@ class ClassPreparationController extends BaseController
         $schoolYear = (string)($this->request->getPost('school_year') ?? $this->schoolYear);
         $semParam   = $this->request->getPost('semester');
         $semester   = (is_string($semParam) && $semParam !== '') ? (string)$semParam : (string)$this->semester;
-        $limitToSemester = $this->hasRosterForSemester($schoolYear, $semester);
         $ids = $this->request->getPost('class_section_ids') ?? [];
         if (!is_array($ids)) $ids = $ids ? [$ids] : [];
         $ids = array_values(array_unique(array_filter(array_map('strval', $ids))));
@@ -460,21 +449,14 @@ class ClassPreparationController extends BaseController
                 ->where('s.is_active', 1)
                 ->where('sc.class_section_id', $classSectionId)
                 ->where('sc.school_year', $schoolYear);
-            if ($limitToSemester && $semester !== '') {
-                $studentQ->where('sc.semester', $semester);
-            }
             $studentRow = $studentQ->get()->getRowArray();
             $studentCount = (int)($studentRow['cnt'] ?? 0);
             $classLevel   = $this->getClassLevelBySection((string)$classSectionId);
             $className    = $this->classSectionModel->getClassSectionNameBySectionId($classSectionId) ?? $classSectionId;
 
-            $items = $this->calculatePrepItems($studentCount, $classLevel, (string)$classSectionId);
+            $items = $this->calculatePrepItems($studentCount, $classLevel, (string)$classSectionId, (string)$schoolYear);
 
-            $rawAdjustments = $this->adjustmentModel
-                ->where('class_section_id', $classSectionId)
-                ->where('school_year', $schoolYear)
-                ->where('adjustable', 1)
-                ->findAll();
+            $rawAdjustments = $this->getAdjustments((string) $classSectionId, (string) $schoolYear);
             foreach ($rawAdjustments as $a) {
                 $item  = $a['item_name'];
                 $delta = (int)$a['adjustment'];
@@ -482,13 +464,15 @@ class ClassPreparationController extends BaseController
             }
 
             try {
-                $this->prepLogModel->insert([
-                    'class_section_id' => (string)$classSectionId,
-                    'class_section'    => $className,
-                    'school_year'      => $schoolYear,
-                    'prep_data'        => json_encode($items),
-                    'created_at'       => $now,
-                ]);
+                $this->prepLogModel->insert(
+                    $this->buildPrepLogData(
+                        (string) $classSectionId,
+                        (string) $className,
+                        (string) $schoolYear,
+                        $items,
+                        $now
+                    )
+                );
                 $count++;
             } catch (\Throwable $e) {
                 // ignore and continue
@@ -528,12 +512,12 @@ class ClassPreparationController extends BaseController
     }
 
     /**
-     * Returns true if student_class has any rows for the given school year.
-     * The semester argument is ignored because assignments are tracked per year.
+     * Returns true when student_class contains at least one assignment
+     * for the selected school year.
      */
-    private function hasRosterForTerm(string $schoolYear, string $semester): bool
+    private function hasRosterForSchoolYear(string $schoolYear): bool
     {
-        $year = trim((string)$schoolYear);
+        $year = trim($schoolYear);
         if ($year === '') {
             return false;
         }
@@ -542,72 +526,163 @@ class ClassPreparationController extends BaseController
             return $this->rosterPresenceCache[$year];
         }
 
-        $cnt = $this->db->table('student_class')
+        $exists = $this->db->table('student_class')
             ->where('school_year', $year)
-            ->countAllResults();
+            ->limit(1)
+            ->countAllResults() > 0;
 
-        $this->rosterPresenceCache[$year] = $cnt > 0;
-        return $this->rosterPresenceCache[$year];
+        $this->rosterPresenceCache[$year] = $exists;
+
+        return $exists;
     }
 
-    private function hasRosterForSemester(string $schoolYear, string $semester): bool
+    private function tableHasColumn(string $table, string $column): bool
     {
-        $year = trim((string)$schoolYear);
-        $sem  = trim((string)$semester);
-        if ($year === '' || $sem === '') {
-            return false;
+        $key = $table . '.' . $column;
+
+        if (!array_key_exists($key, $this->columnExistsCache)) {
+            $this->columnExistsCache[$key] = $this->db->fieldExists($column, $table);
         }
 
-        $key = sprintf('sem:%s:%s', $year, $sem);
-        if (array_key_exists($key, $this->rosterPresenceCache)) {
-            return $this->rosterPresenceCache[$key];
-        }
-
-        $cnt = $this->db->table('student_class')
-            ->where('school_year', $year)
-            ->where('semester', $sem)
-            ->countAllResults();
-
-        $this->rosterPresenceCache[$key] = $cnt > 0;
-        return $this->rosterPresenceCache[$key];
+        return $this->columnExistsCache[$key];
     }
 
-    private function buildInventoryAvailability(string $schoolYear, string $semester, bool $limitToSemester, array $allowed): array
+    private function getAdjustments(string $classSectionId, string $schoolYear): array
+    {
+        $query = $this->adjustmentModel
+            ->where('class_section_id', $classSectionId)
+            ->where('adjustable', 1);
+
+        $table = $this->adjustmentModel->getTable();
+
+        if ($schoolYear !== '' && $this->tableHasColumn($table, 'school_year')) {
+            $query->where('school_year', $schoolYear);
+        }
+
+        return $query->findAll();
+    }
+
+    private function getLatestPrepSnapshot(string $classSectionId, string $schoolYear): ?array
+    {
+        $query = $this->prepLogModel
+            ->where('class_section_id', $classSectionId);
+
+        $table = $this->prepLogModel->getTable();
+
+        if ($schoolYear !== '' && $this->tableHasColumn($table, 'school_year')) {
+            $query->where('school_year', $schoolYear);
+        }
+
+        return $query
+            ->orderBy('created_at', 'DESC')
+            ->first();
+    }
+
+    private function buildPrepLogData(
+        string $classSectionId,
+        string $className,
+        string $schoolYear,
+        array $items,
+        string $createdAt
+    ): array {
+        $data = [
+            'class_section_id' => $classSectionId,
+            'class_section'    => $className,
+            'prep_data'        => json_encode($items),
+            'created_at'       => $createdAt,
+        ];
+
+        $table = $this->prepLogModel->getTable();
+
+        if ($schoolYear !== '' && $this->tableHasColumn($table, 'school_year')) {
+            $data['school_year'] = $schoolYear;
+        }
+
+        return $data;
+    }
+
+    private function buildInventoryAvailability(string $schoolYear, string $semester, array $allowed): array
     {
         $inventoryMap = array_fill_keys($allowed, 0);
 
+        $hasName       = $this->tableHasColumn('inventory_items', 'name');
+
         $joinRows = $this->db->table('inventory_items ii')
-            ->select('ic.name AS item_name, COALESCE(SUM(CASE WHEN ii.good_qty IS NOT NULL THEN ii.good_qty WHEN ii.`condition`="good" THEN ii.quantity ELSE 0 END),0) AS available')
+            ->select('ic.name AS item_name, COALESCE(SUM(CASE WHEN ii.good_qty IS NOT NULL THEN ii.good_qty WHEN ii.`condition` = "good" THEN ii.quantity ELSE 0 END), 0) AS available', false)
             ->join('inventory_categories ic', 'ic.id = ii.category_id', 'left')
             ->where('ii.type', 'classroom')
-            ->where('ii.school_year', $schoolYear)
             ->whereIn('ic.name', $allowed);
-        if ($limitToSemester && $semester !== '') {
-            $joinRows->where('ii.semester', $semester);
-        }
-        $joinRows = $joinRows->groupBy('ic.name')->get()->getResultArray();
 
-        foreach ($joinRows as $r) {
-            $name = (string)($r['item_name'] ?? '');
-            if ($name !== '' && isset($inventoryMap[$name])) {
-                $inventoryMap[$name] = max($inventoryMap[$name], (int)($r['available'] ?? 0));
+        $periodClauses = ['im.item_id = ii.id'];
+        if ($schoolYear !== '') {
+            $periodClauses[] = 'im.school_year = ' . $this->db->escape($schoolYear);
+        }
+        if ($semester !== '') {
+            $periodClauses[] = 'im.semester = ' . $this->db->escape($semester);
+        }
+        if (count($periodClauses) > 1) {
+            $joinRows->where(
+                'EXISTS (SELECT 1 FROM inventory_movements im WHERE ' . implode(' AND ', $periodClauses) . ')',
+                null,
+                false
+            );
+        }
+
+        $joinRows = $joinRows
+            ->groupBy('ic.name')
+            ->get()
+            ->getResultArray();
+
+        foreach ($joinRows as $row) {
+            $name = (string) ($row['item_name'] ?? '');
+
+            if ($name !== '' && array_key_exists($name, $inventoryMap)) {
+                $inventoryMap[$name] = max(
+                    $inventoryMap[$name],
+                    (int) ($row['available'] ?? 0)
+                );
             }
         }
 
-        $nameRows = $this->db->table('inventory_items')
-            ->select('name AS item_name, COALESCE(SUM(CASE WHEN good_qty IS NOT NULL THEN good_qty WHEN `condition`="good" THEN quantity ELSE 0 END),0) AS available')
-            ->where('type', 'classroom')
-            ->where('school_year', $schoolYear)
-            ->whereIn('name', $allowed);
-        if ($limitToSemester && $semester !== '') {
-            $nameRows->where('semester', $semester);
-        }
-        $nameRows = $nameRows->groupBy('name')->get()->getResultArray();
+        /*
+         * Some older schemas store the item name directly on inventory_items.
+         * Only run this fallback when that column actually exists.
+         */
+        if ($hasName) {
+            $nameRows = $this->db->table('inventory_items ii_name')
+                ->select('ii_name.name AS item_name, COALESCE(SUM(CASE WHEN ii_name.good_qty IS NOT NULL THEN ii_name.good_qty WHEN ii_name.`condition` = "good" THEN ii_name.quantity ELSE 0 END), 0) AS available', false)
+                ->where('ii_name.type', 'classroom')
+                ->whereIn('ii_name.name', $allowed);
 
-        foreach ($nameRows as $r) {
-            $name = (string)($r['item_name'] ?? '');
-            if ($name !== '' && isset($inventoryMap[$name])) {
-                $inventoryMap[$name] = max($inventoryMap[$name], (int)($r['available'] ?? 0));
+            $fallbackPeriodClauses = ['im.item_id = ii_name.id'];
+            if ($schoolYear !== '') {
+                $fallbackPeriodClauses[] = 'im.school_year = ' . $this->db->escape($schoolYear);
+            }
+            if ($semester !== '') {
+                $fallbackPeriodClauses[] = 'im.semester = ' . $this->db->escape($semester);
+            }
+            if (count($fallbackPeriodClauses) > 1) {
+                $nameRows->where(
+                    'EXISTS (SELECT 1 FROM inventory_movements im WHERE ' . implode(' AND ', $fallbackPeriodClauses) . ')',
+                    null,
+                    false
+                );
+            }
+
+            $nameRows = $nameRows
+                ->groupBy('ii_name.name')
+                ->get()
+                ->getResultArray();
+
+            foreach ($nameRows as $row) {
+                $name = (string) ($row['item_name'] ?? '');
+
+                if ($name !== '' && array_key_exists($name, $inventoryMap)) {
+                    $inventoryMap[$name] = max(
+                        $inventoryMap[$name],
+                        (int) ($row['available'] ?? 0)
+                    );
+                }
             }
         }
 

app/Controllers/View/CompetitionScoresController.php

@@ -244,7 +244,7 @@ class CompetitionScoresController extends BaseController
     {
         $userId = (int) (session()->get('user_id') ?? 0);
         $schoolYear = (string) ($this->configModel->getConfig('school_year') ?? '');
-        $semester = (string) ($this->configModel->getConfig('semester') ?? '');
+        $semester = (string) (getSemester() ?? '');
         $assignments = $this->teacherClassModel->getClassAssignmentsByUserId(
             $userId,
             $schoolYear,
@@ -386,12 +386,14 @@ class CompetitionScoresController extends BaseController
             return 0;
         }
 
-        $builder = $this->db->table($this->classStudentTable)
+        $builder = $this->db->table($this->classStudentTable . ' cs')
             ->select('COUNT(*) AS total')
-            ->where('class_section_id', $classSectionId);
+            ->join('students s', 's.id = cs.student_id', 'inner')
+            ->where('cs.class_section_id', $classSectionId)
+            ->where('s.is_active', 1);
 
         if ($schoolYear && $this->db->fieldExists('school_year', $this->classStudentTable)) {
-            $builder->where('school_year', $schoolYear);
+            $builder->where('cs.school_year', $schoolYear);
         }
 
         $row = $builder->get()->getRowArray();
@@ -407,7 +409,8 @@ class CompetitionScoresController extends BaseController
         $builder = $this->db->table('students s')
             ->select('s.id, s.school_id, s.firstname, s.lastname')
             ->join($this->classStudentTable . ' cs', 'cs.student_id = s.id', 'inner')
-            ->where('cs.class_section_id', $classSectionId);
+            ->where('cs.class_section_id', $classSectionId)
+            ->where('s.is_active', 1);
 
         $hasSchoolYear = $this->db->fieldExists('school_year', $this->classStudentTable);
         if ($hasSchoolYear && !empty($competition['school_year'])) {

app/Controllers/View/ContactController.php

@@ -6,7 +6,7 @@ use App\Controllers\BaseController;
 
 class ContactController extends BaseController
 {
-    public function __construct(private \CodeIgniter\HTTP\IncomingRequest $request)
+    public function __construct()
     {
         helper('form'); // Load the form helper
     }
@@ -24,10 +24,10 @@ class ContactController extends BaseController
 
         // Define validation rules
         $validation->setRules([
-            'name' => 'required|min_length[3]',
-            'email' => 'required|valid_email',
-            'subject' => 'required|min_length[3]',
-            'message' => 'required|min_length[10]'
+            'name' => "required|regex_match[/^[\\p{L}\\s'\\-]+$/u]|min_length[3]|max_length[100]",
+            'email' => 'required|valid_email|max_length[254]',
+            'subject' => 'required|min_length[3]|max_length[150]',
+            'message' => 'required|min_length[10]|max_length[5000]'
         ]);
 
         if (!$validation->withRequest($this->request)->run()) {
@@ -37,10 +37,10 @@ class ContactController extends BaseController
         }
 
         // Process form data
-        $name = $this->request->getPost('name');
-        $email = strtolower($this->request->getPost('email'));
-        $subject = $this->request->getPost('subject');
-        $message = $this->request->getPost('message');
+        $name = esc((string) $this->request->getPost('name'));
+        $email = esc(strtolower((string) $this->request->getPost('email')));
+        $subject = esc((string) $this->request->getPost('subject'));
+        $message = nl2br(esc((string) $this->request->getPost('message')));
 
         // Initialize the EmailController
         $emailController = new \App\Controllers\View\EmailController();
@@ -63,4 +63,4 @@ class ContactController extends BaseController
 
         return redirect()->to('/parent/contact');
     }
-}
+}

app/Controllers/View/DiscountController.php

@@ -2,6 +2,7 @@
 
 namespace App\Controllers\View;
 use App\Controllers\BaseController;
+use App\Libraries\InvoiceLedgerService;
 use App\Models\DiscountVoucherModel;
 use App\Models\DiscountUsageModel;
 use App\Models\InvoiceModel;
@@ -28,6 +29,7 @@ class DiscountController extends BaseController
     protected $eventChargesModel;
     protected $additionalChargeModel;
     protected $classSectionModel;
+    protected $invoiceLedgerService;
 
     public function __construct()
     {
@@ -41,13 +43,16 @@ class DiscountController extends BaseController
         $this->eventChargesModel = new EventChargesModel();
         $this->additionalChargeModel = new AdditionalChargeModel();
         $this->classSectionModel = new ClassSectionModel();
+        $this->invoiceLedgerService = new InvoiceLedgerService();
 
-        $this->schoolYear = $this->configModel->getConfig('school_year');
-        $this->semester = $this->configModel->getConfig('semester');
+        $this->schoolYear = $this->activeSchoolYearName();
+        $this->semester = getSemester();
     }
 
     public function applyVoucher()
     {
+        $this->schoolYear = $this->activeSchoolYearName();
+
         if (strtolower($this->request->getMethod()) === 'post') {
             $voucherId = $this->request->getPost('voucher_id');
             $parentIds = $this->request->getPost('parent_ids') ?? [];
@@ -105,9 +110,41 @@ class DiscountController extends BaseController
             // Collect invoice IDs that end up fully covered by the voucher in this run
             $fullyCoveredInvoiceIds = [];
             $touchedInvoiceIds = [];
+            $pendingEvents = [];
             $appliedCount = 0;
 
-            $this->db->transStart();
+            $this->db->transBegin();
+
+            try {
+                $lockedVoucher = $this->db->query('SELECT * FROM discount_vouchers WHERE id = ? FOR UPDATE', [(int)$voucherId])->getRowArray();
+                if (!$lockedVoucher) {
+                    throw new \RuntimeException('Voucher not found.');
+                }
+                $today = date('Y-m-d');
+                if ((int)($lockedVoucher['is_active'] ?? 0) !== 1) {
+                    throw new \RuntimeException('Voucher is inactive.');
+                }
+                if (!empty($lockedVoucher['valid_from']) && (string)$lockedVoucher['valid_from'] > $today) {
+                    throw new \RuntimeException('Voucher is not active yet.');
+                }
+                if (!empty($lockedVoucher['valid_until']) && (string)$lockedVoucher['valid_until'] < $today) {
+                    throw new \RuntimeException('Voucher is expired.');
+                }
+                if (!empty($lockedVoucher['school_year']) && (string)$lockedVoucher['school_year'] !== (string)$this->schoolYear) {
+                    throw new \RuntimeException('Voucher is not valid for this school year.');
+                }
+                if (!empty($lockedVoucher['semester']) && (string)$lockedVoucher['semester'] !== (string)$this->semester) {
+                    throw new \RuntimeException('Voucher is not valid for this semester.');
+                }
+
+                $voucher = $lockedVoucher;
+                $maxUsesRaw = $voucher['max_uses'] ?? null;
+                $maxUses = ($maxUsesRaw === null || $maxUsesRaw === '') ? null : (int) $maxUsesRaw;
+                $timesUsed = (int) ($voucher['times_used'] ?? 0);
+                $remainingUses = ($maxUses === null) ? PHP_INT_MAX : ($maxUses - $timesUsed);
+                if ($remainingUses <= 0) {
+                    throw new \RuntimeException('This voucher has reached its maximum allowed uses.');
+                }
 
             foreach ($parentIds as $parentId) {
                 // Fetch invoices for this parent & school year
@@ -121,9 +158,18 @@ class DiscountController extends BaseController
                 foreach ($invoices as $invoice) {
                     if ($remainingUses <= 0) break 2; // out of parentIds loop too
 
+                    $this->db->query('SELECT id FROM invoices WHERE id = ? FOR UPDATE', [(int) $invoice['id']]);
+                    $this->db->query('SELECT id FROM discount_usages WHERE invoice_id = ? FOR UPDATE', [(int)$invoice['id']])->getResultArray();
+
                     // Snapshot current balance BEFORE applying
-                    $initialPreBalance = (float) $this->getCurrentInvoiceBalance($invoice['id'], $this->schoolYear);
-                    if ($initialPreBalance <= 0) {
+                    $ledgerBefore = $this->invoiceLedgerService->calculateInvoice((int)$invoice['id']);
+                    $initialPreBalance = (float)($ledgerBefore['balance'] ?? 0);
+                    $eligibleBaseCents = max(
+                        0,
+                        (int)($ledgerBefore['discount_eligible_base_cents'] ?? 0)
+                        - (int)($ledgerBefore['applied_discount_cents'] ?? 0)
+                    );
+                    if ($eligibleBaseCents <= 0) {
                         log_message(
                             'error',
                             'applyVoucher skip: zero balance | voucher_id={vid} parent_id={pid} invoice_id={iid} invoice_number={inum} balance={bal}',
@@ -163,11 +209,14 @@ class DiscountController extends BaseController
 
                     // Calculate discount
                     $rawDiscount = ($voucher['discount_type'] === 'percent')
-                        ? round(((float)$invoice['total_amount'] * (float)$voucher['discount_value']) / 100, 2)
+                        ? round(($eligibleBaseCents / 100 * (float)$voucher['discount_value']) / 100, 2)
                         : (float) $voucher['discount_value'];
 
                     // Cap by CURRENT invoice balance snapshot
                     $discount = min($rawDiscount, $initialPreBalance);
+                    $requestedDiscountCents = max(0, (int)round($rawDiscount * 100));
+                    $appliedDiscountCents = min($requestedDiscountCents, $eligibleBaseCents);
+                    $discount = $appliedDiscountCents / 100;
 
                     // Nothing to do if no discount
                     if ($discount <= 0) {
@@ -188,7 +237,7 @@ class DiscountController extends BaseController
 
                     // Insert discount usage
                     $now = utc_now();
-                    $this->db->table('discount_usages')->insert([
+                    $usagePayload = [
                         'voucher_id'      => $voucherId,
                         'invoice_id'      => $invoice['id'],
                         'parent_id'       => $parentId,
@@ -199,30 +248,30 @@ class DiscountController extends BaseController
                         'used_at'         => $now,
                         'created_at'      => $now,
                         'updated_at'      => $now,
-                    ]);
+                    ];
+                    if ($this->db->fieldExists('requested_discount_cents', 'discount_usages')) {
+                        $usagePayload['requested_discount_cents'] = $requestedDiscountCents;
+                        $usagePayload['eligible_base_cents'] = $eligibleBaseCents;
+                        $usagePayload['eligible_base_before_cents'] = $eligibleBaseCents;
+                        $usagePayload['applied_discount_cents'] = $appliedDiscountCents;
+                        $usagePayload['application_order'] = $this->nextDiscountApplicationOrder((int)$invoice['id']);
+                    }
+                    if (!$this->db->table('discount_usages')->insert($usagePayload)) {
+                        throw new \RuntimeException('Discount usage could not be recorded.');
+                    }
 
-                    // Update invoice balance based on pre-discount snapshot (supports multiple discounts)
-                    $newBalance = max(0.0, round($initialPreBalance - $discount, 2));
-                    $this->db->table('invoices')
-                        ->where('id', $invoice['id'])
-                        ->update([
-                            'balance'      => $newBalance,
-                            'has_discount' => 1,
-                            'updated_at'   => $now,
-                        ]);
-
-                    // Compute post-balance based on pre-snapshot (more stable than $invoice['balance'])
-                    $postBalance = round($initialPreBalance - $discount, 2);
-                    if ($postBalance < 0) $postBalance = 0.0;
-
-                    // (Optional) current balance re-check (in case of concurrent writes)
-                    $currentBalance = (float) $this->getCurrentInvoiceBalance($invoice['id'], $this->schoolYear);
+                    $ledger = $this->invoiceLedgerService->recalculateInvoice((int) $invoice['id']);
+                    $postBalance = (float) ($ledger['balance'] ?? 0.0);
+                    $currentBalance = $postBalance;
 
                     // Increment voucher usage
-                    $this->db->table('discount_vouchers')
+                    $updatedVoucher = $this->db->table('discount_vouchers')
                         ->where('id', $voucherId)
                         ->set('times_used', 'COALESCE(times_used,0) + 1', false)
                         ->update();
+                    if (!$updatedVoucher) {
+                        throw new \RuntimeException('Voucher usage could not be updated.');
+                    }
 
                     // Prepare and trigger payment event
                     [$eventData, $studentData] = $this->buildPaymentEventData(
@@ -236,7 +285,7 @@ class DiscountController extends BaseController
                         $initialPreBalance,   // pre-payment snapshot
                         $postBalance          // computed post-payment
                     );
-                    Events::trigger('paymentReceived', $eventData, $studentData);
+                    $pendingEvents[] = [$eventData, $studentData];
 
                     $touchedInvoiceIds[] = (int) $invoice['id'];
                     $appliedCount++;
@@ -256,20 +305,27 @@ class DiscountController extends BaseController
 
                     // Deactivate if we just hit the cap
                     if ($remainingUses <= 0 && $maxUses !== null) {
-                        $this->db->table('discount_vouchers')
+                        $deactivated = $this->db->table('discount_vouchers')
                             ->where('id', $voucherId)
                             ->update([
                                 'is_active'  => 0,
                                 'updated_at' => $now,
                             ]);
+                        if (!$deactivated) {
+                            throw new \RuntimeException('Voucher could not be deactivated.');
+                        }
                         break 2;
                     }
                 }
             }
 
-            $this->db->transComplete();
-
-            if ($this->db->transStatus() === false) {
+                if ($this->db->transStatus() === false) {
+                    throw new \RuntimeException('Voucher transaction failed.');
+                }
+                $this->db->transCommit();
+            } catch (\Throwable $e) {
+                $this->db->transRollback();
+                log_message('error', 'Voucher application failed: ' . $e->getMessage() . "\n" . $e->getTraceAsString());
                 return redirect()->back()->with('error', 'Voucher application failed. Transaction rolled back.');
             }
 
@@ -295,6 +351,10 @@ class DiscountController extends BaseController
                 }
             }
 
+            foreach ($pendingEvents as [$eventData, $studentData]) {
+                Events::trigger('paymentReceived', $eventData, $studentData);
+            }
+
             // ✅ AFTER COMMIT: recalculate invoice totals/balance/paid/discount/refund
             foreach (array_unique($touchedInvoiceIds) as $iid) {
                 try {
@@ -344,7 +404,10 @@ class DiscountController extends BaseController
         unset($parent);
 
         return view('discounts/apply_voucher', [
-            'vouchers' => $this->voucherModel->where('is_active', 1)->findAll(),
+            'vouchers' => $this->voucherModel
+                ->where('is_active', 1)
+                ->where('school_year', $this->schoolYear)
+                ->findAll(),
             'parents'  => $parents,
         ]);
     }
@@ -406,7 +469,7 @@ class DiscountController extends BaseController
                 ->orWhere('enrollment_status', 'Payment pending')
                 ->orWhere('enrollment_status', 'Payment Pending')
                 ->orWhere('enrollment_status', 'PAYMENT PENDING')
-                ->orWhere("LOWER(TRIM(REPLACE(enrollment_status, CHAR(160), ' '))) = 'payment pending'", null, false)
+                ->orWhere("LOWER(TRIM(REPLACE(enrollment_status, CONVERT(0xC2A0 USING utf8mb4), ' '))) = 'payment pending'", null, false)
                 ->groupEnd();
 
             if (!empty($paidEnrollmentIds)) {
@@ -428,21 +491,31 @@ class DiscountController extends BaseController
                 return 0;
             }
 
-            // 5) Perform update with same filters
-            $builder = $db->table('enrollments');
-            $builder->set('enrollment_status', 'enrolled')
-                // Use DB date if you prefer: ->set('enrollment_date', 'CURRENT_DATE()', false)
-                ->set('enrollment_date', local_date(utc_now(), 'Y-m-d'))
-                ->whereIn('id', $toUpdateIds);
+            $rowsToUpdate = $db->table('enrollments')
+                ->whereIn('id', $toUpdateIds)
+                ->get()
+                ->getResultArray();
+            $statusService = \Config\Services::enrollmentStatus(false);
 
-            if ($builder->update() === false) {
-                $err = $db->error();
-                throw new \RuntimeException('Enrollments update failed: ' . ($err['message'] ?? 'unknown DB error'));
+            foreach ($rowsToUpdate as $row) {
+                $statusService->upsertStatus([
+                    'id' => (int) $row['id'],
+                    'student_id' => (int) $row['student_id'],
+                    'parent_id' => (int) $row['parent_id'],
+                    'school_year' => (string) $row['school_year'],
+                    'semester' => (string) ($row['semester'] ?? ''),
+                    'enrollment_date' => local_date(utc_now(), 'Y-m-d'),
+                    'enrollment_status' => 'enrolled',
+                    'admission_status' => 'accepted',
+                    'updated_at' => utc_now(),
+                ], (int) (session()->get('user_id') ?? 0) ?: null, 'discount_payment_completed');
             }
 
-            $affected = $db->affectedRows();
+            $affected = count($rowsToUpdate);
             $db->transCommit();
 
+            $this->triggerStudentEnrolledNotification($parentId, $rowsToUpdate);
+
             log_message(
                 'info',
                 'Enrollment status -> enrolled for {n} row(s). parent={p}, year={y}, sem={s}, ids=[{ids}]',
@@ -463,16 +536,73 @@ class DiscountController extends BaseController
         }
     }
 
+    private function triggerStudentEnrolledNotification(int $parentId, array $enrollmentRows): void
+    {
+        if ($parentId <= 0 || $enrollmentRows === []) {
+            return;
+        }
+
+        try {
+            $parent = $this->userModel->find($parentId) ?? [];
+            $studentIds = array_values(array_unique(array_filter(
+                array_map(static fn (array $row): int => (int) ($row['student_id'] ?? 0), $enrollmentRows),
+                static fn (int $studentId): bool => $studentId > 0
+            )));
+
+            if ($studentIds === []) {
+                return;
+            }
+
+            $students = [];
+            foreach ($this->db->table('students')->whereIn('id', $studentIds)->get()->getResultArray() as $student) {
+                $studentId = (int) ($student['id'] ?? 0);
+                if ($studentId <= 0) {
+                    continue;
+                }
+
+                $students[] = [
+                    'student_id' => $studentId,
+                    'name' => trim((string) ($student['firstname'] ?? '') . ' ' . (string) ($student['lastname'] ?? '')) ?: 'Student #' . $studentId,
+                ];
+            }
+
+            if ($students === []) {
+                return;
+            }
+
+            Events::trigger('studentEnrolled', [
+                'user_id' => $parent['id'] ?? $parentId,
+                'email' => $parent['email'] ?? null,
+                'firstname' => $parent['firstname'] ?? '',
+                'lastname' => $parent['lastname'] ?? '',
+                'school_year' => (string) $this->schoolYear,
+                'portalLink' => base_url('/login'),
+            ], $students);
+        } catch (\Throwable $e) {
+            log_message('error', 'Enrollment confirmation notification after discount failed for parent {parent_id}: {error}', [
+                'parent_id' => $parentId,
+                'error' => $e->getMessage(),
+            ]);
+        }
+    }
+
 
     public function listVouchers()
     {
+        $this->schoolYear = $this->currentSchoolYearName();
+
+        $vouchers = $this->voucherModel
+            ->where('school_year', $this->schoolYear)
+            ->orderBy('code', 'ASC')
+            ->findAll();
 
-        $vouchers = $this->voucherModel->findAll();
         return view('discounts/list', ['vouchers' => $vouchers]);
     }
 
     public function createVoucher()
     {
+        $this->schoolYear = $this->activeSchoolYearName();
+
         if (strtolower($this->request->getMethod()) === 'post') {
 
             // -------- Gather & normalize inputs --------
@@ -548,6 +678,7 @@ class DiscountController extends BaseController
                 'valid_until'    => $validUntil,
                 'is_active'      => $isActive,
                 'description'    => $description,   // <-- NEW
+                'school_year'    => $this->schoolYear,
             ];
 
             if ($this->voucherModel->save($data)) {
@@ -566,7 +697,11 @@ class DiscountController extends BaseController
 
     public function editVoucher($id)
     {
-        $voucher = $this->voucherModel->find($id);
+        $this->schoolYear = $this->activeSchoolYearName();
+
+        $voucher = $this->voucherModel
+            ->where('school_year', $this->schoolYear)
+            ->find($id);
 
         if (!$voucher) {
             return redirect()->to('discounts/list')->with('error', 'Voucher not found');
@@ -582,6 +717,7 @@ class DiscountController extends BaseController
                 'valid_from' => $this->request->getPost('valid_from') ?: null,
                 'valid_until' => $this->request->getPost('valid_until') ?: null,
                 'is_active' => $this->request->getPost('is_active') ? 1 : 0,
+                'school_year' => $this->schoolYear,
             ];
 
             $this->voucherModel->save($data);
@@ -591,58 +727,38 @@ class DiscountController extends BaseController
         return view('discounts/edit', ['voucher' => $voucher]);
     }
 
+    private function activeSchoolYearName(): string
+    {
+        try {
+            return service('schoolYearContext')->active()->yearName();
+        } catch (\Throwable) {
+            return (string) ($this->configModel->getConfig('school_year') ?? '');
+        }
+    }
+
+    protected function currentSchoolYearName(?string $fallback = null): string
+    {
+        try {
+            return service('schoolYearContext')->resolve($this->request)->yearName();
+        } catch (\Throwable) {
+            if ($fallback !== null && $fallback !== '') {
+                return $fallback;
+            }
+
+            return (string) ($this->configModel->getConfig('school_year') ?? '');
+        }
+    }
+
     /**
      * 🔄 Helper: Current invoice balance (school-year scoped) = total - payments - discounts - refundsPaid
      */
     private function getCurrentInvoiceBalance($invoiceId, $schoolYear)
     {
-        $invoice = $this->invoiceModel->find($invoiceId);
-        if (!$invoice) return 0.0;
-
-        // Payments (exclude void/refund/failed, honor year)
-        $qb = $this->paymentModel
-            ->select('COALESCE(SUM(paid_amount),0) AS total_paid')
-            ->where('invoice_id', $invoiceId)
-            ->where('school_year', $schoolYear);
-
-        $table = $this->paymentModel->table;
-        $hasStatus = $this->db->fieldExists('status', $table);
-        $hasVoid   = $this->db->fieldExists('is_void', $table);
-        if ($hasStatus) {
-            $qb->groupStart()
-                ->whereNotIn('status', ['void', 'voided', 'refunded', 'failed', 'chargeback', 'declined', 'reversed', 'canceled', 'cancelled'])
-                ->orWhere('status IS NULL', null, false)
-            ->groupEnd();
+        try {
+            return (float) ($this->invoiceLedgerService->calculateInvoice((int) $invoiceId)['balance'] ?? 0.0);
+        } catch (\Throwable $e) {
+            return 0.0;
         }
-        if ($hasVoid) {
-            $qb->groupStart()
-                ->where('is_void', 0)
-                ->orWhere('is_void IS NULL', null, false)
-            ->groupEnd();
-        }
-        $rowPaid   = $qb->first();
-        $totalPaid = (float)($rowPaid['total_paid'] ?? 0);
-
-        // Discounts for this invoice in this year
-        $rowDisc = $this->db->table('discount_usages du')
-            ->select('COALESCE(SUM(du.discount_amount),0) AS total_disc')
-            ->join('invoices i', 'i.id = du.invoice_id')
-            ->where('du.invoice_id', $invoiceId)
-            ->where('i.school_year', $schoolYear)
-            ->get()->getRowArray();
-        $totalDisc = (float)($rowDisc['total_disc'] ?? 0);
-
-        // Refunds PAID for this invoice in this year
-        $rowRefund = $this->db->table('refunds')
-            ->select('COALESCE(SUM(refund_paid_amount),0) AS total_refund_paid')
-            ->where('invoice_id', $invoiceId)
-            ->where('school_year', $schoolYear)
-            ->whereIn('status', ['Partial', 'Paid'])
-            ->get()->getRowArray();
-        $totalRefundPaid = (float)($rowRefund['total_refund_paid'] ?? 0);
-
-        $total = (float)($invoice['total_amount'] ?? 0);
-        return max(0.0, round($total - $totalPaid - $totalDisc - $totalRefundPaid, 2));
     }
 
     /**
@@ -650,169 +766,7 @@ class DiscountController extends BaseController
      */
     private function recalculateInvoice($invoiceId, $schoolYear): void
     {
-        $invoice = $this->invoiceModel->find($invoiceId);
-        if (!$invoice) return;
-
-        $parentId = (int)($invoice['parent_id'] ?? 0);
-        if ($parentId <= 0) return;
-
-        // ---- Tuition (recompute from enrollments) ----
-        $enrollments = $this->enrollmentModel
-            ->where('parent_id', $parentId)
-            ->where('school_year', $schoolYear)
-            ->findAll();
-
-        $registered = [];
-        $withdrawn  = [];
-        foreach ($enrollments as $e) {
-            $row = [
-                'student_id'       => (int)($e['student_id'] ?? 0),
-                'class_section_id' => $e['class_section_id'] ?? null,
-                'enrollment_status'=> (string)($e['enrollment_status'] ?? ''),
-            ];
-            if (in_array($row['enrollment_status'], ['enrolled','payment pending'], true)) {
-                $registered[] = $row;
-            } elseif (in_array($row['enrollment_status'], ['withdrawn','refund pending','withdraw under review'], true)) {
-                $withdrawn[] = $row;
-            }
-        }
-
-        // Refund window check – if after deadline, withdrawn still billed
-        $refundDeadline = (string)($this->configModel->getConfig('refund_deadline') ?? '');
-        $refundAllowed  = true;
-        try {
-            $tzName   = (string) (config('School')->attendance['timezone'] ?? user_timezone());
-            $tz       = new \DateTimeZone($tzName);
-            $today    = new \DateTimeImmutable('today', $tz);
-            $deadline = new \DateTimeImmutable($refundDeadline, $tz);
-            $refundAllowed = $today <= $deadline;
-        } catch (\Throwable $e) {
-            $refundAllowed = true;
-        }
-
-        $tuitionStudents = $registered;
-        if (!$refundAllowed) {
-            $tuitionStudents = array_merge($tuitionStudents, $withdrawn);
-        }
-
-        // Grade threshold and fees
-        $gradeFee         = (int)($this->configModel->getConfig('grade_fee') ?? 9);
-        $firstStudentFee  = (float)($this->configModel->getConfig('first_student_fee')  ?? 350);
-        $secondStudentFee = (float)($this->configModel->getConfig('second_student_fee') ?? 200);
-        $youthFee         = (float)($this->configModel->getConfig('youth_fee')          ?? 180);
-
-        // Normalize grades for tuition students
-        foreach ($tuitionStudents as &$s) {
-            $name = null;
-            if (!empty($s['class_section_id'])) {
-                $name = $this->classSectionModel->getClassSectionNameBySectionId($s['class_section_id']);
-            }
-            $s['grade_name'] = is_string($name) ? strtoupper(trim($name)) : 'N/A';
-        }
-        unset($s);
-
-        // Count regular vs youth and compute tuition
-        $regularCount = 0;
-        $youthCount   = 0;
-        foreach ($tuitionStudents as $s) {
-            $lvl = $this->parseGradeLevel($s['grade_name']);
-            if ($lvl > $gradeFee) $youthCount++; else $regularCount++;
-        }
-
-        $tuitionSubtotal = 0.0;
-        $tuitionSubtotal += $youthCount * $youthFee;
-        if ($regularCount >= 2) {
-            $tuitionSubtotal += $firstStudentFee + ($regularCount - 1) * $secondStudentFee;
-        } elseif ($regularCount === 1) {
-            $tuitionSubtotal += $firstStudentFee;
-        }
-
-        // ---- Event charges (parent-year) ----
-        $eventSubtotal = 0.0;
-        try {
-            $events = $this->eventChargesModel->getChargesWithEventInfo($parentId, $schoolYear) ?? [];
-            foreach ($events as $ev) { $eventSubtotal += (float)($ev['charged'] ?? 0.0); }
-        } catch (\Throwable $e) {}
-
-        // ---- Additional charges (per-invoice) ----
-        $additionalSubtotal = 0.0;
-        try {
-            $rows = $this->additionalChargeModel
-                ->select('charge_type, amount')
-                ->where('invoice_id', $invoiceId)
-                ->where('status', 'applied')
-                ->findAll();
-            foreach ($rows as $r) {
-                $amt = (float)($r['amount'] ?? 0);
-                $typ = strtolower((string)($r['charge_type'] ?? 'add'));
-                if ($typ === 'deduct') $amt = -abs($amt); else $amt = abs($amt);
-                $additionalSubtotal += $amt;
-            }
-        } catch (\Throwable $e) {}
-
-        $discountableTotal = $tuitionSubtotal + $additionalSubtotal;
-        $nonDiscountableTotal = $eventSubtotal;
-        $newTotal = round($discountableTotal + $nonDiscountableTotal, 2);
-
-        // ---- Payments / Discounts / Refunds ----
-        $db        = $this->db;
-        $table     = $this->paymentModel->table;
-        $hasStatus = $db->fieldExists('status', $table);
-        $hasVoid   = $db->fieldExists('is_void', $table);
-        $exclude   = ['void', 'voided', 'refunded', 'failed', 'chargeback', 'declined', 'reversed', 'canceled', 'cancelled'];
-
-        $qb = $this->paymentModel
-            ->where('invoice_id', $invoiceId)
-            ->where('school_year', $schoolYear);
-
-        if ($hasStatus) {
-            $qb->groupStart()
-                ->whereNotIn('status', $exclude)
-                ->orWhere('status IS NULL', null, false)
-                ->groupEnd();
-        }
-
-        if ($hasVoid) {
-            $qb->groupStart()
-                ->where('is_void', 0)
-                ->orWhere('is_void IS NULL', null, false)
-                ->groupEnd();
-        }
-
-        $payments = $qb->findAll();
-        $totalPaid = 0.0;
-        foreach ($payments as $p) { $totalPaid += (float)($p['paid_amount'] ?? 0); }
-
-        $discRow = $this->db->table('discount_usages')
-            ->select('COALESCE(SUM(discount_amount),0) AS total_disc')
-            ->where('invoice_id', $invoiceId)
-            ->get()->getRowArray();
-        $totalDisc = (float)($discRow['total_disc'] ?? 0);
-
-        $refundRow = $this->db->table('refunds')
-            ->select('COALESCE(SUM(refund_paid_amount),0) AS total_refund_paid')
-            ->where('invoice_id', $invoiceId)
-            ->whereIn('status', ['Partial','Paid'])
-            ->get()->getRowArray();
-        $totalRefundPaid = (float)($refundRow['total_refund_paid'] ?? 0);
-
-        $appliedDiscount = min($totalDisc, $discountableTotal);
-        $newBalance = max(0.0, $newTotal - $appliedDiscount - $totalPaid - $totalRefundPaid);
-        $newStatus  = ($newBalance <= 0.00001) ? 'Paid' : (($totalPaid > 0) ? 'Partially Paid' : 'Unpaid');
-
-        $updateData = [
-            'total_amount' => $newTotal,
-            'paid_amount'  => $totalPaid,
-            'balance'      => $newBalance,
-            'status'       => $newStatus,
-            'has_discount' => ($totalDisc > 0.0) ? 1 : 0,
-        ];
-
-        if ($this->db->fieldExists('discount', $this->invoiceModel->table)) {
-            $updateData['discount'] = $totalDisc;
-        }
-
-        $this->invoiceModel->update($invoiceId, $updateData);
+        $this->invoiceLedgerService->recalculateInvoice((int) $invoiceId);
     }
 
     /**
@@ -844,6 +798,17 @@ class DiscountController extends BaseController
         return 999;
     }
 
+    private function nextDiscountApplicationOrder(int $invoiceId): int
+    {
+        $row = $this->db->table('discount_usages')
+            ->select('COALESCE(MAX(application_order),0) + 1 AS next_order', false)
+            ->where('invoice_id', $invoiceId)
+            ->get()
+            ->getRowArray();
+
+        return max(1, (int)($row['next_order'] ?? 1));
+    }
+
     /**
      * Collect parent/invoice/payment data to trigger handlePaymentReceived().
      *

app/Controllers/View/EventController.php

@@ -15,11 +15,15 @@ use App\Models\ClassSectionModel;
 use App\Models\ParentModel;
 use App\Models\PaymentModel;
 use App\Models\CalendarModel;
+use App\Libraries\FinancialStatus;
+use App\Libraries\InvoiceLedgerService;
 use App\Services\EmailService;
 use Config\Database;
-#use ??? 
 use App\Controllers\View\InvoiceController;
+use CodeIgniter\HTTP\ResponseInterface;
 use CodeIgniter\RESTful\ResourceController;
+use Dompdf\Dompdf;
+use Dompdf\Options;
 
 class EventController extends ResourceController
 {
@@ -40,7 +44,9 @@ class EventController extends ResourceController
     protected $semester;
     protected $categories;
     protected $enrollmentModel;
+    protected $invoiceLedgerService;
     private ?bool $eventChargesHasCreatedBy = null;
+    private ?bool $eventChargesHasWaiverSigned = null;
 
     public function __construct()
     {
@@ -58,9 +64,10 @@ class EventController extends ResourceController
         $this->enrollmentModel = new EnrollmentModel();
         $this->parentModel = new ParentModel();
         $this->emailService = new EmailService();
+        $this->invoiceLedgerService = new InvoiceLedgerService();
 
-        $this->schoolYear = $this->configModel->getConfig('school_year');
-        $this->semester = $this->configModel->getConfig('semester');
+        $this->schoolYear = $this->currentSchoolYearName();
+        $this->semester = getSemester();
         $this->categories = [
             'workshops',
             'orientations',
@@ -85,25 +92,264 @@ class EventController extends ResourceController
         return $this->eventChargesHasCreatedBy;
     }
 
+    private function assertSchoolYearNameWritable(string $schoolYear): void
+    {
+        service('schoolYearWriteGuard')->assertWritable(
+            service('schoolYearContext')->forYearName($schoolYear)
+        );
+    }
+
+    private function currentSchoolYearName(): string
+    {
+        try {
+            return service('schoolYearContext')->resolve(service('request'))->yearName();
+        } catch (\Throwable $e) {
+            return (string) ($this->configModel->getConfig('school_year') ?? '');
+        }
+    }
+
+    private function eventChargesSupportsWaiverSigned(): bool
+    {
+        if ($this->eventChargesHasWaiverSigned !== null) {
+            return $this->eventChargesHasWaiverSigned;
+        }
+
+        try {
+            $db = Database::connect();
+            $this->eventChargesHasWaiverSigned = $db->fieldExists('waiver_signed', 'event_charges');
+        } catch (\Throwable $e) {
+            $this->eventChargesHasWaiverSigned = false;
+        }
+
+        return $this->eventChargesHasWaiverSigned;
+    }
+
+    private function getEventChargesReturnTo(): string
+    {
+        $fallback = site_url('administrator/event-charges');
+        $returnTo = trim((string) ($this->request->getPost('return_to') ?? ''));
+        if ($returnTo === '') {
+            return $fallback;
+        }
+
+        $base = rtrim((string) base_url(), '/');
+        if (str_starts_with($returnTo, '/')) {
+            return $returnTo;
+        }
+        if ($base !== '' && str_starts_with($returnTo, $base)) {
+            return $returnTo;
+        }
+
+        return $fallback;
+    }
+
+    private function loadEventChargesListingData(bool $includeParents = true): array
+    {
+        $schoolYear = $this->request->getGet('school_year') ?? $this->schoolYear;
+        $semester = $this->request->getGet('semester') ?? $this->semester;
+        $filterEventId = (int) ($this->request->getGet('event_id') ?? 0);
+        $filterParentId = (int) ($this->request->getGet('parent_id') ?? 0);
+
+        $parents = [];
+        if ($includeParents) {
+            $parents = $this->userModel->getParents();
+            usort($parents, static function (array $a, array $b): int {
+                $aLabel = trim(preg_replace('/\s+/', ' ', (string) ($a['firstname'] ?? '') . ' ' . (string) ($a['lastname'] ?? '')));
+                $bLabel = trim(preg_replace('/\s+/', ' ', (string) ($b['firstname'] ?? '') . ' ' . (string) ($b['lastname'] ?? '')));
+
+                $nameCmp = strnatcasecmp($aLabel, $bLabel);
+                if ($nameCmp !== 0) {
+                    return $nameCmp;
+                }
+
+                return strnatcasecmp((string) ($a['school_id'] ?? ''), (string) ($b['school_id'] ?? ''));
+            });
+        }
+
+        $events = $this->eventModel->getActiveEvents($schoolYear);
+
+        $chargesBuilder = $this->eventChargesModel
+            ->select('event_charges.*,
+                    users.firstname AS parent_firstname, users.lastname AS parent_lastname, users.cellphone AS parent_cellphone,
+                    students.firstname AS student_firstname, students.lastname AS student_lastname,
+                    events.event_name, events.description AS event_description, events.amount AS event_amount')
+            ->join('users', 'users.id = event_charges.parent_id', 'left')
+            ->join('students', 'students.id = event_charges.student_id', 'left')
+            ->join('events', 'events.id = event_charges.event_id', 'left')
+            ->where('event_charges.school_year', $schoolYear)
+            ->where('event_charges.semester', $semester);
+
+        if ($filterEventId > 0) {
+            $chargesBuilder->where('event_charges.event_id', $filterEventId);
+        }
+
+        if ($filterParentId > 0) {
+            $chargesBuilder->where('event_charges.parent_id', $filterParentId);
+        }
+
+        $charges = $chargesBuilder
+            ->orderBy('event_charges.created_at', 'DESC')
+            ->findAll();
+
+        foreach ($charges as &$charge) {
+            if (empty($charge['class_section_id']) && !empty($charge['student_id'])) {
+                $sections = $this->studentClassModel->getClassSectionIdsByStudentId(
+                    (int) $charge['student_id'],
+                    $schoolYear
+                );
+                if (!empty($sections)) {
+                    $charge['class_section_id'] = $sections[0];
+                }
+            }
+        }
+        unset($charge);
+
+        $parentBalances = [];
+        try {
+            $balanceRows = $this->invoiceModel
+                ->select('parent_id, COALESCE(SUM(balance),0) AS total_balance')
+                ->where('school_year', $schoolYear)
+                ->where('semester', $semester)
+                ->groupBy('parent_id')
+                ->findAll();
+
+            foreach ($balanceRows as $row) {
+                $parentBalances[(int) ($row['parent_id'] ?? 0)] = (float) ($row['total_balance'] ?? 0.0);
+            }
+        } catch (\Throwable $e) {
+            log_message('error', 'Failed to load parent balances: ' . $e->getMessage());
+        }
+
+        $sectionIds = array_unique(array_filter(array_column($charges, 'class_section_id')));
+        $classSectionNames = [];
+        if (!empty($sectionIds)) {
+            $sections = $this->classSectionModel
+                ->select('class_section_id, class_section_name')
+                ->whereIn('class_section_id', $sectionIds)
+                ->findAll();
+            foreach ($sections as $section) {
+                $classSectionNames[(int) ($section['class_section_id'] ?? 0)] = $section['class_section_name'] ?? '';
+            }
+        }
+
+        return [
+            'charges' => $charges,
+            'parents' => $parents,
+            'events' => $events,
+            'school_year' => $schoolYear,
+            'semester' => $semester,
+            'filterEventId' => $filterEventId,
+            'filterParentId' => $filterParentId,
+            'parentBalances' => $parentBalances,
+            'classSectionNames' => $classSectionNames,
+        ];
+    }
+
+    private function buildGroupedEventCharges(array $charges): array
+    {
+        $grouped = [];
+        foreach ($charges as $charge) {
+            $eventId = (int) ($charge['event_id'] ?? 0);
+            if (!isset($grouped[$eventId])) {
+                $grouped[$eventId] = [
+                    'label' => $charge['event_name'] ?? 'N/A',
+                    'rows' => [],
+                ];
+            }
+            $grouped[$eventId]['rows'][] = $charge;
+        }
+
+        return $grouped;
+    }
+
+    private function applyGroupedEventChargeRowOrder(array $groupedCharges): array
+    {
+        $rowOrder = $this->request->getGet('row_order');
+        if (!is_array($rowOrder) || empty($rowOrder)) {
+            return $groupedCharges;
+        }
+
+        foreach ($groupedCharges as $eventId => &$group) {
+            $rawOrder = $rowOrder[$eventId] ?? $rowOrder[(string) $eventId] ?? null;
+            if (!is_string($rawOrder) || trim($rawOrder) === '') {
+                continue;
+            }
+
+            $orderedIds = array_values(array_filter(array_map(
+                static fn ($value): int => (int) trim((string) $value),
+                explode(',', $rawOrder)
+            )));
+            if (empty($orderedIds) || empty($group['rows']) || !is_array($group['rows'])) {
+                continue;
+            }
+
+            $rowsById = [];
+            foreach ($group['rows'] as $row) {
+                $rowsById[(int) ($row['id'] ?? 0)] = $row;
+            }
+
+            $reorderedRows = [];
+            foreach ($orderedIds as $chargeId) {
+                if (isset($rowsById[$chargeId])) {
+                    $reorderedRows[] = $rowsById[$chargeId];
+                    unset($rowsById[$chargeId]);
+                }
+            }
+
+            foreach ($group['rows'] as $row) {
+                $chargeId = (int) ($row['id'] ?? 0);
+                if (isset($rowsById[$chargeId])) {
+                    $reorderedRows[] = $row;
+                    unset($rowsById[$chargeId]);
+                }
+            }
+
+            $group['rows'] = $reorderedRows;
+        }
+        unset($group);
+
+        return $groupedCharges;
+    }
+
+    private function buildEventChargesPdfFilename(array $data): string
+    {
+        $label = 'event_participant_lists';
+        if (!empty($data['filterEventId'])) {
+            foreach (($data['events'] ?? []) as $event) {
+                if ((int) ($event['id'] ?? 0) === (int) $data['filterEventId']) {
+                    $label = (string) ($event['event_name'] ?? $label);
+                    break;
+                }
+            }
+        }
+
+        $safeLabel = trim((string) preg_replace('/[^A-Za-z0-9]+/', '_', strtolower($label)), '_');
+        if ($safeLabel === '') {
+            $safeLabel = 'event_participant_lists';
+        }
+
+        return $safeLabel . '_' . date('Ymd_His') . '.pdf';
+    }
+
     public function index()
     {
-        $eventModel = new EventModel();
-
         $today = local_date(utc_now(), 'Y-m-d');
+        $schoolYear = $this->currentSchoolYearName();
 
-        // Fetch all events
-        $events = $eventModel
+        $events = $this->eventModel
+            ->where('school_year', $schoolYear)
             ->orderBy('created_at', 'DESC')
             ->findAll();
 
-        // Fetch active events (not expired)
-        $activeEventCount = $eventModel
+        $activeEventCount = $this->eventModel
+            ->where('school_year', $schoolYear)
             ->where('expiration_date >=', $today)
             ->countAllResults();
 
         return view('administrator/events/event_list', [
             'events' => $events,
-            'activeEventCount' => $activeEventCount
+            'activeEventCount' => $activeEventCount,
+            'schoolYear' => $schoolYear,
         ]);
     }
 
@@ -220,6 +466,59 @@ class EventController extends ResourceController
             ]);
 
             if ($updated) {
+                if ($this->request->getPost('add_to_calendar')) {
+                    $calendarModel = new CalendarModel();
+
+                    $title = trim((string) $this->request->getPost('event_name'));
+                    $date = (string) $this->request->getPost('expiration_date');
+                    $schoolYear = (string) $this->request->getPost('school_year');
+                    $semester = (string) $this->request->getPost('semester');
+
+                    if ($title !== '' && $date !== '' && $schoolYear !== '') {
+                        $data = [
+                            'title'          => $title,
+                            'description'    => (string) $this->request->getPost('description'),
+                            'event_type'     => 'Event',
+                            'date'           => $date,
+                            'notify_parent'  => $this->request->getPost('notify_parent') ? 1 : 0,
+                            'notify_teacher' => $this->request->getPost('notify_teacher') ? 1 : 0,
+                            'notify_admin'   => $this->request->getPost('notify_admin') ? 1 : 0,
+                            'no_school'      => 0,
+                            'school_year'    => $schoolYear,
+                            'semester'       => $semester ?: $this->semester,
+                        ];
+                        if (!$calendarModel->supportsEventType()) {
+                            unset($data['event_type']);
+                        }
+
+                        $existingByPreviousEvent = $calendarModel
+                            ->where('school_year', (string) ($event['school_year'] ?? ''))
+                            ->where('date', (string) ($event['expiration_date'] ?? ''))
+                            ->where('title', (string) ($event['event_name'] ?? ''));
+                        if ($calendarModel->supportsEventType() && isset($data['event_type'])) {
+                            $existingByPreviousEvent = $existingByPreviousEvent->where('event_type', $data['event_type']);
+                        }
+                        $existingCalendar = $existingByPreviousEvent->first();
+
+                        if ($existingCalendar) {
+                            $calendarModel->update($existingCalendar['id'], $data);
+                        } else {
+                            $dupQuery = $calendarModel
+                                ->where('school_year', $data['school_year'])
+                                ->where('date', $data['date'])
+                                ->where('title', $data['title']);
+                            if ($calendarModel->supportsEventType() && isset($data['event_type'])) {
+                                $dupQuery = $dupQuery->where('event_type', $data['event_type']);
+                            }
+                            $duplicate = $dupQuery->first();
+
+                            if (!$duplicate) {
+                                $calendarModel->save($data);
+                            }
+                        }
+                    }
+                }
+
                 $redirect = redirect()->to('/administrator/events')->with('success', 'Event updated successfully');
                 if ($this->request->getPost('send_email_parent')) {
                     $emailStatus = $this->broadcastEventToParents((int) $id);
@@ -386,74 +685,7 @@ class EventController extends ResourceController
     // Optionally keep your eventShow / eventUpdate for legacy administrator event charges
     public function eventShow()
     {
-
-        $schoolYear = $this->request->getGet('school_year') ?? $this->schoolYear;
-        $semester = $this->request->getGet('semester') ?? $this->semester;
-
-        $parents = $this->userModel->getParents();
-        $events = $this->eventModel->getActiveEvents($schoolYear);
-        $filterEventId = (int) ($this->request->getGet('event_id') ?? 0);
-        $filterParentId = (int) ($this->request->getGet('parent_id') ?? 0);
-
-        $chargesBuilder = $this->eventChargesModel
-            ->select('event_charges.*, 
-                    users.firstname AS parent_firstname, users.lastname AS parent_lastname, 
-                    students.firstname AS student_firstname, students.lastname AS student_lastname,
-                    events.event_name, events.description AS event_description, events.amount AS event_amount')
-            ->join('users', 'users.id = event_charges.parent_id', 'left')
-            ->join('students', 'students.id = event_charges.student_id', 'left')
-            ->join('events', 'events.id = event_charges.event_id', 'left')
-            ->where('event_charges.school_year', $schoolYear)
-            ->where('event_charges.semester', $semester);
-
-        if ($filterEventId > 0) {
-            $chargesBuilder->where('event_charges.event_id', $filterEventId);
-        }
-
-        $charges = $chargesBuilder
-            ->orderBy('event_charges.created_at', 'DESC')
-            ->findAll();
-
-        foreach ($charges as &$charge) {
-            if (empty($charge['class_section_id']) && !empty($charge['student_id'])) {
-                $sections = $this->studentClassModel->getClassSectionIdsByStudentId(
-                    (int)$charge['student_id'],
-                    $schoolYear
-                );
-                if (!empty($sections)) {
-                    $charge['class_section_id'] = $sections[0];
-                }
-            }
-        }
-        unset($charge);
-
-        $parentBalances = [];
-        try {
-            $balanceRows = $this->invoiceModel
-                ->select('parent_id, COALESCE(SUM(balance),0) AS total_balance')
-                ->where('school_year', $schoolYear)
-                ->where('semester', $semester)
-                ->groupBy('parent_id')
-                ->findAll();
-
-            foreach ($balanceRows as $row) {
-                $parentBalances[(int)($row['parent_id'] ?? 0)] = (float)($row['total_balance'] ?? 0.0);
-            }
-        } catch (\Throwable $e) {
-            log_message('error', 'Failed to load parent balances: ' . $e->getMessage());
-        }
-
-        $sectionIds = array_unique(array_filter(array_column($charges, 'class_section_id')));
-        $classSectionNames = [];
-        if (!empty($sectionIds)) {
-            $sections = $this->classSectionModel
-                ->select('class_section_id, class_section_name')
-                ->whereIn('class_section_id', $sectionIds)
-                ->findAll();
-            foreach ($sections as $section) {
-                $classSectionNames[(int)($section['class_section_id'] ?? 0)] = $section['class_section_name'] ?? '';
-            }
-        }
+        $data = $this->loadEventChargesListingData();
 
         $semesterOptions = (new EventChargesModel())
             ->select('semester')
@@ -475,19 +707,37 @@ class EventController extends ResourceController
             $schoolYearOptions = [$this->schoolYear];
         }
 
-        return view('administrator/events/event_charges', [
-            'charges' => $charges,
-            'parents' => $parents,
-            'events'  => $events,
-            'school_year' => $schoolYear,
-            'semester' => $semester,
-            'filterEventId' => $filterEventId,
-            'filterParentId' => $filterParentId,
-            'parentBalances' => $parentBalances,
-            'classSectionNames' => $classSectionNames,
+        return view('administrator/events/event_charges', array_merge($data, [
             'semesterOptions' => $semesterOptions,
             'schoolYearOptions' => $schoolYearOptions,
-        ]);
+        ]));
+    }
+
+    public function eventChargesPdf(): ResponseInterface
+    {
+        $data = $this->loadEventChargesListingData(false);
+        $groupedCharges = $this->buildGroupedEventCharges($data['charges']);
+        $groupedCharges = $this->applyGroupedEventChargeRowOrder($groupedCharges);
+        $generatedAt = date('m-d-Y h:i A');
+
+        $html = view('administrator/events/event_charges_pdf', array_merge($data, [
+            'groupedCharges' => $groupedCharges,
+            'generatedAt' => $generatedAt,
+        ]));
+
+        $options = new Options();
+        $options->set('isRemoteEnabled', true);
+        $options->set('defaultFont', 'DejaVu Sans');
+
+        $dompdf = new Dompdf($options);
+        $dompdf->loadHtml($html, 'UTF-8');
+        $dompdf->setPaper('A4', 'landscape');
+        $dompdf->render();
+
+        return $this->response
+            ->setHeader('Content-Type', 'application/pdf')
+            ->setHeader('Content-Disposition', 'inline; filename="' . $this->buildEventChargesPdfFilename($data) . '"')
+            ->setBody($dompdf->output());
     }
 
 
@@ -517,6 +767,7 @@ class EventController extends ResourceController
 
         $parentsForInvoice = [];
         $supportsCreatedBy = $this->eventChargesSupportsCreatedBy();
+        $supportsWaiverSigned = $this->eventChargesSupportsWaiverSigned();
 
         foreach ($participations as $studentId => $value) {
             $existing = $this->eventChargesModel->where([
@@ -543,6 +794,9 @@ class EventController extends ResourceController
                     'updated_by'      => $userId,
                     'class_section_id'=> $classSectionId,
                 ];
+                if ($supportsWaiverSigned) {
+                    $updateData['waiver_signed'] = (int) ($existing['waiver_signed'] ?? 0);
+                }
                 if (isset($event['amount']) && ((float)$event['amount'] !== (float)($existing['charged'] ?? 0))) {
                     $updateData['charged'] = $event['amount'];
                 }
@@ -561,6 +815,9 @@ class EventController extends ResourceController
                     'semester'      => $semester,
                     'updated_by'    => $userId
                 ];
+                if ($supportsWaiverSigned) {
+                    $insertData['waiver_signed'] = 0;
+                }
                 if ($supportsCreatedBy) {
                     $insertData['created_by'] = $userId;
                 }
@@ -577,6 +834,7 @@ class EventController extends ResourceController
             $parentPhone = trim($pieces['parent_phone'] ?? '');
             $parentEmail = trim((string)($pieces['parent_email'] ?? ''));
             $markPaid = (string)($pieces['paid'] ?? '0') === '1';
+            $waiverSigned = (string)($pieces['waiver_signed'] ?? '0') === '1';
 
             if (!$firstname && !$lastname) {
                 continue;
@@ -611,7 +869,7 @@ class EventController extends ResourceController
             $existingExternal = $this->eventChargesModel->where($matchConditions)->first();
 
             if ($existingExternal) {
-                $this->eventChargesModel->update($existingExternal['id'], [
+                $updateData = [
                     'participation' => 'yes',
                     'charged' => $event['amount'],
                     'updated_by' => $userId,
@@ -621,7 +879,11 @@ class EventController extends ResourceController
                     'external_parent_lastname' => $parentLast !== '' ? $parentLast : ($existingExternal['external_parent_lastname'] ?? null),
                     'external_parent_phone' => $parentPhone !== '' ? $parentPhone : ($existingExternal['external_parent_phone'] ?? null),
                     'external_parent_email' => $parentEmail !== '' ? $parentEmail : ($existingExternal['external_parent_email'] ?? null),
-                ]);
+                ];
+                if ($supportsWaiverSigned) {
+                    $updateData['waiver_signed'] = $waiverSigned ? 1 : 0;
+                }
+                $this->eventChargesModel->update($existingExternal['id'], $updateData);
                 continue;
             }
 
@@ -643,6 +905,9 @@ class EventController extends ResourceController
                 'semester' => $semester,
                 'updated_by' => $userId,
             ];
+            if ($supportsWaiverSigned) {
+                $insertData['waiver_signed'] = $waiverSigned ? 1 : 0;
+            }
             if ($supportsCreatedBy) {
                 $insertData['created_by'] = $userId;
             }
@@ -672,14 +937,16 @@ class EventController extends ResourceController
 
     public function removeCharge($chargeId = null)
     {
+        $returnTo = $this->getEventChargesReturnTo();
         if (!$chargeId) {
-            return redirect()->back()->with('error', 'Invalid charge.');
+            return redirect()->to($returnTo)->with('error', 'Invalid charge.');
         }
 
         $charge = $this->eventChargesModel->find($chargeId);
         if (!$charge) {
-            return redirect()->back()->with('error', 'Charge not found.');
+            return redirect()->to($returnTo)->with('error', 'Charge not found.');
         }
+        $this->assertSchoolYearNameWritable((string)($charge['school_year'] ?? ''));
 
         $paymentId = (int)($charge['event_payment_id'] ?? 0);
         if ($paymentId > 0) {
@@ -691,19 +958,20 @@ class EventController extends ResourceController
             $this->invoiceController->generateInvoice((string)$charge['parent_id'], (string)($charge['school_year'] ?? $this->schoolYear), (string)($charge['semester'] ?? $this->semester), false);
         }
 
-        return redirect()->back()->with('success', 'Participation removed, invoices updated.');
+        return redirect()->to($returnTo)->with('success', 'Participation removed, invoices updated.');
     }
 
     public function toggleEventPayment($chargeId = null)
     {
+        $returnTo = $this->getEventChargesReturnTo();
         if (!$chargeId) {
-            return redirect()->back()->with('error', 'Invalid charge.');
+            return redirect()->to($returnTo)->with('error', 'Invalid charge.');
         }
 
         $isPaid = $this->request->getPost('paid') === '1';
         $meta = $this->applyEventPaymentStatus((int)$chargeId, $isPaid);
         if (!$meta) {
-            return redirect()->back()->with('error', 'Charge not found.');
+            return redirect()->to($returnTo)->with('error', 'Charge not found.');
         }
 
         if (!empty($meta['invoice_id'])) {
@@ -711,7 +979,34 @@ class EventController extends ResourceController
             $this->fixInvoiceStatusAfterCharge((int)$meta['parent_id'], (string)$meta['school_year']);
         }
 
-        return redirect()->back()->with('success', 'Event payment status updated.');
+        return redirect()->to($returnTo)->with('success', 'Event payment status updated.');
+    }
+
+    public function toggleWaiverStatus($chargeId = null)
+    {
+        $returnTo = $this->getEventChargesReturnTo();
+        if (!$chargeId) {
+            return redirect()->to($returnTo)->with('error', 'Invalid charge.');
+        }
+
+        if (!$this->eventChargesSupportsWaiverSigned()) {
+            return redirect()->to($returnTo)->with('error', 'Waiver tracking is not available until the database migration is applied.');
+        }
+
+        $charge = $this->eventChargesModel->find($chargeId);
+        if (!$charge) {
+            return redirect()->to($returnTo)->with('error', 'Charge not found.');
+        }
+        $this->assertSchoolYearNameWritable((string)($charge['school_year'] ?? ''));
+
+        $signed = $this->request->getPost('waiver_signed') === '1';
+
+        $this->eventChargesModel->update((int) $chargeId, [
+            'waiver_signed' => $signed ? 1 : 0,
+            'updated_by' => session()->get('user_id'),
+        ]);
+
+        return redirect()->to($returnTo)->with('success', $signed ? 'Waiver marked as signed.' : 'Waiver marked as unsigned.');
     }
 
     private function parentHasEnrollment(int $parentId, string $schoolYear): bool
@@ -767,77 +1062,11 @@ class EventController extends ResourceController
             return;
         }
 
-        $invoice = $this->invoiceModel->find($invoiceId);
-        if (!$invoice) {
-            return;
-        }
-
-        $db = \Config\Database::connect();
-        $exclude = ['void', 'voided', 'refunded', 'failed', 'chargeback', 'declined', 'reversed', 'canceled', 'cancelled'];
-
-        $paidSum = 0.0;
         try {
-            $qb = $db->table('payments')
-                ->select('COALESCE(SUM(paid_amount),0) AS tot')
-                ->where('invoice_id', $invoiceId)
-                ->where('paid_amount >', 0);
-
-            if ($db->fieldExists('status', 'payments')) {
-                $qb->groupStart()
-                    ->whereNotIn('status', $exclude)
-                    ->orWhere('status IS NULL', null, false)
-                    ->groupEnd();
-            }
-            if ($db->fieldExists('is_void', 'payments')) {
-                $qb->groupStart()
-                    ->where('is_void', 0)
-                    ->orWhere('is_void IS NULL', null, false)
-                    ->groupEnd();
-            }
-
-            $row = $qb->get()->getRowArray();
-            $paidSum = (float)($row['tot'] ?? 0.0);
+            $this->invoiceLedgerService->recalculateInvoice($invoiceId);
         } catch (\Throwable $e) {
-            log_message('error', 'Failed to sum payments for invoice ' . $invoiceId . ': ' . $e->getMessage());
+            log_message('error', 'Failed to recalculate invoice ledger for invoice ' . $invoiceId . ': ' . $e->getMessage());
         }
-
-        $discountSum = 0.0;
-        try {
-            $row = $db->table('discount_usages')
-                ->select('COALESCE(SUM(discount_amount),0) AS tot')
-                ->where('invoice_id', $invoiceId)
-                ->get()
-                ->getRowArray();
-            $discountSum = (float)($row['tot'] ?? 0.0);
-        } catch (\Throwable $e) {
-            log_message('error', 'Failed to sum discounts for invoice ' . $invoiceId . ': ' . $e->getMessage());
-        }
-
-        $refundSum = 0.0;
-        try {
-            $row = $db->table('refunds')
-                ->select('COALESCE(SUM(refund_paid_amount),0) AS tot')
-                ->where('invoice_id', $invoiceId)
-                ->whereIn('status', ['Partial', 'Paid'])
-                ->get()
-                ->getRowArray();
-            $refundSum = (float)($row['tot'] ?? 0.0);
-        } catch (\Throwable $e) {
-            log_message('error', 'Failed to sum refunds for invoice ' . $invoiceId . ': ' . $e->getMessage());
-        }
-
-        $total = (float)($invoice['total_amount'] ?? 0.0);
-        $newBalance = round($total - $discountSum - $refundSum - $paidSum, 2);
-        $newStatus = ($newBalance <= 0.00001)
-            ? 'Paid'
-            : (($paidSum > 0) ? 'Partially Paid' : 'Unpaid');
-
-        $this->invoiceModel->update($invoiceId, [
-            'paid_amount' => $paidSum,
-            'balance' => $newBalance,
-            'status' => $newStatus,
-            'updated_at' => utc_now(),
-        ]);
     }
 
     private function applyEventPaymentStatus(int $chargeId, bool $isPaid): ?array
@@ -850,6 +1079,7 @@ class EventController extends ResourceController
         if (!$charge) {
             return null;
         }
+        $this->assertSchoolYearNameWritable((string)($charge['school_year'] ?? ''));
 
         $event = $this->eventModel->find($charge['event_id']);
         $eventAmount = max(0.0, (float)($event['amount'] ?? 0));
@@ -888,12 +1118,10 @@ class EventController extends ResourceController
                         $eventAmount,
                         $paymentSchoolYear,
                         $paymentSemester,
-                        (float)($invoice['total_amount'] ?? 0.0),
-                        (float)($invoice['paid_amount'] ?? 0.0),
-                        (float)($invoice['balance'] ?? 0.0)
+                        (float)($invoice['total_amount'] ?? 0.0)
                     ) ?? 0);
                 } elseif (!$isPaid && $paymentId > 0) {
-                    $this->paymentModel->delete($paymentId);
+                    $this->voidPayment($paymentId, 'Event charge marked unpaid.');
                     $paymentId = 0;
                 }
 
@@ -967,42 +1195,32 @@ class EventController extends ResourceController
         float $amount,
         string $schoolYear,
         ?string $semester,
-        float $invoiceTotal = 0.0,
-        float $invoicePaid = 0.0,
-        float $invoiceBalance = 0.0
+        float $invoiceTotal = 0.0
     ): ?int
     {
         if ($amount <= 0 || $invoiceId <= 0 || $parentId <= 0) {
             return null;
         }
 
-        $monthSemester = $semester ?: $this->semester;
-        $newPaid = (float)$invoicePaid + $amount;
-        $newBalance = (float)$invoiceBalance - $amount;
-        $paymentStatus = ($newBalance <= 0.00001)
-            ? 'Paid'
-            : (($newPaid > 0) ? 'Partially Paid' : 'Unpaid');
-
-        $exclude = ['void', 'voided', 'refunded', 'failed', 'chargeback', 'declined', 'reversed', 'canceled', 'cancelled'];
-        $priorCount = $this->paymentModel
+        $row = $this->paymentModel->db->table('payments')
+            ->select('COALESCE(MAX(installment_seq), 0) + 1 AS next_seq', false)
             ->where('invoice_id', $invoiceId)
-            ->where('paid_amount >', 0)
-            ->whereNotIn('status', $exclude)
-            ->countAllResults();
-        $installmentSeq = $priorCount + 1;
+            ->get()
+            ->getRowArray();
+        $installmentSeq = (int)($row['next_seq'] ?? 1);
 
         $data = [
             'parent_id' => $parentId,
             'invoice_id' => $invoiceId,
             'total_amount' => $invoiceTotal > 0 ? $invoiceTotal : $amount,
             'paid_amount' => $amount,
-            'balance' => $newBalance,
+            'balance' => null,
             'number_of_installments' => $installmentSeq,
+            'installment_seq' => $installmentSeq,
             'payment_method' => 'cash',
             'payment_date' => utc_now(),
             'school_year' => $schoolYear,
-            'semester' => $monthSemester,
-            'status' => $paymentStatus,
+            'status' => FinancialStatus::PAYMENT_RECORDED,
             'transaction_id' => $this->paymentModel->generateNewTransactionId(),
             'updated_by' => session()->get('user_id'),
         ];
@@ -1015,6 +1233,33 @@ class EventController extends ResourceController
         return (int)$this->paymentModel->getInsertID();
     }
 
+    private function voidPayment(int $paymentId, string $reason): bool
+    {
+        if ($paymentId <= 0) {
+            return false;
+        }
+
+        $data = [
+            'status' => FinancialStatus::PAYMENT_VOIDED,
+            'updated_by' => session()->get('user_id'),
+        ];
+
+        if ($this->paymentModel->db->fieldExists('is_void', 'payments')) {
+            $data['is_void'] = 1;
+        }
+        if ($this->paymentModel->db->fieldExists('voided_at', 'payments')) {
+            $data['voided_at'] = utc_now();
+        }
+        if ($this->paymentModel->db->fieldExists('voided_by', 'payments')) {
+            $data['voided_by'] = session()->get('user_id');
+        }
+        if ($this->paymentModel->db->fieldExists('void_reason', 'payments')) {
+            $data['void_reason'] = $reason;
+        }
+
+        return (bool) $this->paymentModel->update($paymentId, $data);
+    }
+
     private function normalizeExternalName(?string $value): string
     {
         $raw = trim((string)$value);
@@ -1044,13 +1289,9 @@ class EventController extends ResourceController
             ->findAll();
 
         foreach ($invoices as $invoice) {
-            $status = strtolower(trim($invoice['status'] ?? ''));
-            $balance = (float)($invoice['balance'] ?? 0.0);
-
-            if ($balance <= 0.00001 && $status !== 'paid') {
-                $this->invoiceModel->update($invoice['id'], ['status' => 'Paid']);
-            } elseif ($status === 'paid' && $balance > 0) {
-                $this->invoiceModel->update($invoice['id'], ['status' => 'Unpaid']);
+            $invoiceId = (int)($invoice['id'] ?? 0);
+            if ($invoiceId > 0) {
+                $this->invoiceLedgerService->recalculateInvoice($invoiceId);
             }
         }
     }

app/Controllers/View/ExamDraftController.php

@@ -65,7 +65,7 @@ class ExamDraftController extends BaseController
         $this->db = Database::connect();
 
         $this->schoolYear = (string) ($this->configModel->getConfig('school_year') ?? '');
-        $this->semester = (string) ($this->configModel->getConfig('semester') ?? '');
+        $this->semester = (string) (getSemester() ?? '');
         $this->hasFinalPdfColumn = $this->schemaHasColumn('exam_drafts', 'final_pdf_file');
         $this->hasIsLegacyColumn = $this->schemaHasColumn('exam_drafts', 'is_legacy');
         $this->hasAcceptanceTypeColumn = $this->schemaHasColumn('exam_drafts', 'acceptance_type');
@@ -91,6 +91,9 @@ class ExamDraftController extends BaseController
 
     public function teacherIndex()
     {
+        $this->syncAcademicContext();
+        $context = $this->resolveSchoolYearContext();
+
         $teacherId = (int) (session()->get('user_id') ?? 0);
         if ($teacherId <= 0) {
             return redirect()->to('/login');
@@ -102,11 +105,9 @@ class ExamDraftController extends BaseController
             session()->set('class_section_id', $selectedClass);
         }
 
-        $allDrafts = $this->examDraftModel
-            ->select($this->draftSelectColumns())
-            ->select('cs.class_section_name')
-            ->join('classSection cs', 'cs.class_section_id = exam_drafts.class_section_id', 'left')
-            ->where($this->authorIdColumn, $teacherId)
+        $classSectionIds = array_map(static fn($a) => (int) $a['class_section_id'], $assignments);
+
+        $allDrafts = $this->visibleTeacherDraftsQuery($teacherId, $classSectionIds)
             ->orderBy('created_at', 'DESC')
             ->findAll();
 
@@ -117,10 +118,10 @@ class ExamDraftController extends BaseController
                     $row['final_pdf_file'] = $pdf;
                 }
             }
+            $row = $this->attachTeacherDraftContext($row, $teacherId);
         }
         unset($row);
 
-        $classSectionIds = array_map(static fn($a) => (int) $a['class_section_id'], $assignments);
         $legacyExams = [];
         // Guard against missing schema column in older databases
         if ($this->hasIsLegacyColumn) {
@@ -129,8 +130,9 @@ class ExamDraftController extends BaseController
 
             $legacyQuery = $this->examDraftModel
                 ->select($this->draftSelectColumns())
-                ->select('cs.class_section_name')
+                ->select('cs.class_section_name, u.firstname AS teacher_first, u.lastname AS teacher_last')
                 ->join('classSection cs', 'cs.class_section_id = exam_drafts.class_section_id', 'left')
+                ->join('users u', 'u.id = exam_drafts.' . $this->authorIdColumn, 'left')
                 ->where('exam_drafts.is_legacy', 1)
                 ->where('exam_drafts.status', 'legacy')
                 ->where('exam_drafts.final_file IS NOT NULL', null, false);
@@ -143,6 +145,11 @@ class ExamDraftController extends BaseController
                 ->orderBy('cs.class_section_name', 'ASC')
                 ->orderBy('exam_drafts.created_at', 'DESC')
                 ->findAll();
+
+            foreach ($legacyExams as &$row) {
+                $row = $this->attachTeacherDraftContext($row, $teacherId);
+            }
+            unset($row);
         } else {
             // Legacy column absent, show all drafts and skip legacy tab query
             $drafts = $allDrafts;
@@ -171,11 +178,15 @@ class ExamDraftController extends BaseController
             'maxUploadBytes' => self::MAX_UPLOAD_BYTES,
             'validation' => $validation,
             'printableDraftIds' => $printableIds,
+            'isSchoolYearReadonly' => $context->isReadonly(),
         ]);
     }
 
     public function teacherStore()
     {
+        $this->syncAcademicContext();
+        $this->assertSchoolYearWritable($this->resolveSchoolYearContext());
+
         $teacherId = (int) (session()->get('user_id') ?? 0);
         if ($teacherId <= 0) {
             return redirect()->to('/login');
@@ -189,10 +200,13 @@ class ExamDraftController extends BaseController
             return redirect()->back()->withInput()->with('error', 'Select a class section before submitting.');
         }
 
-        $assignment = $this->teacherClassModel
+        $assignmentQuery = $this->teacherClassModel
             ->where('teacher_id', $teacherId)
-            ->where('class_section_id', $classSectionId)
-            ->first();
+            ->where('class_section_id', $classSectionId);
+        if ($this->schoolYear !== '') {
+            $assignmentQuery->where('school_year', $this->schoolYear);
+        }
+        $assignment = $assignmentQuery->first();
 
         if (empty($assignment)) {
             return redirect()->back()->withInput()->with('error', 'You are not assigned to the selected class section.');
@@ -344,6 +358,16 @@ class ExamDraftController extends BaseController
     }
 
     public function adminIndex()
+    {
+        return $this->reviewIndex();
+    }
+
+    public function principalIndex()
+    {
+        return $this->reviewIndex();
+    }
+
+    public function reviewIndex()
     {
         if ($this->reviewerIdColumn !== '') {
             $allDrafts = $this->examDraftModel
@@ -483,10 +507,23 @@ class ExamDraftController extends BaseController
             'visibleClasses' => $visibleClasses,
             'classDraftGroups' => $classDraftGroups,
             'newSubmissionClasses' => $newSubmissionClasses,
+            'reviewActionUrl' => base_url($this->reviewRoutePrefix() . '/exam-drafts/review'),
+            'legacyUploadUrl' => base_url($this->reviewRoutePrefix() . '/exam-drafts/upload-legacy'),
+            'reviewPortalLabel' => $this->reviewPortalLabel(),
         ]);
     }
 
     public function adminUploadLegacy()
+    {
+        return $this->reviewUploadLegacy();
+    }
+
+    public function principalUploadLegacy()
+    {
+        return $this->reviewUploadLegacy();
+    }
+
+    public function reviewUploadLegacy()
     {
         $adminId = (int) (session()->get('user_id') ?? 0);
         if ($adminId <= 0) {
@@ -567,13 +604,23 @@ class ExamDraftController extends BaseController
         }
 
         if ($saved > 0) {
-            return redirect()->to('/administrator/exam-drafts')->with('success', 'Old exam uploaded successfully.');
+            return redirect()->to($this->reviewDashboardPath())->with('success', 'Old exam uploaded successfully.');
         }
 
         return redirect()->back()->withInput()->with('error', 'Unable to save the old exam.');
     }
 
     public function adminReview()
+    {
+        return $this->reviewSubmission();
+    }
+
+    public function principalReview()
+    {
+        return $this->reviewSubmission();
+    }
+
+    public function reviewSubmission()
     {
         $draftId = (int) ($this->request->getPost('draft_id') ?? 0);
         if ($draftId <= 0) {
@@ -686,11 +733,6 @@ class ExamDraftController extends BaseController
             if ($this->hasAcceptanceTypeColumn) {
                 $newRow['acceptance_type'] = $status === 'accepted' ? $acceptanceType : null;
             }
-            $teacherFile = $this->draftTeacherFile($draft);
-            if (!empty($teacherFile)) {
-                $newRow[$this->authorFileColumn] = $teacherFile;
-                $newRow[$this->authorFilenameColumn] = $this->draftTeacherFilename($draft) ?? $teacherFile;
-            }
             if ($this->hasIsLegacyColumn && !empty($draft['is_legacy'])) {
                 $newRow['is_legacy'] = 1;
             }
@@ -707,16 +749,6 @@ class ExamDraftController extends BaseController
                 return redirect()->back()->with('success', 'Review saved successfully.');
             }
             return redirect()->back()->with('error', 'Unable to save the review.');
-        } elseif (strtolower($status) === 'accepted' && !empty($this->draftTeacherFile($draft))) {
-            $copied = $this->copyDraftToFinal($this->draftTeacherFile($draft));
-            if ($copied !== null) {
-                $update['final_file'] = $copied;
-                $update['final_filename'] = $this->draftTeacherFilename($draft) ?? $this->draftTeacherFile($draft);
-                $pdfName = $this->ensurePdfExists($copied, pathinfo($copied, PATHINFO_EXTENSION));
-                if ($pdfName !== null && $this->hasFinalPdfColumn) {
-                    $update['final_pdf_file'] = $pdfName;
-                }
-            }
         }
         if ($status === 'legacy') {
             $this->prepareLegacyPdfVersion($update, $draft);
@@ -763,15 +795,18 @@ class ExamDraftController extends BaseController
 
     public function teacherStatusFeed()
     {
+        $this->syncAcademicContext();
+
         $teacherId = (int) (session()->get('user_id') ?? 0);
         if ($teacherId <= 0) {
             return $this->response->setStatusCode(401);
         }
 
-        $drafts = $this->examDraftModel
-            ->select($this->draftSelectColumns())
-            ->select('id, status, acceptance_type, updated_at, reviewed_at')
-            ->where($this->authorIdColumn, $teacherId)
+        $assignments = $this->teacherClassModel->getClassAssignmentsByUserId($teacherId, $this->schoolYear);
+        $classSectionIds = array_map(static fn($a) => (int) $a['class_section_id'], $assignments);
+
+        $drafts = $this->visibleTeacherDraftsQuery($teacherId, $classSectionIds)
+            ->select('exam_drafts.id, exam_drafts.status, exam_drafts.acceptance_type, exam_drafts.updated_at, exam_drafts.reviewed_at')
             ->orderBy('updated_at', 'DESC')
             ->findAll();
 
@@ -817,6 +852,66 @@ class ExamDraftController extends BaseController
         return $validIds[0] ?? 0;
     }
 
+    private function visibleTeacherDraftsQuery(int $teacherId, array $classSectionIds)
+    {
+        $query = $this->examDraftModel
+            ->select($this->draftSelectColumns())
+            ->select('cs.class_section_name, u.firstname AS teacher_first, u.lastname AS teacher_last')
+            ->join('classSection cs', 'cs.class_section_id = exam_drafts.class_section_id', 'left')
+            ->join('users u', 'u.id = exam_drafts.' . $this->authorIdColumn, 'left');
+
+        $this->applyExamDraftYearScope($query);
+
+        if (empty($classSectionIds)) {
+            return $query->where('exam_drafts.' . $this->authorIdColumn, $teacherId);
+        }
+
+        $query->groupStart()
+            ->where('exam_drafts.' . $this->authorIdColumn, $teacherId)
+            ->orGroupStart()
+                ->whereIn('exam_drafts.class_section_id', $classSectionIds)
+                ->where('exam_drafts.' . $this->authorIdColumn . ' !=', $teacherId)
+                ->where('exam_drafts.status !=', 'draft');
+
+        $query->groupEnd()
+            ->groupEnd();
+
+        return $query;
+    }
+
+    private function syncAcademicContext(): void
+    {
+        $this->schoolYear = $this->currentSchoolYearName((string) ($this->configModel->getConfig('school_year') ?? ''));
+        $this->semester = (string) (getSemester() ?? '');
+    }
+
+    private function applyExamDraftYearScope($query): void
+    {
+        if ($this->schoolYear !== '') {
+            $query->where('exam_drafts.school_year', $this->schoolYear);
+        }
+    }
+
+    private function attachTeacherDraftContext(array $row, int $viewerId): array
+    {
+        $isOwn = $this->draftTeacherId($row) === $viewerId;
+        $row['is_own_submission'] = $isOwn;
+        $row['teacher_display_name'] = $isOwn ? 'You' : $this->draftTeacherName($row);
+
+        return $row;
+    }
+
+    private function draftTeacherName(array $draft): string
+    {
+        $name = trim(((string) ($draft['teacher_first'] ?? '')) . ' ' . ((string) ($draft['teacher_last'] ?? '')));
+        if ($name !== '') {
+            return $name;
+        }
+
+        $teacherId = $this->draftTeacherId($draft);
+        return $teacherId > 0 ? 'Teacher #' . $teacherId : 'Teacher';
+    }
+
     private function statusBadgeMap(): array
     {
         return [
@@ -953,7 +1048,7 @@ class ExamDraftController extends BaseController
                 . '<tr><td style="padding:4px 8px;"><strong>Status</strong></td><td style="padding:4px 8px;">' . esc((string) ($draft['status'] ?? 'submitted')) . '</td></tr>'
                 . '<tr><td style="padding:4px 8px;"><strong>Submitted at</strong></td><td style="padding:4px 8px;">' . esc((string) $submittedAt) . '</td></tr>'
                 . '</table>'
-                . '<p>Review drafts: <a href="' . esc(base_url('administrator/exam-drafts')) . '">Admin exam drafts</a></p>';
+                . '<p>Review drafts: <a href="' . esc(base_url($this->reviewRoutePrefix() . '/exam-drafts')) . '">' . esc($this->reviewPortalLabel()) . ' exam drafts</a></p>';
 
             $mailer = \Config\Services::emailService();
             $mailer->send($principalEmail, $subject, $body, 'notifications');
@@ -962,6 +1057,38 @@ class ExamDraftController extends BaseController
         }
     }
 
+    private function reviewDashboardPath(): string
+    {
+        return '/' . $this->reviewRoutePrefix() . '/exam-drafts';
+    }
+
+    private function reviewRoutePrefix(): string
+    {
+        return $this->isPrincipalReviewer() ? 'principal' : 'administrator';
+    }
+
+    private function reviewPortalLabel(): string
+    {
+        return $this->isPrincipalReviewer() ? 'Principal' : 'Administrator';
+    }
+
+    private function isPrincipalReviewer(): bool
+    {
+        $roles = session()->get('roles');
+        if (!is_array($roles)) {
+            $roles = $roles === null ? [] : [$roles];
+        }
+
+        foreach ($roles as $role) {
+            $normalized = strtolower(trim(str_replace([' ', '-'], '_', (string) $role)));
+            if ($normalized === 'principal') {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     private function nextDraftVersion(array $draft): int
     {
         $query = $this->examDraftModel
@@ -1316,6 +1443,11 @@ class ExamDraftController extends BaseController
         $base = pathinfo($sourcePath, PATHINFO_FILENAME);
         $targetPath = $targetDir . '/' . $base . '.pdf';
 
+        if (!function_exists('exec')) {
+            log_message('warning', 'ExamDraftController::convertDocToPdf skipped because exec() is unavailable.');
+            return is_file($targetPath) ? basename($targetPath) : null;
+        }
+
         // Attempt conversion via LibreOffice if available
         $cmd = 'soffice --headless --convert-to pdf --outdir ' . escapeshellarg($targetDir) . ' ' . escapeshellarg($sourcePath) . ' 2>/dev/null';
         @\exec($cmd);

app/Controllers/View/ExpenseController.php

@@ -2,6 +2,7 @@
 
 namespace App\Controllers\View;
 use App\Controllers\BaseController;
+use App\Libraries\FinancialAttachmentService;
 use App\Models\ExpenseModel;
 use App\Models\UserModel;
 use App\Models\ConfigurationModel;
@@ -12,6 +13,7 @@ class ExpenseController extends BaseController
     protected $expenseModel;
     protected $userModel;
     protected $configModel;
+    protected FinancialAttachmentService $financialAttachmentService;
     protected $schoolYear;
     protected $semester;
     protected $retailors;
@@ -21,9 +23,10 @@ class ExpenseController extends BaseController
         $this->expenseModel = new ExpenseModel();
         $this->userModel    = new UserModel();
         $this->configModel  = new ConfigurationModel();
+        $this->financialAttachmentService = new FinancialAttachmentService();
 
         $this->schoolYear = $this->configModel->getConfig('school_year');
-        $this->semester   = $this->configModel->getConfig('semester');
+        $this->semester   = getSemester();
 
         // Default list of common retailors; adjust as needed
         $this->retailors = [
@@ -93,6 +96,8 @@ class ExpenseController extends BaseController
 
     public function index()
     {
+        $schoolYear = (string) ($this->configModel->getConfig('school_year') ?? '');
+
         $expenses = $this->expenseModel
             ->select("
                 expenses.*,
@@ -101,6 +106,7 @@ class ExpenseController extends BaseController
             ")
             ->join('users u', 'u.id = expenses.purchased_by', 'left')
             ->join('users approver', 'approver.id = expenses.approved_by', 'left')
+            ->where('expenses.school_year', $schoolYear)
             ->orderBy('expenses.created_at', 'DESC')
             ->findAll();
 
@@ -112,7 +118,10 @@ class ExpenseController extends BaseController
             return $row;
         }, $expenses);
 
-        return view('expenses/index', ['expenses' => $expenses]);
+        return view('expenses/index', [
+            'expenses'   => $expenses,
+            'schoolYear' => $schoolYear,
+        ]);
     }
 
     public function create()
@@ -135,19 +144,19 @@ class ExpenseController extends BaseController
             // Optional extra fields
             'retailor'         => 'permit_empty|max_length[255]',
             'date_of_purchase' => 'permit_empty',
-            // allow JPG/JPEG/PNG/WEBP/GIF and PDF up to 2MB
+            // allow JPG/JPEG/PNG and PDF up to 2MB
             'receipt'      => 'uploaded[receipt]'
-                . '|max_size[receipt,2048]'
-                . '|ext_in[receipt,jpg,jpeg,png,webp,gif,pdf]'
-                . '|mime_in[receipt,image/jpg,image/jpeg,image/png,image/webp,image/gif,application/pdf]',
+                . '|max_size[receipt,5120]'
+                . '|ext_in[receipt,jpg,jpeg,png,pdf]'
+                . '|mime_in[receipt,image/jpg,image/jpeg,image/png,application/pdf]',
         ];
 
         $messages = [
             'receipt' => [
                 'uploaded' => 'Receipt file is required.',
-                'max_size' => 'Maximum file size is 2MB.',
-                'ext_in'   => 'Allowed formats: JPG, JPEG, PNG, WEBP, GIF, or PDF.',
-                'mime_in'  => 'Allowed formats: JPG, JPEG, PNG, WEBP, GIF, or PDF.',
+                'max_size' => 'Maximum file size is 5MB.',
+                'ext_in'   => 'Allowed formats: JPG, JPEG, PNG, or PDF.',
+                'mime_in'  => 'Allowed formats: JPG, JPEG, PNG, or PDF.',
             ]
         ];
 
@@ -170,24 +179,32 @@ class ExpenseController extends BaseController
         $purchasedById = (int) $purchasedById;
 
         // School context
-        $schoolYear = $this->schoolYear ?: date('Y');
+        $schoolYear = (string)$this->schoolYear;
+        if (!preg_match('/^\d{4}-\d{4}$/', $schoolYear)) {
+            return redirect()->back()->withInput()->with('error', 'Invalid school year configuration. Expected YYYY-YYYY.');
+        }
         $semester   = $this->semester ?: 'Fall';
 
-        // Handle upload: store under writable/uploads/receipts and save only the filename
-        $receiptName = null;
-        $file = $this->request->getFile('receipt');
-        if ($file && $file->isValid() && !$file->hasMoved()) {
-            $stored      = $file->store('receipts'); // -> writable/uploads/receipts/<randomname>.ext
-            $receiptName = basename($stored);
+        $stagedReceipt = null;
+        try {
+            $stagedReceipt = $this->financialAttachmentService->stageUploadedFile(
+                $this->request->getFile('receipt'),
+                'receipts'
+            );
+        } catch (\RuntimeException $e) {
+            return redirect()->back()->withInput()->with('error', $e->getMessage());
         }
 
         $status       = $isDonation ? 'approved' : 'pending';
         $statusReason = $isDonation ? 'Marked as Donation (non-reimbursable).' : null;
 
-        $this->expenseModel->insert([
+        $db = \Config\Database::connect();
+        $db->transBegin();
+        try {
+            $expenseId = (int)$this->expenseModel->insert([
             'category'     => $category,
             'amount'       => $amount,
-            'receipt_path' => $receiptName, // filename only
+            'receipt_path' => null,
             'description'  => $description,
             'retailor'     => ($retailor !== '') ? $retailor : null,
             'date_of_purchase' => ($datePurchase !== '') ? $datePurchase : null,
@@ -198,7 +215,33 @@ class ExpenseController extends BaseController
             'approved_by'  => $isDonation ? $userId : null,
             'school_year'  => $schoolYear,
             'semester'     => $semester,
-        ]);
+            ]);
+            if ($expenseId <= 0) {
+                throw new \RuntimeException('Expense insert failed.');
+            }
+            if ($db->transStatus() === false) {
+                throw new \RuntimeException('Expense transaction failed.');
+            }
+            $db->transCommit();
+        } catch (\Throwable $e) {
+            $db->transRollback();
+            $this->financialAttachmentService->discardStagedFile($stagedReceipt);
+            log_message('error', 'Expense creation failed: ' . $e->getMessage());
+            return redirect()->back()->withInput()->with('error', 'Expense could not be saved.');
+        }
+
+        if ($stagedReceipt !== null) {
+            try {
+                $receiptName = $this->financialAttachmentService->finalizeStagedFile($stagedReceipt);
+                if (!$this->expenseModel->update($expenseId, ['receipt_path' => $receiptName])) {
+                    throw new \RuntimeException('Expense receipt update failed.');
+                }
+            } catch (\Throwable $e) {
+                $this->financialAttachmentService->discardStagedFile($stagedReceipt);
+                log_message('critical', 'Expense receipt incomplete for expense #' . $expenseId . ': ' . $e->getMessage());
+                return redirect()->to('/expenses/index')->with('error', 'Expense saved, but receipt could not be finalized. Operations must review.');
+            }
+        }
 
         return redirect()->to('/expenses/index')->with('success', 'Record added successfully!');
     }
@@ -217,18 +260,37 @@ class ExpenseController extends BaseController
             return $this->response->setJSON(['error' => 'Invalid data']);
         }
 
-        $expense = $this->expenseModel->find($id);
-        if (!$expense) {
-            log_message('error', 'Expense not found for ID ' . $id);
-            return $this->response->setJSON(['error' => 'Expense not found']);
-        }
+        $db = \Config\Database::connect();
+        $db->transBegin();
+        try {
+            $expense = $db->query('SELECT * FROM expenses WHERE id = ? FOR UPDATE', [$id])->getRowArray();
+            if (!$expense) {
+                throw new \RuntimeException('Expense not found');
+            }
+            $this->assertSchoolYearNameWritable((string)($expense['school_year'] ?? ''));
+            $db->query(
+                "SELECT id FROM reimbursements WHERE expense_id = ? AND LOWER(status) NOT IN ('reversed','rejected','cancelled','canceled','voided') FOR UPDATE",
+                [$id]
+            )->getResultArray();
+            if ($this->hasActiveReimbursement($expense)) {
+                throw new \RuntimeException('Expense status cannot change after reimbursement without reversal.');
+            }
 
-        $success = $this->expenseModel->update($id, [
-            'status'        => $status,
-            'status_reason' => $reason,
-            'approved_by'   => $userId,
-            'updated_by'    => $userId
-        ]);
+            $success = $this->expenseModel->update($id, [
+                'status'        => $status === 'denied' ? 'rejected' : $status,
+                'status_reason' => $reason,
+                'approved_by'   => $status === 'approved' ? $userId : null,
+                'updated_by'    => $userId
+            ]);
+            if (!$success || $db->transStatus() === false) {
+                throw new \RuntimeException('Update failed');
+            }
+            $db->transCommit();
+        } catch (\Throwable $e) {
+            $db->transRollback();
+            log_message('error', 'Expense status update failed for ID ' . $id . ': ' . $e->getMessage());
+            return $this->response->setJSON(['error' => $e->getMessage()]);
+        }
 
         if (!$success) {
             log_message('error', 'Expense update failed for ID ' . $id);
@@ -260,6 +322,10 @@ class ExpenseController extends BaseController
             throw PageNotFoundException::forPageNotFound("Expense #$id not found");
         }
 
+        if ($this->hasActiveReimbursement($expense)) {
+            return redirect()->back()->with('error', 'Reimbursed expenses are immutable. Reverse the reimbursement and create a replacement expense.');
+        }
+
         // same user list you use in create()
         $users = $this->staffUsers();
 
@@ -279,6 +345,7 @@ class ExpenseController extends BaseController
         if (!$expense) {
             throw PageNotFoundException::forPageNotFound("Expense #$id not found");
         }
+        $this->assertSchoolYearNameWritable((string)($expense['school_year'] ?? ''));
 
         // Base rules
         $rules = [
@@ -308,14 +375,13 @@ class ExpenseController extends BaseController
         $isDonation = ($category === 'Donation');
         $userId     = (int) (session()->get('user_id') ?? 0);
 
-        // Keep old receipt unless replaced or removed
-        $receiptName = $expense['receipt_path'];
+        $stagedReceipt = null;
         if ($file && $file->isValid() && !$file->hasMoved() && ($file->getSize() ?? 0) > 0) {
-            $stored      = $file->store('receipts');
-            $receiptName = basename($stored);
-        }
-        if ($this->request->getPost('remove_receipt') === '1') {
-            $receiptName = null;
+            try {
+                $stagedReceipt = $this->financialAttachmentService->stageUploadedFile($file, 'receipts');
+            } catch (\RuntimeException $e) {
+                return redirect()->back()->withInput()->with('error', $e->getMessage());
+            }
         }
 
         $updateData = [
@@ -325,9 +391,11 @@ class ExpenseController extends BaseController
             'retailor'     => trim((string) $this->request->getPost('retailor')) ?: null,
             'date_of_purchase' => (string) $this->request->getPost('date_of_purchase') ?: null,
             'purchased_by' => $purchasedById,
-            'receipt_path' => $receiptName,
             'updated_by'   => $userId,
         ];
+        if ($this->request->getPost('remove_receipt') === '1') {
+            $updateData['receipt_path'] = null;
+        }
 
         if ($isDonation) {
             $updateData['status']           = 'approved';
@@ -335,14 +403,89 @@ class ExpenseController extends BaseController
             $updateData['approved_by']      = $userId ?: null;
             $updateData['reimbursement_id'] = null;
         } elseif (($expense['category'] ?? '') === 'Donation') {
-            // Moving a donation back to a reimbursable category: clear the marker.
+            // Moving a donation back to a reimbursable category must re-enter approval.
             $updateData['status_reason'] = null;
-            $updateData['approved_by']   = $expense['approved_by'] ?? null;
-            $updateData['status']        = $expense['status'] ?? 'pending';
+            $updateData['approved_by']   = null;
+            $updateData['status']        = 'pending';
         }
 
-        $this->expenseModel->update($id, $updateData);
+        $db = \Config\Database::connect();
+        $db->transBegin();
+        try {
+            $lockedExpense = $db->query('SELECT * FROM expenses WHERE id = ? FOR UPDATE', [$id])->getRowArray();
+            if (!$lockedExpense) {
+                throw new \RuntimeException('Expense not found.');
+            }
+            $activeReimbursements = $db->query(
+                "SELECT id FROM reimbursements WHERE expense_id = ? AND LOWER(status) NOT IN ('reversed','rejected','cancelled','canceled','voided') FOR UPDATE",
+                [$id]
+            )->getResultArray();
+            if ($activeReimbursements !== []) {
+                $protectedChanged = (
+                    (float)$lockedExpense['amount'] !== (float)$updateData['amount']
+                    || (string)$lockedExpense['category'] !== (string)$updateData['category']
+                    || (int)$lockedExpense['purchased_by'] !== (int)$updateData['purchased_by']
+                    || array_key_exists('receipt_path', $updateData)
+                );
+                if ($protectedChanged) {
+                    throw new \RuntimeException('Reimbursed expenses are immutable. Reverse the reimbursement and create a replacement expense.');
+                }
+            }
+
+            if (!$this->expenseModel->update($id, $updateData) || $db->transStatus() === false) {
+                throw new \RuntimeException('Expense update failed.');
+            }
+            $db->transCommit();
+        } catch (\Throwable $e) {
+            $db->transRollback();
+            $this->financialAttachmentService->discardStagedFile($stagedReceipt);
+            return redirect()->back()->withInput()->with('error', $e->getMessage());
+        }
+
+        if ($stagedReceipt !== null) {
+            try {
+                $receiptName = $this->financialAttachmentService->finalizeStagedFile($stagedReceipt);
+                if (!$this->expenseModel->update($id, ['receipt_path' => $receiptName])) {
+                    throw new \RuntimeException('Expense receipt update failed.');
+                }
+            } catch (\Throwable $e) {
+                $this->financialAttachmentService->discardStagedFile($stagedReceipt);
+                log_message('critical', 'Expense receipt replacement incomplete for expense #' . $id . ': ' . $e->getMessage());
+                return redirect()->to('/expenses/index')->with('error', 'Expense updated, but receipt could not be finalized. Operations must review.');
+            }
+        }
 
         return redirect()->to('/expenses/index')->with('success', 'Expense updated.');
     }
+
+    private function hasActiveReimbursement(array $expense): bool
+    {
+        $expenseId = (int) ($expense['id'] ?? 0);
+        if ($expenseId <= 0) {
+            return false;
+        }
+
+        if (!empty($expense['reimbursement_id'])) {
+            $row = \Config\Database::connect()
+                ->table('reimbursements')
+                ->select('id')
+                ->where('id', (int) $expense['reimbursement_id'])
+                ->where("LOWER(status) NOT IN ('reversed','rejected','cancelled','canceled','voided')", null, false)
+                ->get()
+                ->getRowArray();
+            if ($row) {
+                return true;
+            }
+        }
+
+        $row = \Config\Database::connect()
+            ->table('reimbursements')
+            ->select('id')
+            ->where('expense_id', $expenseId)
+            ->where("LOWER(status) NOT IN ('reversed','rejected','cancelled','canceled','voided')", null, false)
+            ->get()
+            ->getRowArray();
+
+        return $row !== null;
+    }
 }

app/Controllers/View/ExtraChargesController.php

@@ -3,6 +3,9 @@
 namespace App\Controllers\View;
 
 use App\Controllers\BaseController;
+use App\Libraries\FinancialStatus;
+use App\Libraries\InvoiceAdjustmentService;
+use App\Libraries\InvoiceLedgerService;
 use App\Models\AdditionalChargeModel;
 use CodeIgniter\Controller;
 use App\Models\UserModel;
@@ -28,6 +31,8 @@ class ExtraChargesController extends BaseController
     protected $studentClassModel;
     protected $enableAttendance;
     protected $attendanceDayModel;
+    protected $invoiceLedgerService;
+    protected InvoiceAdjustmentService $invoiceAdjustmentService;
 
     public function __construct()
     {
@@ -37,8 +42,10 @@ class ExtraChargesController extends BaseController
         $this->additionalChargeModel = new AdditionalChargeModel();
         $this->userModel = new UserModel();
         $this->invoiceModel = new InvoiceModel();
-        $this->semester = $this->configModel->getConfig('semester');
+        $this->semester = getSemester();
         $this->schoolYear = $this->configModel->getConfig('school_year');
+        $this->invoiceLedgerService = new InvoiceLedgerService();
+        $this->invoiceAdjustmentService = new InvoiceAdjustmentService($this->db);
     }
 
     public function index()
@@ -50,14 +57,29 @@ class ExtraChargesController extends BaseController
     /** Render HTML management page */
     public function page()
     {
+        $legacyTermKeys = ['school_year', 'schoolYear', 'year', 'semester'];
+        $query = $this->request->getGet();
+        $hasLegacyTermFilter = false;
+        foreach ($legacyTermKeys as $key) {
+            if (array_key_exists($key, $query)) {
+                unset($query[$key]);
+                $hasLegacyTermFilter = true;
+            }
+        }
+        if ($hasLegacyTermFilter) {
+            $target = site_url('admin/charges') . (!empty($query) ? '?' . http_build_query($query) : '');
+            return redirect()->to($target);
+        }
+
+        $schoolYearContext = $this->resolveSchoolYearContext();
+        $schoolYear = $schoolYearContext->yearName();
         $parentId   = (int)($this->request->getGet('parent_id') ?? 0);
         $status     = $this->request->getGet('status') ?: null;
-        $yearSelect = (string)($this->request->getGet('school_year') ?? $this->schoolYear);
 
         $rows = [];
         if ($parentId > 0) {
             $rows = $this->additionalChargeModel
-                ->byParentTerm($parentId, $this->schoolYear, $this->semester, $status);
+                ->byParentTerm($parentId, $schoolYear, $this->semester, $status);
         }
 
         // Load ALL parents for current view
@@ -81,7 +103,7 @@ class ExtraChargesController extends BaseController
         $parentIds = array_map(fn($r) => (int)$r['id'], $parents);
         $invoicesByParent = [];
         if (!empty($parentIds)) {
-            $all = $this->invoiceModel->getAllInvoicesByUserIds($parentIds, $yearSelect);
+            $all = $this->invoiceModel->getAllInvoicesByUserIds($parentIds, $schoolYear);
             foreach ($all as $inv) {
                 $pid = (int)$inv['parent_id'];
                 $invoicesByParent[$pid][] = [
@@ -103,7 +125,7 @@ class ExtraChargesController extends BaseController
 
         // ✅ Always pull all charges for the selected year & current semester (all parents)
         $rows   = $this->additionalChargeModel->listAllForTerm(
-            $yearSelect,
+            $schoolYear,
             $this->semester,
             $status,
             $q,
@@ -111,38 +133,6 @@ class ExtraChargesController extends BaseController
         );
         $pager  = $this->additionalChargeModel->pager;
 
-        // Build school year options from data (additional_charges + invoices)
-        $schoolYears = [];
-        try {
-            $q1 = $this->db->table('additional_charges')->select('DISTINCT school_year', false)
-                ->where('school_year IS NOT NULL', null, false)
-                ->orderBy('school_year', 'DESC')->get()->getResultArray();
-            foreach ($q1 as $r) {
-                $val = (string)($r['school_year'] ?? '');
-                if ($val !== '' && !in_array($val, $schoolYears, true)) $schoolYears[] = $val;
-            }
-        } catch (\Throwable $e) {}
-        try {
-            $q2 = $this->db->table('invoices')->select('DISTINCT school_year', false)
-                ->where('school_year IS NOT NULL', null, false)
-                ->orderBy('school_year', 'DESC')->get()->getResultArray();
-            foreach ($q2 as $r) {
-                $val = (string)($r['school_year'] ?? '');
-                if ($val !== '' && !in_array($val, $schoolYears, true)) $schoolYears[] = $val;
-            }
-        } catch (\Throwable $e) {}
-        if (empty($schoolYears) && is_string($this->schoolYear) && $this->schoolYear !== '') {
-            // fallback: generate recent years around configured schoolYear
-            $schoolYears[] = $this->schoolYear;
-            // Optionally add previous/next
-            [$start, $end] = explode('-', $this->schoolYear) + [0 => date('Y'), 1 => date('Y')+1];
-            $start = (int)$start;
-            for ($i = 1; $i <= 3; $i++) {
-                $schoolYears[] = ($start - $i) . '-' . (($start - $i) + 1);
-            }
-        }
-        rsort($schoolYears);
-
         return view('payment/extra_charges', [
             'q'          => $q,
             'pager'      => $pager,
@@ -153,9 +143,9 @@ class ExtraChargesController extends BaseController
             'parentId'            => $parentId,
             'selectedParentLabel' => $selectedParentLabel,
             'status'              => $status,
-            'schoolYear'          => $yearSelect,
-            'schoolYears'         => $schoolYears,
+            'schoolYear'          => $schoolYear,
             'semester'            => $this->semester,
+            'isSchoolYearReadonly' => $schoolYearContext->isReadonly(),
         ]);
     }
 
@@ -229,16 +219,19 @@ class ExtraChargesController extends BaseController
             if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => 'Charge not found', 'csrf_token' => csrf_token(), 'csrf_hash' => csrf_hash()]);
             return redirect()->back()->with('error', 'Charge not found.');
         }
+        if (($row['status'] ?? '') === FinancialStatus::ADDITIONAL_CHARGE_APPLIED) {
+            $message = 'Applied charges are immutable. Void and create an adjustment instead.';
+            if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => $message, 'csrf_token' => csrf_token(), 'csrf_hash' => csrf_hash()]);
+            return redirect()->back()->with('error', $message);
+        }
 
         $data = $this->request->getPost();
-        $newAmount = isset($data['amount']) ? (float)$data['amount'] : (float)$row['amount'];
-        $delta = $newAmount - (float)$row['amount'];
+        $newAmount = isset($data['amount']) ? round(abs((float)$data['amount']), 2) : round(abs((float)$row['amount']), 2);
 
         $db = \Config\Database::connect();
         $db->transStart();
 
-        // Update the charge first
-        $this->additionalChargeModel->update($id, [
+        $updated = $this->additionalChargeModel->update($id, [
             'title'       => trim($data['title'] ?? $row['title']),
             'description' => trim($data['description'] ?? $row['description']),
             'amount'      => $newAmount,
@@ -246,14 +239,15 @@ class ExtraChargesController extends BaseController
             'charge_type' => $data['charge_type'] ?? $row['charge_type'],
             // keep status as-is
         ]);
+        if (!$updated) {
+            $db->transRollback();
+            if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => 'Failed to update charge', 'csrf_token' => csrf_token(), 'csrf_hash' => csrf_hash()]);
+            return redirect()->back()->with('error', 'Failed to update charge.');
+        }
 
-        // If it’s already applied on an invoice and the amount changed, reflect the delta
-        if ($row['status'] === 'applied' && !empty($row['invoice_id']) && abs($delta) > 0.00001) {
-            if ($delta > 0) {
-                $this->invoiceModel->applyAdditionalCharge((int)$row['invoice_id'], $delta);
-            } else {
-                $this->invoiceModel->reverseAdditionalCharge((int)$row['invoice_id'], -$delta);
-            }
+        if (($row['status'] ?? '') === FinancialStatus::ADDITIONAL_CHARGE_APPLIED && !empty($row['invoice_id'])) {
+            $db->query('SELECT id FROM invoices WHERE id = ? FOR UPDATE', [(int) $row['invoice_id']]);
+            $this->invoiceLedgerService->recalculateInvoice((int) $row['invoice_id']);
         }
 
         $db->transComplete();
@@ -273,7 +267,7 @@ class ExtraChargesController extends BaseController
     public function invoicesForParent()
     {
         $parentId   = (int)($this->request->getGet('parent_id') ?? 0);
-        $schoolYear = (string)($this->request->getGet('school_year') ?? $this->schoolYear);
+        $schoolYear = $this->currentSchoolYearName((string)($this->schoolYear ?? ''));
 
         $rows = ($parentId > 0)
             ? ($this->invoiceModel->getInvoicesByUserId($parentId, $schoolYear) ?? [])
@@ -304,6 +298,9 @@ class ExtraChargesController extends BaseController
 
     public function store()
     {
+        $schoolYearContext = $this->resolveSchoolYearContext();
+        $this->assertSchoolYearWritable($schoolYearContext);
+        $schoolYear = $schoolYearContext->yearName();
         $data = $this->request->getPost();
 
         $rules = [
@@ -328,22 +325,30 @@ class ExtraChargesController extends BaseController
         }
 
         $invoiceId  = !empty($data['invoice_id']) ? (int)$data['invoice_id'] : null;
+        $invoice = null;
+        if ($invoiceId !== null) {
+            $invoice = $this->invoiceModel->find($invoiceId);
+            if (!$invoice) {
+                $msg = 'Invoice not found for charge.';
+                if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => $msg, 'csrf_token' => csrf_token(), 'csrf_hash' => csrf_hash()]);
+                return redirect()->back()->withInput()->with('error', $msg);
+            }
+        }
         $chargeType = (string)$data['charge_type'];
 
         $amountAbs    = round(abs((float)$data['amount']), 2);
-        $signedAmount = ($chargeType === 'add') ? $amountAbs : -$amountAbs;
 
         $payload = [
-            'parent_id'   => (int)$data['parent_id'], // ← users.id of the parent
+            'parent_id'   => $invoice ? (int)$invoice['parent_id'] : (int)$data['parent_id'],
             'invoice_id'  => $invoiceId,
-            'school_year' => $data['school_year'] ?? $this->schoolYear,
-            'semester'    => $data['semester']    ?? $this->semester,
+            'school_year' => $invoice ? (string)$invoice['school_year'] : $schoolYear,
+            'semester'    => $invoice ? (string)($invoice['semester'] ?? $this->semester) : (string)$this->semester,
             'charge_type' => $chargeType,
             'title'       => trim($data['title']),
             'description' => trim($data['description'] ?? ''),
-            'amount'      => $signedAmount,
+            'amount'      => $amountAbs,
             'due_date'    => !empty($data['due_date']) ? $data['due_date'] : null,
-            'status'      => $invoiceId ? 'applied' : 'pending',
+            'status'      => FinancialStatus::ADDITIONAL_CHARGE_PENDING,
             'created_by'  => (int)(session()->get('user_id') ?? 0),
             'created_at'  => \CodeIgniter\I18n\Time::now('UTC')->toDateTimeString(), // store UTC
         ];
@@ -351,30 +356,22 @@ class ExtraChargesController extends BaseController
         $this->db->transStart();
 
         // BEFORE
-        $invoiceBefore = $this->invoiceModel->getInvoicesByParentId($data['parent_id'], $this->schoolYear);
+        $invoiceBefore = $this->invoiceModel->getInvoicesByParentId($payload['parent_id'], $payload['school_year']);
 
         // Insert charge
-        $this->additionalChargeModel->insert($payload);
-        $chargeId = (int)$this->additionalChargeModel->getInsertID();
-
-        // Apply to invoice if present
-        if ($invoiceId) {
-            try {
-                if ($chargeType === 'add') {
-                    $this->invoiceModel->applyAdditionalCharge($invoiceId, $amountAbs);
-                } else {
-                    $this->invoiceModel->deductAdditionalCharge($invoiceId, $amountAbs);
-                }
-            } catch (\Throwable $e) {
-                log_message('error', 'apply/deductAdditionalCharge failed: ' . $e->getMessage());
-            }
+        $chargeId = (int)$this->additionalChargeModel->insert($payload);
+        if ($chargeId <= 0) {
+            $this->db->transRollback();
+            $msg = 'Failed to save charge.';
+            if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => $msg, 'csrf_token' => csrf_token(), 'csrf_hash' => csrf_hash()]);
+            return redirect()->back()->withInput()->with('error', $msg);
         }
 
         // AFTER
-        $invoiceAfter = $this->invoiceModel->getInvoicesByParentId($data['parent_id'], $this->schoolYear);
+        $invoiceAfter = $this->invoiceModel->getInvoicesByParentId($payload['parent_id'], $payload['school_year']);
 
         // Parent USER (not parent table)
-        $parentUser = $this->userModel->getUserInfoById($data['parent_id']);
+        $parentUser = $this->userModel->getUserInfoById($payload['parent_id']);
 
         $this->db->transComplete();
 
@@ -421,7 +418,7 @@ class ExtraChargesController extends BaseController
             'charge_title'   => $payload['title'],
             'charge_desc'    => $payload['description'],
             'charge_type'    => $payload['charge_type'],     // add|deduct
-            'amount_signed'  => $signedAmount,
+            'amount_signed'  => $chargeType === 'add' ? $amountAbs : -$amountAbs,
             'amount_abs'     => $amountAbs,
             'due_date'       => $payload['due_date'],
             'created_at'     => $payload['created_at'],
@@ -444,7 +441,7 @@ class ExtraChargesController extends BaseController
                 'ok'          => true,
                 'id'          => $chargeId,
                 'invoice_id'  => $invoiceId,
-                'parent_id'   => (int)$data['parent_id'],
+                'parent_id'   => $payload['parent_id'],
                 'csrf_token'  => csrf_token(),
                 'csrf_hash'   => csrf_hash(),
             ]);
@@ -452,6 +449,61 @@ class ExtraChargesController extends BaseController
         return redirect()->to(site_url('admin/charges'))->with('status', 'Charge recorded.');
     }
 
+    public function approve($id)
+    {
+        $row = $this->additionalChargeModel->find((int)$id);
+        if (!$row) {
+            if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => 'Charge not found']);
+            return redirect()->back()->with('error', 'Charge not found.');
+        }
+        if (($row['status'] ?? '') !== FinancialStatus::ADDITIONAL_CHARGE_PENDING) {
+            if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => 'Only pending charges can be approved']);
+            return redirect()->back()->with('error', 'Only pending charges can be approved.');
+        }
+
+        if (!$this->additionalChargeModel->update((int)$id, ['status' => FinancialStatus::ADDITIONAL_CHARGE_APPROVED])) {
+            if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => 'Failed to approve charge']);
+            return redirect()->back()->with('error', 'Failed to approve charge.');
+        }
+
+        if ($this->wantsJson()) return $this->response->setJSON(['ok' => true]);
+        return redirect()->back()->with('status', 'Charge approved.');
+    }
+
+    public function apply($id)
+    {
+        $row = $this->additionalChargeModel->find((int)$id);
+        if (!$row) {
+            if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => 'Charge not found']);
+            return redirect()->back()->with('error', 'Charge not found.');
+        }
+        if ((string)($row['status'] ?? '') !== FinancialStatus::ADDITIONAL_CHARGE_APPROVED) {
+            if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => 'Only approved charges can be applied']);
+            return redirect()->back()->with('error', 'Only approved charges can be applied.');
+        }
+
+        $invoiceId = (int)($row['invoice_id'] ?? 0);
+        if ($invoiceId <= 0) {
+            if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => 'Charge must reference an invoice before application']);
+            return redirect()->back()->with('error', 'Charge must reference an invoice before application.');
+        }
+
+        try {
+            $this->invoiceAdjustmentService->applyAdditionalCharge(
+                (int)$id,
+                $invoiceId,
+                (int)(session()->get('user_id') ?? 0)
+            );
+        } catch (\Throwable $e) {
+            log_message('error', 'Additional charge apply failed: ' . $e->getMessage());
+            if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => $e->getMessage()]);
+            return redirect()->back()->with('error', $e->getMessage());
+        }
+
+        if ($this->wantsJson()) return $this->response->setJSON(['ok' => true]);
+        return redirect()->back()->with('status', 'Charge applied.');
+    }
+
     /**
      * Mark a charge as void and roll back its impact on the invoice if applied.
      */
@@ -463,35 +515,36 @@ class ExtraChargesController extends BaseController
             return redirect()->back()->with('error', 'Charge not found.');
         }
 
-        $invoiceId  = (int)($row['invoice_id'] ?? 0);
-        $amountAbs  = round(abs((float)($row['amount'] ?? 0)), 2);
-        $chargeType = (string)($row['charge_type'] ?? 'add');
         $status     = (string)($row['status'] ?? 'pending');
+        $reason     = trim((string)($this->request->getPost('reason') ?? 'Voided by staff'));
 
-        $this->db->transStart();
-
-        if ($status === 'applied' && $invoiceId > 0 && $amountAbs > 0) {
-            try {
-                if ($chargeType === 'add') {
-                    $this->invoiceModel->reverseAdditionalCharge($invoiceId, $amountAbs);
-                } else {
-                    // voiding a deduction -> add back
-                    $this->invoiceModel->applyAdditionalCharge($invoiceId, $amountAbs);
+        try {
+            if ($status === FinancialStatus::ADDITIONAL_CHARGE_APPLIED) {
+                $this->invoiceAdjustmentService->reverseAdditionalCharge(
+                    (int)$id,
+                    $reason,
+                    (int)(session()->get('user_id') ?? 0)
+                );
+            } else {
+                $this->db->transBegin();
+                $this->additionalChargeModel->update((int)$id, [
+                    'status' => FinancialStatus::ADDITIONAL_CHARGE_VOIDED,
+                    'voided_by' => (int)(session()->get('user_id') ?? 0) ?: null,
+                    'voided_at' => utc_now(),
+                    'void_reason' => $reason,
+                ]);
+                if (!$this->db->transStatus()) {
+                    throw new \RuntimeException('Failed to void charge.');
                 }
-            } catch (\Throwable $e) {
-                log_message('error', 'void(): invoice adjust failed: ' . $e->getMessage());
+                $this->db->transCommit();
             }
-        }
-
-        $this->additionalChargeModel->update((int)$id, [
-            'status' => 'void',
-        ]);
-
-        $this->db->transComplete();
-
-        if (!$this->db->transStatus()) {
-            if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => 'Failed to void charge']);
-            return redirect()->back()->with('error', 'Failed to void charge.');
+        } catch (\Throwable $e) {
+            if ($this->db->transStatus() === false) {
+                $this->db->transRollback();
+            }
+            log_message('error', 'Additional charge void failed: ' . $e->getMessage());
+            if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => $e->getMessage()]);
+            return redirect()->back()->with('error', $e->getMessage());
         }
 
         if ($this->wantsJson()) return $this->response->setJSON(['ok' => true]);
@@ -499,7 +552,7 @@ class ExtraChargesController extends BaseController
     }
 
     /**
-     * Reverse a previously applied charge: undo invoice impact and return to pending state.
+     * Reverse a previously applied charge with an immutable reversing invoice line.
      */
     public function reverse($id)
     {
@@ -510,47 +563,35 @@ class ExtraChargesController extends BaseController
         }
 
         $invoiceId  = (int)($row['invoice_id'] ?? 0);
-        $amountAbs  = round(abs((float)($row['amount'] ?? 0)), 2);
-        $chargeType = (string)($row['charge_type'] ?? 'add');
         $status     = (string)($row['status'] ?? 'pending');
 
-        if ($status !== 'applied' || $invoiceId <= 0 || $amountAbs <= 0) {
+        if ($status !== FinancialStatus::ADDITIONAL_CHARGE_APPLIED || $invoiceId <= 0) {
             if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => 'Nothing to reverse']);
             return redirect()->back()->with('error', 'Nothing to reverse.');
         }
 
-        $this->db->transStart();
+        $reason = trim((string)($this->request->getPost('reason') ?? 'Reversed by staff'));
         try {
-            if ($chargeType === 'add') {
-                $this->invoiceModel->reverseAdditionalCharge($invoiceId, $amountAbs);
-            } else {
-                $this->invoiceModel->applyAdditionalCharge($invoiceId, $amountAbs);
-            }
+            $this->invoiceAdjustmentService->reverseAdditionalCharge(
+                (int)$id,
+                $reason,
+                (int)(session()->get('user_id') ?? 0)
+            );
         } catch (\Throwable $e) {
-            log_message('error', 'reverse(): invoice adjust failed: ' . $e->getMessage());
-        }
-
-        $this->additionalChargeModel->update((int)$id, [
-            'status'     => 'pending',
-            'invoice_id' => null,
-        ]);
-
-        $this->db->transComplete();
-
-        if (!$this->db->transStatus()) {
-            if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => 'Failed to reverse charge']);
-            return redirect()->back()->with('error', 'Failed to reverse charge.');
+            log_message('error', 'Additional charge reverse failed: ' . $e->getMessage());
+            if ($this->wantsJson()) return $this->response->setJSON(['ok' => false, 'error' => $e->getMessage()]);
+            return redirect()->back()->with('error', $e->getMessage());
         }
 
         if ($this->wantsJson()) return $this->response->setJSON(['ok' => true]);
-        return redirect()->back()->with('status', 'Charge reversed to pending.');
+        return redirect()->back()->with('status', 'Charge reversed.');
     }
 
     /** JSON: list charges for the current term (with optional filters). */
     public function apiList()
     {
-        $year   = (string)($this->request->getGet('school_year') ?? $this->schoolYear);
-        $sem    = (string)($this->request->getGet('semester')    ?? $this->semester);
+        $year   = $this->currentSchoolYearName((string)($this->schoolYear ?? ''));
+        $sem    = (string)$this->semester;
         $status = $this->request->getGet('status') ?: null;
         $q      = trim((string)($this->request->getGet('q') ?? '')) ?: null;
         $per    = (int)($this->request->getGet('per_page') ?? 50);

app/Controllers/View/FamilyAdminController.php

@@ -150,10 +150,12 @@ class FamilyAdminController extends BaseController
                     }
 
                     // Recent payments (limit 10)
-                    $payRows = $db->table('payments')
-                        ->select('id, parent_id, invoice_id, paid_amount, balance, payment_method, payment_date, status')
-                        ->whereIn('parent_id', $parentIds)
-                        ->orderBy('payment_date', 'DESC')
+                    $payRows = $db->table('payments p')
+                        ->select('p.id, p.parent_id, p.invoice_id, p.paid_amount, p.payment_method, p.payment_date, p.status AS payment_status, p.installment_seq, p.number_of_installments, i.invoice_number, i.balance AS invoice_current_balance, i.status AS invoice_status, i.school_year')
+                        ->join('invoices i', 'i.id = p.invoice_id', 'inner')
+                        ->whereIn('p.parent_id', $parentIds)
+                        ->orderBy('p.payment_date', 'DESC')
+                        ->orderBy('p.id', 'DESC')
                         ->limit(10)
                         ->get()->getResultArray();
                     $fam['payments'] = $payRows;
@@ -252,7 +254,41 @@ class FamilyAdminController extends BaseController
                       LIMIT 1",
                     [$studentId]
                 )->getRowArray();
-                if (!empty($row['id'])) $familyId = (int) $row['id'];
+                if (!empty($row['id'])) {
+                    $familyId = (int) $row['id'];
+                } else {
+                    // Legacy/newly-created students can have students.parent_id set
+                    // before the normalized family_students row is created.
+                    $row = $db->query(
+                        "SELECT f.id
+                           FROM students s
+                           JOIN family_guardians fg ON fg.user_id = s.parent_id
+                           JOIN families f ON f.id = fg.family_id
+                          WHERE s.id = ?
+                          ORDER BY fg.is_primary DESC, f.household_name
+                          LIMIT 1",
+                        [$studentId]
+                    )->getRowArray();
+
+                    if (!empty($row['id'])) {
+                        $familyId = (int) $row['id'];
+                    } else {
+                        $row = $db->query(
+                            "SELECT f.id
+                               FROM students s
+                               JOIN families f ON f.family_code = CONCAT('FAM-', s.parent_id)
+                              WHERE s.id = ?
+                                AND s.parent_id IS NOT NULL
+                              ORDER BY f.household_name
+                              LIMIT 1",
+                            [$studentId]
+                        )->getRowArray();
+
+                        if (!empty($row['id'])) {
+                            $familyId = (int) $row['id'];
+                        }
+                    }
+                }
             } elseif ($guardianId) {
                 // 1) Try via guardians link
                 $row = $db->query(
@@ -328,6 +364,24 @@ class FamilyAdminController extends BaseController
               ORDER BY s.lastname, s.firstname",
             [$familyId]
         )->getResultArray();
+
+        if ($studentId > 0) {
+            $studentIds = array_map(static fn(array $row): int => (int) ($row['id'] ?? 0), $studentsRows);
+            if (!in_array($studentId, $studentIds, true)) {
+                $selectedStudent = $db->query(
+                    "SELECT id, firstname, lastname
+                       FROM students
+                      WHERE id = ?
+                      LIMIT 1",
+                    [$studentId]
+                )->getRowArray();
+
+                if ($selectedStudent) {
+                    $studentsRows[] = $selectedStudent;
+                }
+            }
+        }
+
         if (!empty($studentsRows)) {
             foreach ($studentsRows as &$sr) {
                 $sid = (int) ($sr['id'] ?? 0);
@@ -359,7 +413,7 @@ class FamilyAdminController extends BaseController
                 if ($gid > 0) $gmap[$gid] = trim(($g['firstname'] ?? '') . ' ' . ($g['lastname'] ?? ''));
             }
             $ecRows = $db->table('emergency_contacts')
-                ->select('id, parent_id, emergency_contact_name, relation, cellphone, email, school_year, semester, created_at, updated_at')
+                ->select('id, parent_id, emergency_contact_name, relation, cellphone, email, created_at, updated_at')
                 ->whereIn('parent_id', $parentIds)
                 ->orderBy('updated_at', 'DESC')
                 ->get()->getResultArray();
@@ -395,10 +449,12 @@ class FamilyAdminController extends BaseController
             }
 
             // Payments
-            $payRows = $db->table('payments')
-                ->select('id, parent_id, invoice_id, paid_amount, balance, payment_method, payment_date, status')
-                ->whereIn('parent_id', $parentIds)
-                ->orderBy('payment_date', 'DESC')
+            $payRows = $db->table('payments p')
+                ->select('p.id, p.parent_id, p.invoice_id, p.paid_amount, p.payment_method, p.payment_date, p.status AS payment_status, p.installment_seq, p.number_of_installments, i.invoice_number, i.balance AS invoice_current_balance, i.status AS invoice_status, i.school_year')
+                ->join('invoices i', 'i.id = p.invoice_id', 'inner')
+                ->whereIn('p.parent_id', $parentIds)
+                ->orderBy('p.payment_date', 'DESC')
+                ->orderBy('p.id', 'DESC')
                 ->limit(10)
                 ->get()->getResultArray();
             $family['payments'] = $payRows;

app/Controllers/View/FilesController.php

@@ -4,7 +4,6 @@ namespace App\Controllers\View;
 
 use CodeIgniter\Controller;
 use CodeIgniter\Exceptions\PageNotFoundException;
-use Config\Database;
 
 class FilesController extends Controller
 {
@@ -22,7 +21,11 @@ class FilesController extends Controller
             throw PageNotFoundException::forPageNotFound();
         }
 
-        // 3) Build path under writable
+        $expense = $this->expenseRecordForFile($name);
+        if ($expense === null || !$this->canViewExpenseFile($expense)) {
+            return $this->response->setStatusCode(403, 'You are not allowed to access this file.');
+        }
+
         $path = WRITEPATH . 'uploads/receipts/' . $name;
         if (!is_file($path)) {
             throw PageNotFoundException::forPageNotFound();
@@ -79,7 +82,11 @@ class FilesController extends Controller
             throw \CodeIgniter\Exceptions\PageNotFoundException::forPageNotFound();
         }
 
-        // 3) Build path under writable (REIMBURSEMENTS)
+        $reimbursement = $this->reimbursementRecordForFile($name);
+        if ($reimbursement === null || !$this->canViewReimbursementFile($reimbursement)) {
+            return $this->response->setStatusCode(403, 'You are not allowed to access this file.');
+        }
+
         $path = WRITEPATH . 'uploads/reimbursements/' . $name;
         if (!is_file($path)) {
             throw \CodeIgniter\Exceptions\PageNotFoundException::forPageNotFound();
@@ -145,6 +152,10 @@ class FilesController extends Controller
             throw PageNotFoundException::forPageNotFound();
         }
 
+        if (! $this->canViewEarlyDismissalSignature($name)) {
+            return $this->response->setStatusCode(403, 'You are not allowed to access this file.');
+        }
+
         // 3) Build path under writable (EARLY DISMISSAL SIGNATURES)
         $path = WRITEPATH . 'uploads/early_dismissal_signatures/' . $name;
         if (!is_file($path)) {
@@ -193,7 +204,7 @@ class FilesController extends Controller
             ->setHeader('Content-Length', (string) $size)
             ->setHeader('ETag', $etag)
             ->setHeader('Last-Modified', gmdate('D, d M Y H:i:s', $mtime) . ' GMT')
-            ->setHeader('Cache-Control', 'public, max-age=86400')
+            ->setHeader('Cache-Control', 'private, no-store')
             ->setBody(file_get_contents($path));
     }
 
@@ -224,6 +235,10 @@ class FilesController extends Controller
             throw PageNotFoundException::forPageNotFound();
         }
 
+        if (!$this->canAccessExamDraftFile($name, $subdir)) {
+            return $this->response->setStatusCode(403, 'You are not allowed to access this file.');
+        }
+
         $mime = 'application/octet-stream';
         if (function_exists('finfo_open')) {
             $fi = finfo_open(FILEINFO_MIME_TYPE);
@@ -317,4 +332,202 @@ class FilesController extends Controller
         }
         return 'teacher_file';
     }
+
+    private function resolveExamDraftAuthorIdColumn($db): string
+    {
+        try {
+            $fields = $db->getFieldNames('exam_drafts');
+            if (in_array('teacher_id', $fields, true)) {
+                return 'teacher_id';
+            }
+            if (in_array('author_id', $fields, true)) {
+                return 'author_id';
+            }
+        } catch (\Throwable $e) {
+            log_message('error', 'FilesController::resolveExamDraftAuthorIdColumn error: ' . $e->getMessage());
+        }
+
+        return 'teacher_id';
+    }
+
+    private function canAccessExamDraftFile(string $filename, string $subdir): bool
+    {
+        $userId = (int) (session()->get('user_id') ?? 0);
+        if ($userId <= 0) {
+            return false;
+        }
+
+        $role = strtolower((string) (session()->get('role') ?? ''));
+        if (in_array($role, ['admin', 'administrator', 'principal'], true)) {
+            return true;
+        }
+
+        $db = Database::connect();
+        $fileColumn = $subdir === 'finals' ? 'final_file' : $this->resolveExamDraftFileColumn($db);
+        $authorIdColumn = $this->resolveExamDraftAuthorIdColumn($db);
+
+        $draft = $db->table('exam_drafts ed')
+            ->select('ed.class_section_id, ed.school_year, ed.semester, ed.status, ed.' . $authorIdColumn . ' AS draft_author_id')
+            ->where('ed.' . $fileColumn, $filename)
+            ->limit(1)
+            ->get()
+            ->getRowArray();
+
+        if (empty($draft)) {
+            return false;
+        }
+
+        $authorId = (int) ($draft['draft_author_id'] ?? 0);
+        if ($authorId > 0 && $authorId === $userId) {
+            return true;
+        }
+
+        $classSectionId = (int) ($draft['class_section_id'] ?? 0);
+        if ($classSectionId <= 0) {
+            return false;
+        }
+
+        $status = strtolower(trim((string) ($draft['status'] ?? '')));
+        if ($subdir === 'drafts' && $status === 'draft') {
+            return false;
+        }
+
+        $currentSchoolYear = trim((string) (session()->get('school_year') ?? ''));
+        $currentSemester = trim((string) (session()->get('semester') ?? ''));
+        $draftSchoolYear = trim((string) ($draft['school_year'] ?? ''));
+        $draftSemester = trim((string) ($draft['semester'] ?? ''));
+
+        $hasCurrentAssignment = $db->table('teacher_class')
+            ->select('id')
+            ->where('teacher_id', $userId)
+            ->where('class_section_id', $classSectionId);
+
+        if ($currentSchoolYear !== '') {
+            $hasCurrentAssignment->where('school_year', $currentSchoolYear);
+        }
+
+        $hasCurrentAssignment = $hasCurrentAssignment->limit(1)->countAllResults() > 0;
+
+        if ($hasCurrentAssignment) {
+            if ($subdir === 'finals') {
+                return true;
+            }
+
+            return $draftSchoolYear === '' || $currentSchoolYear === '' || $draftSchoolYear === $currentSchoolYear;
+        }
+
+        $assignmentQuery = $db->table('teacher_class')
+            ->select('id')
+            ->where('teacher_id', $userId)
+            ->where('class_section_id', $classSectionId);
+
+        if ($draftSchoolYear !== '') {
+            $assignmentQuery->where('school_year', $draftSchoolYear);
+        }
+
+        $hasDraftYearAssignment = $assignmentQuery->limit(1)->countAllResults() > 0;
+        if (!$hasDraftYearAssignment) {
+            return false;
+        }
+
+        if ($subdir === 'finals') {
+            return true;
+        }
+
+        return $draftSemester === '' || $currentSemester === '' || $draftSemester === $currentSemester;
+    }
+
+    private function canViewEarlyDismissalSignature(string $name): bool
+    {
+        $userId = (int) (session()->get('user_id') ?? 0);
+        if ($userId <= 0) {
+            return false;
+        }
+
+        $roles = array_map('strtolower', (array) (session()->get('roles') ?? []));
+        $activeRole = strtolower((string) (session()->get('role') ?? ''));
+        if ($activeRole !== '' && ! in_array($activeRole, $roles, true)) {
+            $roles[] = $activeRole;
+        }
+
+        foreach (['administrator', 'administrative staff', 'principal', 'admin', 'teacher', 'teacher_assistant'] as $role) {
+            if (in_array($role, $roles, true)) {
+                return true;
+            }
+        }
+
+        $row = \Config\Database::connect()
+            ->table('early_dismissal_signatures')
+            ->select('uploaded_by')
+            ->where('filename', $name)
+            ->get()
+            ->getRowArray();
+
+        return $row !== null && (int) ($row['uploaded_by'] ?? 0) === $userId;
+    }
+
+    private function expenseRecordForFile(string $name): ?array
+    {
+        return \Config\Database::connect()
+            ->table('expenses')
+            ->where('receipt_path', $name)
+            ->get()
+            ->getRowArray();
+    }
+
+    private function reimbursementRecordForFile(string $name): ?array
+    {
+        return \Config\Database::connect()
+            ->table('reimbursements')
+            ->where('receipt_path', $name)
+            ->get()
+            ->getRowArray();
+    }
+
+    private function canViewExpenseFile(array $expense): bool
+    {
+        if ($this->hasFinancialStaffAccess()) {
+            return true;
+        }
+
+        $userId = (int) (session()->get('user_id') ?? 0);
+
+        return $userId > 0 && in_array($userId, [
+            (int) ($expense['purchased_by'] ?? 0),
+            (int) ($expense['added_by'] ?? 0),
+            (int) ($expense['approved_by'] ?? 0),
+        ], true);
+    }
+
+    private function canViewReimbursementFile(array $reimbursement): bool
+    {
+        if ($this->hasFinancialStaffAccess()) {
+            return true;
+        }
+
+        $userId = (int) (session()->get('user_id') ?? 0);
+
+        return $userId > 0 && in_array($userId, [
+            (int) ($reimbursement['reimbursed_to'] ?? 0),
+            (int) ($reimbursement['approved_by'] ?? 0),
+            (int) ($reimbursement['added_by'] ?? 0),
+        ], true);
+    }
+
+    private function hasFinancialStaffAccess(): bool
+    {
+        $roles = array_map('strtolower', (array) (session()->get('roles') ?? []));
+        $activeRole = strtolower((string) (session()->get('role') ?? ''));
+        if ($activeRole !== '' && !in_array($activeRole, $roles, true)) {
+            $roles[] = $activeRole;
+        }
+
+        foreach (['administrator', 'administrative staff', 'principal', 'teacher', 'teacher_assistant'] as $role) {
+            if (in_array($role, $roles, true)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
 }

app/Controllers/View/FinalController.php

@@ -27,7 +27,7 @@ class FinalController extends BaseController
         $this->studentModel = new StudentModel();
         $this->teacherClassModel = new TeacherClassModel();
         $this->schoolYear = $this->configModel->getConfig('school_year');
-        $this->semester = $this->configModel->getConfig('semester');
+        $this->semester = getSemester();
         $this->gradingLockModel = new GradingLockModel();
         $this->missingScoreOverrideModel = new MissingScoreOverrideModel();
     }
@@ -131,6 +131,7 @@ class FinalController extends BaseController
             )
             ->join('(' . $latestFinalSub . ') fl', 'fl.student_id = s.id', 'left', false)
             ->join('final_exam fe', 'fe.id = fl.max_id', 'left')
+            ->where('s.is_active', 1)
             ->orderBy('s.lastname', 'ASC')
             ->orderBy('s.firstname', 'ASC');
 

app/Controllers/View/FlagController.php

@@ -24,6 +24,13 @@ class FlagController extends Controller
         helper(['url', 'form']);
     }
 
+    private function assertSchoolYearNameWritable(string $schoolYear): void
+    {
+        service('schoolYearWriteGuard')->assertWritable(
+            service('schoolYearContext')->forYearName($schoolYear)
+        );
+    }
+
     public function index()
     {
         $currentFlagModel = new CurrentFlagModel();
@@ -35,8 +42,11 @@ class FlagController extends Controller
         $grades = [];
 
         // Retrieve flags and class sections that currently have active students
-        $flags = $currentFlagModel->findAll();
         $schoolYear = $configModel->getConfig('school_year');
+        if ((string)$schoolYear !== '' && $this->db->fieldExists('school_year', 'current_flag')) {
+            $currentFlagModel->where('school_year', (string)$schoolYear);
+        }
+        $flags = $currentFlagModel->findAll();
         $studentCounts = $studentClassModel->getStudentCountsBySection($schoolYear);
         $classSections = [];
 
@@ -357,7 +367,7 @@ class FlagController extends Controller
         $userId = session()->get('user_id');
 
         // Get the semester and school year from configuration
-        $semester = $configModel->getConfig('semester');
+        $semester = getSemester();
         $schoolYear = $configModel->getConfig('school_year');
 
         // Set the current system date and time for flag_datetime
@@ -433,6 +443,13 @@ class FlagController extends Controller
             return $this->index();
         }
 
+        $flagData = $currentFlagModel->find($id);
+        if (!$flagData) {
+            session()->setFlashdata('error', 'Incident not found.');
+            return $this->index();
+        }
+        $this->assertSchoolYearNameWritable((string)($flagData['school_year'] ?? ''));
+
         $update = ['flag_state' => $newState];
         if ($newState === 'Closed') {
             $update['updated_by_closed'] = $userId;
@@ -487,6 +504,7 @@ class FlagController extends Controller
             session()->setFlashdata('error', 'Incident not found.');
             return redirect()->back();
         }
+        $this->assertSchoolYearNameWritable((string)($flagData['school_year'] ?? ''));
 
         // Proceed only if flag is not closed
         if ($flagData['flag_state'] !== 'Closed') {
@@ -534,6 +552,7 @@ class FlagController extends Controller
             session()->setFlashdata('error', 'Incident not found.');
             return redirect()->back();
         }
+        $this->assertSchoolYearNameWritable((string)($flagData['school_year'] ?? ''));
 
         // Check if the flag is not already canceled
         if ($flagData['flag_state'] !== 'Canceled') {

app/Controllers/View/HealthController.php

@@ -10,7 +10,6 @@ class HealthController extends Controller
     {
         return [
             'label'    => $label,
-            'path'     => $path,
             'exists'   => is_dir($path),
             'writable' => is_writable($path),
         ];
@@ -65,7 +64,6 @@ class HealthController extends Controller
             'ok'          => $ok,
             'paths'       => $pathsStatus,
             'database'    => $dbChecks,
-            'write_path'  => WRITEPATH,
             'timestamp'   => date('c'),
         ];
 

app/Controllers/View/HomeworkController.php

@@ -5,7 +5,7 @@ namespace App\Controllers\View;
 use App\Models\HomeworkModel;
 use App\Models\StudentModel;
 use App\Models\StudentClassModel;
-use CodeIgniter\Controller;
+use App\Controllers\BaseController;
 use App\Models\TeacherClassModel;
 use App\Models\ConfigurationModel;
 use App\Models\UserModel;
@@ -16,7 +16,7 @@ use App\Controllers\View\GradingController;
 use App\Models\GradingLockModel;
 use App\Models\MissingScoreOverrideModel;
 
-class HomeworkController extends Controller
+class HomeworkController extends BaseController
 {
     protected $db;
     protected $semesterScoreService;
@@ -42,7 +42,7 @@ class HomeworkController extends Controller
         $this->configModel = new ConfigurationModel();
 
         $this->schoolYear = $this->configModel->getConfig('school_year');
-        $this->semester = $this->configModel->getConfig('semester');
+        $this->semester = getSemester();
 
         // Log the service initialization
         log_message('debug', 'Initializing SemesterScoreService');
@@ -59,11 +59,12 @@ class HomeworkController extends Controller
         }
     }
 
-    public function updateHomeworkScores(array $scores = null, int $updatedBy = null, int $classSectionId = null)
+    public function updateHomeworkScores(?array $scores = null, ?int $updatedBy = null, ?int $classSectionId = null)
     {
         $scores = $this->request->getPost('scores');
         $semester = $this->request->getPost('semester') ?? $this->semester;
-        $schoolYear = $this->request->getPost('school_year') ?? $this->schoolYear;
+        $schoolYear = $this->currentSchoolYearName((string) ($this->schoolYear ?? ''));
+        $this->assertSchoolYearWritable($this->resolveSchoolYearContext());
 
         if ($updatedBy === null) {
             $updatedBy = session()->get('user_id');
@@ -175,7 +176,7 @@ class HomeworkController extends Controller
                 }
             }
         }
-        $studentUserInfo = $this->studentModel->getStudentInfoByClassSectionId($classSectionId, $semester, $schoolYear);
+        $studentUserInfo = $this->studentModel->getActiveStudentInfoByClassSectionId($classSectionId, $semester, $schoolYear);
 
         // Call the updateScoresForStudents method
         try {
@@ -195,6 +196,8 @@ class HomeworkController extends Controller
         $selectedSemester = $this->getSelectedSemester();
         $normalized = $this->normalizeSemesterSelection($selectedSemester);
         $semesterLabel = $normalized !== '' ? ucfirst($normalized) : $selectedSemester;
+        $schoolYear = $this->currentSchoolYearName((string) ($this->schoolYear ?? ''));
+        $this->assertSchoolYearWritable($this->resolveSchoolYearContext());
 
         // Step 1: Get the highest existing homework_index
         $existingIndexes = $this->homeworkModel
@@ -202,7 +205,7 @@ class HomeworkController extends Controller
             ->where('class_section_id', $classSectionId)
             //->where('teacher_id', $updatedBy)
             ->whereIn('semester', $this->getSemesterVariants($semesterLabel))
-            ->where('school_year', $this->schoolYear)
+            ->where('school_year', $schoolYear)
             ->groupBy('homework_index')
             ->orderBy('homework_index', 'DESC')
             ->findAll();
@@ -219,6 +222,7 @@ class HomeworkController extends Controller
         // Step 2: Get all students in the class
         $students = $this->studentClassModel
             ->where('class_section_id', $classSectionId)
+            ->where('school_year', $schoolYear)
             ->findAll();
 
         // Step 3: Insert a new homework row for each student if not already exists
@@ -233,7 +237,7 @@ class HomeworkController extends Controller
                 ->where('class_section_id', $classSectionId)
                 //->where('teacher_id', $updatedBy)
                 ->whereIn('semester', $this->getSemesterVariants($semesterLabel))
-                ->where('school_year', $this->schoolYear)
+                ->where('school_year', $schoolYear)
                 ->first();
 
             if ($existing) continue;
@@ -246,7 +250,7 @@ class HomeworkController extends Controller
                 'homework_index'   => $nextIndex,
                 'score'            => null,
                 'semester'         => $semesterLabel,
-                'school_year'      => $this->schoolYear,
+                'school_year'      => $schoolYear,
                 'created_at'       => utc_now(),
                 'updated_at'       => utc_now()
             ];
@@ -269,15 +273,23 @@ class HomeworkController extends Controller
     public function showHomework()
     {
         $updatedBy = session()->get('user_id');
-        $classSectionId = $this->getClassSectionIdForTeacher($updatedBy);
+        $semester = $this->getSelectedSemester();
+        $schoolYear = $this->currentSchoolYearName((string) ($this->schoolYear ?? ''));
+        $classSectionId = (int) (
+            $this->request->getGet('class_section_id')
+            ?? $this->request->getPost('class_section_id')
+            ?? 0
+        );
+        if ($classSectionId <= 0) {
+            $classSectionId = (int) ($this->getClassSectionIdForTeacher($updatedBy, $schoolYear, $semester) ?? 0);
+        }
         if (!$classSectionId) {
             return redirect()->back()->with('status', 'No class section found for the current teacher.');
         }
 
         session()->set('class_section_id', $classSectionId);
 
-        $semester = $this->getSelectedSemester();
-        $homeworkHeaders = $this->getHomeworkHeaders($classSectionId, $semester, $this->schoolYear);
+        $homeworkHeaders = $this->getHomeworkHeaders($classSectionId, $semester, $schoolYear);
         if (empty($homeworkHeaders)) {
             $homeworkHeaders = [1];
         }
@@ -285,15 +297,15 @@ class HomeworkController extends Controller
             $classSectionId,
             $homeworkHeaders,
             $semester,
-            $this->schoolYear
+            $schoolYear
         );
-        $missingOkMap = $this->missingScoreOverrideModel->getOverridesMap($classSectionId, $semester, $this->schoolYear, 'homework');
+        $missingOkMap = $this->missingScoreOverrideModel->getOverridesMap($classSectionId, $semester, $schoolYear, 'homework');
 
         return view('teacher/add_homework', [
             'students'         => $students,
             'homeworkHeaders'  => $homeworkHeaders,
             'semester'         => $semester,
-            'schoolYear'       => $this->schoolYear,
+            'schoolYear'       => $schoolYear,
             'class_section_id' => $classSectionId,
             'missingOkMap'     => $missingOkMap,
         ]);
@@ -392,7 +404,7 @@ class HomeworkController extends Controller
             return $this->showHomeworkMngt($updatedBy);
         }
 
-        $studentTeacherInfo = $this->studentModel->getStudentInfoByClassSectionId($classSectionId);
+        $studentTeacherInfo = $this->studentModel->getActiveStudentInfoByClassSectionId($classSectionId, $semester, $schoolYear);
         // Call the updateScoresForStudents method
         try {
 
@@ -503,9 +515,16 @@ class HomeworkController extends Controller
         return $students;
     }
 
-    private function getClassSectionIdForTeacher($updatedBy)
+    private function getClassSectionIdForTeacher($updatedBy, ?string $schoolYear = null, ?string $semester = null)
     {
-        $class = $this->teacherClassModel->where('teacher_id', $updatedBy)->first();
+        $builder = $this->teacherClassModel->where('teacher_id', $updatedBy);
+        if ($schoolYear !== null && $schoolYear !== '') {
+            $builder->where('school_year', $schoolYear);
+        }
+        if ($semester !== null && $semester !== '') {
+            $builder->where('semester', $semester);
+        }
+        $class = $builder->first();
         return $class['class_section_id'] ?? null;
     }
 

app/Controllers/View/HomeworkTrackingController.php

@@ -26,7 +26,7 @@ class HomeworkTrackingController extends BaseController
         $this->homeworkModel = new HomeworkModel();
         $this->db            = \Config\Database::connect();
 
-        $this->semester   = (string) ($this->configModel->getConfig('semester') ?? '');
+        $this->semester   = (string) (getSemester() ?? '');
         $this->schoolYear = (string) ($this->configModel->getConfig('school_year') ?? '');
     }
 
@@ -72,13 +72,18 @@ class HomeworkTrackingController extends BaseController
         }
 
         $limitToSemester = $this->hasTeacherAssignments($this->schoolYear, $this->semester);
+        $semesterVariants = $this->getSemesterVariants($this->semester);
 
-        // Aggregate homework presence + first entered date per class_section_id + homework_index
+        // Aggregate submitted homework per class_section_id + homework_index.
+        // Adding a homework column creates blank rows for every student, so only
+        // indexes with at least one non-null score count as submitted.
         $hwQ = $this->db->table('homework')
-            ->select('class_section_id, homework_index, MIN(created_at) AS first_created, COUNT(*) AS cnt')
+            ->select('class_section_id, homework_index')
+            ->select('MIN(CASE WHEN score IS NOT NULL THEN updated_at ELSE NULL END) AS first_submitted', false)
+            ->select('COUNT(score) AS scored_count', false)
             ->where('school_year', $this->schoolYear);
-        if ($limitToSemester && $this->semester !== '') {
-            $hwQ->where('semester', $this->semester);
+        if ($limitToSemester && $semesterVariants !== []) {
+            $hwQ->whereIn('semester', $semesterVariants);
         }
         $rows = $hwQ->groupBy('class_section_id, homework_index')
             ->get()
@@ -90,60 +95,32 @@ class HomeworkTrackingController extends BaseController
         foreach ($rows as $r) {
             $csid = (int)($r['class_section_id'] ?? 0);
             $hi   = (int)($r['homework_index'] ?? 0);
-            $cnt  = (int)($r['cnt'] ?? 0);
+            $cnt  = (int)($r['scored_count'] ?? 0);
             if ($csid > 0 && $hi > 0 && $cnt > 0) {
                 $hasHomework[$csid][$hi] = true;
-                $dateStr = substr((string)($r['first_created'] ?? ''), 0, 10);
+                $dateStr = substr((string)($r['first_submitted'] ?? ''), 0, 10);
                 $hwEnteredAt[$csid][$hi] = $dateStr ?: null;
                 $homeworkSubmissionCounts[$csid] = ($homeworkSubmissionCounts[$csid] ?? 0) + 1;
             }
         }
 
-        // Build date-based presence mapped to the nearest prior non-NoSchool Sunday.
-        $hb = $this->db->table('homework')
-            ->select("class_section_id, DATE(created_at) AS hw_date, MIN(created_at) AS first_created, COUNT(*) AS cnt", false)
-            ->where('school_year', $this->schoolYear);
-        if ($limitToSemester && $this->semester !== '') {
-            $hb->where('semester', $this->semester);
+        $indexToDate = [];
+        foreach ($dateToIndex as $ymd => $homeworkIndex) {
+            if ($homeworkIndex !== null) {
+                $indexToDate[(int) $homeworkIndex] = $ymd;
+            }
         }
-        $rowsByDate = $hb->groupBy('class_section_id, DATE(created_at)', '', false)
-            ->orderBy('hw_date', 'ASC', false)
-            ->get()
-            ->getResultArray();
-
         $hasHomeworkByDate = [];
         $hwEnteredAtByDate = [];
-        foreach ($rowsByDate as $r) {
-            $csid = (int)($r['class_section_id'] ?? 0);
-            $d    = substr((string)($r['hw_date'] ?? ''), 0, 10);
-            $cnt  = (int)($r['cnt'] ?? 0);
-            $firstCreated = substr((string)($r['first_created'] ?? ''), 0, 10);
-            if ($csid <= 0 || !$d || $cnt <= 0) { continue; }
-
-            // Find the index of the last Sunday on or before $d
-            $baseIndex = -1;
-            for ($i = count($sundays) - 1; $i >= 0; $i--) {
-                if ($sundays[$i] <= $d) { $baseIndex = $i; break; }
-            }
-            if ($baseIndex < 0) { continue; }
-
-            // Map this homework day to only the nearest prior non–No School Sunday
-            $j = $baseIndex;
-            while ($j >= 0 && !empty($eventDays[$sundays[$j]])) { $j--; }
-            if ($j < 0) { continue; }
-            $sd = $sundays[$j];
-
-            // Mark homework on that Sunday for this class_section (single mapping)
-            $hasHomeworkByDate[$csid][$sd] = true;
-            if (empty($hwEnteredAtByDate[$csid][$sd])) {
-                $hwEnteredAtByDate[$csid][$sd] = $firstCreated ?: $d;
-            } else {
-                // Keep the earliest date for display
-                $existing = (string)$hwEnteredAtByDate[$csid][$sd];
-                $candidate = $firstCreated ?: $d;
-                if ($candidate && (!$existing || $candidate < $existing)) {
-                    $hwEnteredAtByDate[$csid][$sd] = $candidate;
+        foreach ($hasHomework as $csid => $indexes) {
+            foreach ($indexes as $homeworkIndex => $_submitted) {
+                $ymd = $indexToDate[(int) $homeworkIndex] ?? null;
+                if ($ymd === null) {
+                    continue;
                 }
+
+                $hasHomeworkByDate[(int) $csid][$ymd] = true;
+                $hwEnteredAtByDate[(int) $csid][$ymd] = $hwEnteredAt[(int) $csid][(int) $homeworkIndex] ?? null;
             }
         }
 
@@ -252,6 +229,21 @@ class HomeworkTrackingController extends BaseController
         return $this->teacherAssignmentCache[$year];
     }
 
+    private function getSemesterVariants(string $semester): array
+    {
+        $trimmed = trim($semester);
+        if ($trimmed === '') {
+            return [];
+        }
+
+        return array_values(array_unique([
+            $trimmed,
+            ucfirst(strtolower($trimmed)),
+            strtolower($trimmed),
+            strtoupper($trimmed),
+        ]));
+    }
+
     /**
      * Compute start/end dates for the given semester within the school year.
      * Fall: 09/21/{startYear} to 01/18/{startYear+1}

app/Controllers/View/InventoryController.php

@@ -3,6 +3,7 @@
 namespace App\Controllers\View;
 
 use App\Controllers\BaseController;
+use App\Exceptions\SchoolYear\SchoolYearWriteConflictException;
 use App\Models\ClassSectionModel;
 use App\Models\InventoryItemModel;
 use App\Models\InventoryCategoryModel;
@@ -43,7 +44,7 @@ class InventoryController extends BaseController
         $this->teacherClassModel = new TeacherClassModel();
         $this->studentClassModel = new StudentClassModel();
         $this->schoolYear = $this->configModel->getConfig('school_year');
-        $this->semester = $this->configModel->getConfig('semester');
+        $this->semester = getSemester();
         $this->classSectionModel = new ClassSectionModel();
         $this->db = \Config\Database::connect();
         $this->teacherModel = new TeacherModel();
@@ -75,14 +76,14 @@ class InventoryController extends BaseController
         $selectedSem    = $selectedSemRaw === null ? (string) $this->semester : trim((string) $selectedSemRaw);
 
         $builder = $this->itemModel->where('type', $type);
-        if (strtolower($selectedYear) !== 'all') {
-            $builder->where('school_year', $selectedYear);
-        }
-        if ($selectedSem !== '') {
-            $builder->where('semester', $selectedSem);
+        if ($type !== 'book') {
+            $this->applyInventoryMovementPeriodFilter($builder, 'inventory_items', $selectedYear, $selectedSem);
         }
 
         $items = $builder->orderBy('name', 'ASC')->findAll();
+        if ($type === 'book') {
+            $items = $this->attachBookYearRows($items, $selectedYear);
+        }
         $categories = $this->catModel->optionsForType($type);
 
         // NEW: build UpdatedBy name map
@@ -110,6 +111,9 @@ class InventoryController extends BaseController
 
         // Load categories for THIS item type
         $categories = $this->catModel->optionsForType($item['type']);
+        if (($item['type'] ?? '') === 'book') {
+            $item = $this->withBookYearData($item);
+        }
 
         return view($this->viewForForm($item['type']), [
             'type'        => $item['type'],
@@ -139,6 +143,13 @@ class InventoryController extends BaseController
         if (!$this->itemModel->update($id, $data)) {
             return redirect()->back()->withInput()->with('error', implode(', ', $this->itemModel->errors()));
         }
+        if (($item['type'] ?? '') === 'book') {
+            $this->saveBookClassAssignments($id);
+            $gradeError = $this->syncBookCategoryGradeRange($data['category_id'] ?? null);
+            if ($gradeError !== null) {
+                return redirect()->back()->withInput()->with('error', $gradeError);
+            }
+        }
 
         return redirect()->to(site_url('inventory/' . $item['type']))->with('success', 'Item updated.');
     }
@@ -152,6 +163,19 @@ class InventoryController extends BaseController
         $itemId = $this->itemModel->insert($itemData, true);
         if ($itemId) {
             $initialQty = (int) ($itemData['quantity'] ?? 0);
+            if (($itemData['type'] ?? '') === 'book') {
+                $this->saveBookClassAssignments((int) $itemId);
+                $gradeError = $this->syncBookCategoryGradeRange($itemData['category_id'] ?? null);
+                if ($gradeError !== null) {
+                    return redirect()->back()->withInput()->with('error', $gradeError);
+                }
+                if ($initialQty !== 0) {
+                    $this->recordMovement($itemId, $initialQty, 'initial', 'Initial stock');
+                } else {
+                    $this->recalcQuantity($itemId);
+                }
+                return redirect()->to(site_url("inventory/{$itemData['type']}"))->with('success', 'Item added.');
+            }
             if ($initialQty !== 0) {
                 $this->recordMovement($itemId, $initialQty, 'initial', 'Initial stock');
             } else {
@@ -213,20 +237,12 @@ class InventoryController extends BaseController
 
         // Only books have grade range
         if ($data['type'] === 'book') {
-            $gmin = $this->request->getPost('grade_min');
-            $gmax = $this->request->getPost('grade_max');
-
-            $gmin = ($gmin === '' || $gmin === null) ? null : max(0, (int)$gmin);
-            $gmax = ($gmax === '' || $gmax === null) ? null : max(0, (int)$gmax);
-
-            if ($gmin !== null && $gmax !== null && $gmin > $gmax) {
-                return redirect()->back()->withInput()->with('error', 'Grade Min cannot be greater than Grade Max.');
+            $normalized = $this->normalizeGradeRangePost();
+            if (is_string($normalized)) {
+                return redirect()->back()->withInput()->with('error', $normalized);
             }
-            if ($gmin !== null && $gmin > 13) $gmin = 13;
-            if ($gmax !== null && $gmax > 13) $gmax = 13;
-
-            $data['grade_min'] = $gmin;
-            $data['grade_max'] = $gmax;
+            $data['grade_min'] = $normalized['grade_min'];
+            $data['grade_max'] = $normalized['grade_max'];
         } else {
             $data['grade_min'] = null;
             $data['grade_max'] = null;
@@ -248,7 +264,14 @@ class InventoryController extends BaseController
                         'A category with this Type & Name already exists. Please choose a different name or edit the existing one.'
                     );
                 }
-                $ok = $this->catModel->update((int)$id, $data);
+                $current = $this->db->table('inventory_categories')->where('id', (int) $id)->get()->getRowArray();
+                if (!$current) {
+                    return redirect()->back()->withInput()->with('error', 'Category not found.');
+                }
+                if (!empty($current['school_year'])) {
+                    $data['school_year'] = $current['school_year'];
+                }
+                $ok = $this->writeCategoryRow((int) $id, $data);
             } else {
                 // Creating: block if already exists
                 if ($existing) {
@@ -279,7 +302,9 @@ class InventoryController extends BaseController
         }
 
         if (!$ok) {
-            return redirect()->back()->withInput()->with('error', 'Failed to save category.');
+            $errors = $this->catModel->errors();
+            $message = $errors !== [] ? implode(', ', $errors) : 'Failed to save category.';
+            return redirect()->back()->withInput()->with('error', $message);
         }
 
         return redirect()->back()->with('success', 'Category saved.');
@@ -345,6 +370,13 @@ class InventoryController extends BaseController
         if ($type === 'book') {
             $base['isbn']    = $this->post('isbn');
             $base['edition'] = $this->post('edition');
+            $base['author']  = $this->post('author');
+            $base['is_active'] = 1;
+            $isbn = preg_replace('/[^0-9X]/i', '', strtoupper((string) $base['isbn']));
+            $edition = strtolower(trim((string) $base['edition']));
+            $sku = strtolower(trim((string) $base['sku']));
+            $base['isbn_edition_key'] = $isbn !== '' ? $isbn . '|' . $edition : null;
+            $base['sku_normalized'] = $sku !== '' ? $sku : null;
         } else {
             $base['isbn'] = $base['edition'] = null;
         }
@@ -352,6 +384,270 @@ class InventoryController extends BaseController
         return $base;
     }
 
+    private function withBookYearData(array $item): array
+    {
+        $itemYear = $this->bookItemYear((int) $item['id'], false);
+        if ($itemYear !== null) {
+            $item['charge_price'] = number_format(((int) ($itemYear['charge_price_cents'] ?? 0)) / 100, 2, '.', '');
+            $item['price_confirmed'] = (int) ($itemYear['price_confirmed'] ?? 0);
+            $item['item_year_id'] = (int) $itemYear['id'];
+            $item['opening_quantity'] = (int) ($itemYear['opening_quantity'] ?? 0);
+        }
+        $item['classes'] = array_map(
+            'intval',
+            array_column(
+                $this->db->table('inventory_book_class_assignments')
+                    ->select('class_number')
+                    ->where('inventory_item_id', (int) $item['id'])
+                    ->where('school_year', $this->schoolYear)
+                    ->orderBy('class_number', 'ASC')
+                    ->get()->getResultArray(),
+                'class_number'
+            )
+        );
+        return $item;
+    }
+
+    private function attachBookYearRows(array $items, string $schoolYear): array
+    {
+        $ids = array_values(array_filter(array_map(static fn (array $item): int => (int) ($item['id'] ?? 0), $items)));
+        if ($ids === []) {
+            return $items;
+        }
+        $rows = $this->db->table('inventory_item_years')
+            ->whereIn('inventory_item_id', $ids)
+            ->where('school_year', $schoolYear)
+            ->get()->getResultArray();
+        $byItem = [];
+        foreach ($rows as $row) {
+            $byItem[(int) $row['inventory_item_id']] = $row;
+        }
+        foreach ($items as &$item) {
+            $row = $byItem[(int) ($item['id'] ?? 0)] ?? null;
+            if ($row !== null) {
+                $item['charge_price_cents'] = (int) ($row['charge_price_cents'] ?? 0);
+                $item['price_confirmed'] = (int) ($row['price_confirmed'] ?? 0);
+                $item['opening_quantity'] = (int) ($row['opening_quantity'] ?? 0);
+            }
+        }
+        unset($item);
+        return $items;
+    }
+
+    public function bookPrices()
+    {
+        $books = $this->itemModel
+            ->where('type', 'book')
+            ->orderBy('name', 'ASC')
+            ->findAll();
+        $books = $this->attachBookYearRows($books, (string) $this->schoolYear);
+
+        return view('inventory/book/prices', [
+            'books' => $books,
+            'categories' => $this->catModel->optionsForType('book'),
+            'schoolYear' => $this->schoolYear,
+        ]);
+    }
+
+    public function updateBookPrices()
+    {
+        $prices = (array) $this->request->getPost('prices');
+        $confirmed = (array) $this->request->getPost('confirmed');
+        $ids = array_values(array_unique(array_filter(array_map('intval', array_keys($prices)))));
+
+        if ($ids === []) {
+            return redirect()->back()->with('warning', 'No book prices were submitted.');
+        }
+
+        $books = $this->itemModel
+            ->where('type', 'book')
+            ->whereIn('id', $ids)
+            ->findAll();
+        $booksById = [];
+        foreach ($books as $book) {
+            $booksById[(int) $book['id']] = $book;
+        }
+
+        $year = $this->currentSchoolYearRow();
+        $updated = 0;
+
+        try {
+            $this->db->transStart();
+            foreach ($ids as $id) {
+                if (! isset($booksById[$id])) {
+                    continue;
+                }
+
+                $isConfirmed = isset($confirmed[$id]) && (string) $confirmed[$id] === '1';
+                $priceCents = $this->moneyValueToCents($prices[$id] ?? '');
+                if ($isConfirmed && $priceCents <= 0) {
+                    throw new \InvalidArgumentException('Confirmed book prices must be greater than $0.00.');
+                }
+
+                $itemYear = $this->bookItemYear($id, false);
+                $payload = [
+                    'inventory_item_id' => $id,
+                    'school_year_id' => (int) ($year['id'] ?? 0) ?: null,
+                    'school_year' => $this->schoolYear,
+                    'charge_price_cents' => $priceCents,
+                    'currency' => 'USD',
+                    'price_confirmed' => $isConfirmed ? 1 : 0,
+                    'status' => 'open',
+                    'updated_by' => $this->currentUserId(),
+                    'updated_at' => utc_now(),
+                ];
+
+                if ($itemYear === null) {
+                    $payload['opening_quantity'] = (int) ($booksById[$id]['quantity'] ?? 0);
+                    $payload['created_by'] = $this->currentUserId();
+                    $payload['created_at'] = utc_now();
+                    $this->db->table('inventory_item_years')->insert($payload);
+                } else {
+                    $this->db->table('inventory_item_years')->where('id', (int) $itemYear['id'])->update($payload);
+                }
+                $updated++;
+            }
+            $this->db->transComplete();
+
+            if ($this->db->transStatus() === false) {
+                throw new \RuntimeException('Book prices could not be saved.');
+            }
+        } catch (\Throwable $e) {
+            $this->db->transRollback();
+            return redirect()->back()->withInput()->with('error', $e->getMessage());
+        }
+
+        return redirect()->to(site_url('inventory/book-prices'))->with('success', 'Saved prices for ' . $updated . ' book(s).');
+    }
+
+    private function saveBookClassAssignments(int $itemId): void
+    {
+        $classes = array_values(array_unique(array_filter(
+            array_map('intval', (array) $this->request->getPost('classes')),
+            static fn (int $class): bool => $class >= 1 && $class <= 13
+        )));
+        $this->db->table('inventory_book_class_assignments')
+            ->where('inventory_item_id', $itemId)
+            ->where('school_year', $this->schoolYear)
+            ->delete();
+        foreach ($classes as $classNumber) {
+            $this->db->table('inventory_book_class_assignments')->insert([
+                'inventory_item_id' => $itemId,
+                'school_year' => $this->schoolYear,
+                'class_number' => $classNumber,
+                'created_at' => utc_now(),
+            ]);
+        }
+    }
+
+    /**
+     * Persist grade_min/grade_max onto the selected book category.
+     * Returns an error message string on failure, or null on success/no-op.
+     */
+    private function syncBookCategoryGradeRange($categoryId): ?string
+    {
+        $categoryId = (int) ($categoryId ?? 0);
+        if ($categoryId <= 0) {
+            return null;
+        }
+
+        // Disabled inputs are omitted from POST; do not wipe an existing category range.
+        $post = $this->request->getPost();
+        if (! is_array($post)
+            || (! array_key_exists('grade_min', $post) && ! array_key_exists('grade_max', $post))
+        ) {
+            return null;
+        }
+
+        $normalized = $this->normalizeGradeRangePost();
+        if (is_string($normalized)) {
+            return $normalized;
+        }
+
+        $category = $this->db->table('inventory_categories')->where('id', $categoryId)->get()->getRowArray();
+        if (!$category || ($category['type'] ?? '') !== 'book') {
+            return 'Selected category was not found or is not a book category.';
+        }
+
+        $payload = [
+            'grade_min' => $normalized['grade_min'],
+            'grade_max' => $normalized['grade_max'],
+        ];
+        if (!empty($category['school_year'])) {
+            $payload['school_year'] = $category['school_year'];
+        }
+
+        if (!$this->writeCategoryRow($categoryId, $payload)) {
+            return 'Failed to update category grade range.';
+        }
+
+        return null;
+    }
+
+    private function writeCategoryRow(int $id, array $data): bool
+    {
+        $data['updated_at'] = date('Y-m-d H:i:s');
+
+        return (bool) $this->db->table('inventory_categories')->where('id', $id)->update($data);
+    }
+
+    /**
+     * @return array{grade_min: ?int, grade_max: ?int}|string
+     */
+    private function normalizeGradeRangePost()
+    {
+        $gmin = $this->request->getPost('grade_min');
+        $gmax = $this->request->getPost('grade_max');
+
+        $gmin = ($gmin === '' || $gmin === null) ? null : max(0, (int) $gmin);
+        $gmax = ($gmax === '' || $gmax === null) ? null : max(0, (int) $gmax);
+
+        if ($gmin !== null && $gmin > 13) {
+            $gmin = 13;
+        }
+        if ($gmax !== null && $gmax > 13) {
+            $gmax = 13;
+        }
+
+        if ($gmin !== null && $gmax !== null && $gmin > $gmax) {
+            return 'Grade Min cannot be greater than Grade Max.';
+        }
+
+        return [
+            'grade_min' => $gmin,
+            'grade_max' => $gmax,
+        ];
+    }
+
+    private function moneyValueToCents($value): int
+    {
+        $raw = trim((string) $value);
+        if ($raw === '') {
+            return 0;
+        }
+        if (! preg_match('/^\d+(?:\.\d{1,2})?$/', $raw)) {
+            throw new \InvalidArgumentException('Book charge price must be a valid dollar amount with at most two decimals.');
+        }
+        return (int) round(((float) $raw) * 100);
+    }
+
+    private function currentSchoolYearRow(): ?array
+    {
+        return $this->db->table('school_years')
+            ->where('name', $this->schoolYear)
+            ->get(1)
+            ->getRowArray();
+    }
+
+    private function bookItemYear(int $itemId, bool $forUpdate = false): ?array
+    {
+        $sql = 'SELECT * FROM inventory_item_years WHERE inventory_item_id = ? AND school_year = ? LIMIT 1';
+        if ($forUpdate) {
+            $sql .= ' FOR UPDATE';
+        }
+        return $this->db->query($sql, [$itemId, $this->schoolYear])->getRowArray();
+    }
+
     public function auditClassroomForm(int $itemId)
     {
         $item = $this->itemModel->find($itemId);
@@ -474,17 +770,26 @@ class InventoryController extends BaseController
     // Distinct school years for a given inventory type (newest first).
     private function getSchoolYearsForType(string $type): array
     {
-        // Pull distinct non-null school_year values for this type
-        $years = $this->itemModel
-            ->select('school_year')
-            ->where('type', $type)
-            ->where('school_year IS NOT NULL', null, false)
-            ->groupBy('school_year')
-            ->orderBy('school_year', 'DESC')
-            ->findColumn('school_year') ?? [];
+        $rows = $this->db->table('inventory_movements m')
+            ->distinct()
+            ->select('m.school_year')
+            ->join('inventory_items i', 'i.id = m.item_id', 'inner')
+            ->where('m.school_year IS NOT NULL', null, false)
+            ->where("TRIM(m.school_year) <>", '')
+            ->orderBy('m.school_year', 'DESC');
+
+        if (strtolower($type) !== 'all') {
+            $rows->where('i.type', $type);
+        }
+
+        $rows = $rows->get()
+            ->getResultArray();
 
         // Normalize & de-dup
-        $years = array_values(array_unique(array_filter(array_map('trim', $years))));
+        $years = array_values(array_unique(array_filter(array_map(
+            static fn(array $row): string => trim((string)($row['school_year'] ?? '')),
+            $rows
+        ))));
 
         // Ensure the current year (from config) appears as an option, even if no rows yet
         $currentYear = $this->schoolYear;
@@ -496,6 +801,31 @@ class InventoryController extends BaseController
         return $years;
     }
 
+    private function applyInventoryMovementPeriodFilter($builder, string $itemAlias, ?string $schoolYear, ?string $semester = null): void
+    {
+        $schoolYear = trim((string) $schoolYear);
+        $semester = trim((string) $semester);
+        $clauses = ["m.item_id = {$itemAlias}.id"];
+
+        if ($schoolYear !== '' && strtolower($schoolYear) !== 'all') {
+            $clauses[] = 'm.school_year = ' . $this->db->escape($schoolYear);
+        }
+
+        if ($semester !== '') {
+            $clauses[] = 'm.semester = ' . $this->db->escape($semester);
+        }
+
+        if (count($clauses) <= 1) {
+            return;
+        }
+
+        $builder->where(
+            'EXISTS (SELECT 1 FROM inventory_movements m WHERE ' . implode(' AND ', $clauses) . ')',
+            null,
+            false
+        );
+    }
+
     private function recordMovement(
         int $itemId,
         int $qtyChange,
@@ -684,6 +1014,8 @@ class InventoryController extends BaseController
      */
     public function teacherDistributeForm()
     {
+        $schoolYearContext = $this->resolveSchoolYearContext();
+
         // 1) Build teacher/class context (auth/role/no-class handled inside)
         $ctx = $this->buildTeacherClassContext();
         if ($ctx instanceof \CodeIgniter\HTTP\RedirectResponse) {
@@ -710,12 +1042,17 @@ class InventoryController extends BaseController
         $db = \Config\Database::connect();
         $builder = $db->table('inventory_items i')
             ->select('i.id,i.name,i.isbn,i.edition,i.quantity,i.category_id,i.type,
+                  iy.id AS item_year_id, iy.charge_price_cents, iy.price_confirmed,
                   c.name AS category_name, c.grade_min, c.grade_max')
             ->join('inventory_categories c', 'c.id = i.category_id', 'left')
+            ->join('inventory_item_years iy', 'iy.inventory_item_id = i.id AND iy.school_year = ' . $db->escape($this->schoolYear), 'left')
+            ->join('inventory_book_class_assignments bca', 'bca.inventory_item_id = i.id AND bca.school_year = ' . $db->escape($this->schoolYear), 'left')
             ->where('i.type', 'book');
 
         if (!empty($classID)) {
             $builder->groupStart()
+                ->where('bca.class_number', (int) $classID)
+                ->orGroupStart()
                 // Case A: both bounds set and classID between [min..max]
                 ->groupStart()
                 ->where('c.grade_min IS NOT NULL', null, false)
@@ -737,10 +1074,11 @@ class InventoryController extends BaseController
                 ->where('c.grade_min', null)               // IS NULL
                 ->where('c.grade_max', (int)$classID)      // =
                 ->groupEnd()
+                ->groupEnd()
                 ->groupEnd();
         }
 
-        $rows = $builder->orderBy('i.name', 'ASC')->get()->getResultArray();
+        $rows = $builder->groupBy('i.id')->orderBy('i.name', 'ASC')->get()->getResultArray();
 
         // Build CATEGORY groups keyed by category_id
         $labelFor = static function (?array $r): string {
@@ -771,6 +1109,8 @@ class InventoryController extends BaseController
                 'id'       => (int)$r['id'],
                 'display'  => $display,
                 'quantity' => (int)($r['quantity'] ?? 0),
+                'charge_price_cents' => (int)($r['charge_price_cents'] ?? 0),
+                'price_confirmed' => (int)($r['price_confirmed'] ?? 0),
             ];
         }
 
@@ -787,16 +1127,16 @@ class InventoryController extends BaseController
         // 7) History map: how many of the selected book each student already received this school year
         $already = [];
         if ($itemId && $classSectionId) {
-            $rowsHist = $this->movModel
-                ->select('student_id, SUM(CASE WHEN qty_change < 0 THEN -qty_change ELSE 0 END) AS qty')
-                ->where([
-                    'item_id'          => $itemId,
-                    'movement_type'    => 'distribution',
-                    'class_section_id' => $classSectionId,
-                    'school_year'      => $ctx['schoolYear'],
-                ])
+            $itemYear = $this->bookItemYear($itemId, false);
+            $rowsHist = $this->db->table('student_book_issues')
+                ->select('student_id, SUM(quantity) AS qty')
+                ->where('inventory_item_id', $itemId)
+                ->where('inventory_item_year_id', (int) ($itemYear['id'] ?? 0))
+                ->where('class_section_id', $classSectionId)
+                ->where('school_year', $ctx['schoolYear'])
+                ->where('status', 'issued')
                 ->groupBy('student_id')
-                ->findAll();
+                ->get()->getResultArray();
 
             foreach ($rowsHist as $r) {
                 $sid = (int) ($r['student_id'] ?? 0);
@@ -806,11 +1146,16 @@ class InventoryController extends BaseController
 
         // 8) On-hand for the selected book (to show live available stock)
         $onHand = 0;
+        $unitChargeCents = 0;
+        $priceConfirmed = 0;
         if ($itemId) {
             $book = $this->itemModel->find($itemId);
             if ($book && ($book['type'] ?? '') === 'book') {
                 $onHand = (int) ($book['quantity'] ?? 0);
             }
+            $itemYear = $this->bookItemYear($itemId, false);
+            $unitChargeCents = (int) ($itemYear['charge_price_cents'] ?? 0);
+            $priceConfirmed = (int) ($itemYear['price_confirmed'] ?? 0);
         }
 
         // 9) Render view
@@ -826,14 +1171,24 @@ class InventoryController extends BaseController
             'students'         => $students,
             'already'          => $already,
             'onHand'           => $onHand,
+            'unitChargeCents'  => $unitChargeCents,
+            'priceConfirmed'   => $priceConfirmed,
 
             'schoolYear'       => $ctx['schoolYear'],
             'semester'         => $ctx['semester'],
+            'isEditable'       => ! $schoolYearContext->isReadonly(),
         ]);
     }
 
     public function teacherDistributeStore()
     {
+        $schoolYearContext = $this->resolveSchoolYearContext();
+        try {
+            $this->assertSchoolYearWritable($schoolYearContext);
+        } catch (SchoolYearWriteConflictException $e) {
+            return redirect()->back()->withInput()->with('error', $e->getMessage());
+        }
+
         $ctx = $this->buildTeacherClassContext();
         if ($ctx instanceof \CodeIgniter\HTTP\RedirectResponse) {
             return $ctx;
@@ -870,50 +1225,34 @@ class InventoryController extends BaseController
         $selectedIds = array_values(array_unique(array_map('intval', $selectedIds)));
         $selectedIds = array_values(array_filter($selectedIds, fn($sid) => isset($validIds[$sid])));
 
-        // Already distributed this year for this class/book
-        $already = [];
-        $rows = $this->movModel
-            ->select('student_id, SUM(CASE WHEN qty_change < 0 THEN -qty_change ELSE 0 END) AS qty')
-            ->where([
-                'item_id'          => $itemId,
-                'movement_type'    => 'distribution',
-                'class_section_id' => $classSectionId,
-                'school_year'      => $ctx['schoolYear'],
-            ])->groupBy('student_id')->findAll();
-        foreach ($rows as $r) {
-            $sid = (int)($r['student_id'] ?? 0);
-            if ($sid) $already[$sid] = (int)$r['qty'];
+        try {
+            $year = $this->currentSchoolYearRow();
+            $result = (new \App\Services\StudentBookIssueService($this->db))->distributeBatch(
+                $itemId,
+                $selectedIds,
+                $classSectionId,
+                (int) ($year['id'] ?? 0),
+                (string) $ctx['schoolYear'],
+                $this->currentUserId(),
+                $note,
+                null,
+                (string) $this->request->getPost('idempotency_key')
+            );
+        } catch (\Throwable $e) {
+            return redirect()
+                ->to(site_url('inventory/books/distribute?class_section_id=' . $classSectionId . '&item_id=' . $itemId))
+                ->withInput()
+                ->with('error', $e->getMessage());
         }
 
-        // Only assign to students who don't already have it
-        $toGive = [];
-        foreach ($selectedIds as $sid) {
-            if (($already[$sid] ?? 0) < 1) $toGive[] = $sid;
-        }
-
-        // Stock check
-        $needed = count($toGive);
-        $onHand = (int)$book['quantity'];
-        if ($needed > $onHand) {
-            return redirect()->back()->withInput()->with('error', 'Not enough stock: need ' . $needed . ', on hand ' . $onHand . '.');
-        }
-
-        // Record one movement per student
-        $okCount = 0;
-        foreach ($toGive as $sid) {
-            $ok = $this->recordMovement($itemId, -1, 'distribution', 'Teacher distribution', $note, $classSectionId, $sid);
-            if ($ok) $okCount++;
-        }
-
-        if ($okCount === 0) {
+        if ((int) ($result['issued'] ?? 0) === 0) {
             return redirect()
                 ->to(site_url('inventory/books/distribute?class_section_id=' . $classSectionId . '&item_id=' . $itemId))
                 ->with('warning', 'No changes (everyone selected already has this book).');
         }
-
         return redirect()
             ->to(site_url('inventory/books/distribute?class_section_id=' . $classSectionId . '&item_id=' . $itemId))
-            ->with('success', 'Distributed to ' . $okCount . ' student(s).');
+            ->with('success', 'Distributed to ' . (int) $result['issued'] . ' student(s).');
     }
 
 
@@ -949,7 +1288,10 @@ class InventoryController extends BaseController
             ->where('ur.user_id', $user_id)
             ->get()->getResultArray();
 
-        $roleNames = array_map(fn($r) => $r['name'], $roles);
+        $roleNames = array_map(
+            static fn($r): string => strtolower(trim((string) ($r['name'] ?? ''))),
+            $roles
+        );
 
         if (in_array('teacher', $roleNames, true)) {
             $user['role_name'] = 'teacher';
@@ -960,12 +1302,15 @@ class InventoryController extends BaseController
         }
 
         // 4) Collect class_section IDs
-        $classSectionIds = array_column($classes, 'class_section_id');
+        $classSectionIds = array_values(array_filter(array_map(
+            static fn($class): int => (int) ($class['class_section_id'] ?? 0),
+            $classes
+        )));
         $studentsData = [];
 
         // 5) Group students by class_section_id
         if (!empty($classSectionIds)) {
-            $students = $this->studentClassModel->getStudentsByClassSectionIds($classSectionIds);
+            $students = $this->studentClassModel->getStudentsByClassSectionIds($classSectionIds, $this->schoolYear);
             foreach ($students as $student) {
                 $studentsData[$student['class_section_id']][] = $student;
             }
@@ -1065,7 +1410,9 @@ class InventoryController extends BaseController
 
     public function create(string $type = 'classroom')
     {
+        $type = $this->normalizeType($type);
         $categories = $this->catModel->optionsForType($type);
+
         return view("inventory/{$type}/form", [
             'type'             => $type,
             'item'             => [], // important for create
@@ -1095,7 +1442,7 @@ class InventoryController extends BaseController
 
         // Filter by school year unless "all"
         if (!$isAllYears) {
-            $qbItems->where('i.school_year', $selectedYear);
+            $this->applyInventoryMovementPeriodFilter($qbItems, 'i', $selectedYear);
         }
 
         // Optional: filter by type if provided
@@ -1123,7 +1470,7 @@ class InventoryController extends BaseController
             return view('inventory/summary', [
                 'selectedYear' => $selectedYear,
                 'currentYear'  => $this->schoolYear,
-                'schoolYears'  => $this->getSchoolYearsForType('book') ?: [$this->schoolYear, 'All'],
+                'schoolYears'  => $this->getSchoolYearsForType($selectedType) ?: [$this->schoolYear, 'All'],
                 'rows'         => $rows,
                 'totals'       => $totals,
                 // optionally pass the selected type if your view supports it
@@ -1202,7 +1549,7 @@ class InventoryController extends BaseController
         }
 
         // -------- Year dropdown options --------
-        $schoolYears = $this->getSchoolYearsForType('book') ?: [$this->schoolYear, 'All'];
+        $schoolYears = $this->getSchoolYearsForType($selectedType) ?: [$this->schoolYear, 'All'];
 
         return view('inventory/summary', [
             'selectedYear' => $selectedYear,
@@ -1307,6 +1654,10 @@ class InventoryController extends BaseController
         $userId = (int) (session('user_id') ?? 0);
         $itemId = (int) $this->request->getPost('item_id');
         $movementType = (string) $this->request->getPost('movement_type');
+        if ($movementType === 'distribution') {
+            return redirect()->back()->withInput()->with('status', 'error')
+                ->with('message', 'Student book distributions must be created from the book distribution workflow.');
+        }
 
         $item = $this->itemModel->find($itemId);
         if (!$item) {
@@ -1364,6 +1715,10 @@ class InventoryController extends BaseController
             return redirect()->to(site_url('inventory/movements'))
                 ->with('status', 'error')->with('message', 'Movement not found.');
         }
+        if ($this->isProtectedMovement($movement)) {
+            return redirect()->to(site_url('inventory/movements'))
+                ->with('status', 'error')->with('message', 'Issue-backed or distribution movements are read-only. Use correction reversal instead.');
+        }
 
         // enrich for display (names)
         $movement = $this->hydrateNames($movement);
@@ -1409,8 +1764,16 @@ class InventoryController extends BaseController
             return redirect()->to(site_url('inventory/movements'))
                 ->with('status', 'error')->with('message', 'Movement not found.');
         }
+        if ($this->isProtectedMovement($existing)) {
+            return redirect()->to(site_url('inventory/movements'))
+                ->with('status', 'error')->with('message', 'Issue-backed or distribution movements are read-only. Use correction reversal instead.');
+        }
 
         $movementType = (string) $this->request->getPost('movement_type');
+        if ($movementType === 'distribution') {
+            return redirect()->back()->withInput()->with('status', 'error')
+                ->with('message', 'Student book distributions must be created from the book distribution workflow.');
+        }
         $qtyChange = $this->normalizeMovementQty($movementType, (int) $this->request->getPost('qty_change'));
 
         $itemId = (int) ($existing['item_id'] ?? 0);
@@ -1464,10 +1827,13 @@ class InventoryController extends BaseController
     {
         // Optional: authorization checks here
         log_message('info', 'Inventory: delete one attempt', ['id' => $id, 'user' => (int)(session('user_id') ?? 0)]);
-        $movement = $this->db->table('inventory_movements')->select('id, item_id')->where('id', $id)->get()->getRowArray();
+        $movement = $this->db->table('inventory_movements')->select('*')->where('id', $id)->get()->getRowArray();
         if (!$movement) {
             return redirect()->back()->with('status', 'error')->with('message', 'Movement not found.');
         }
+        if ($this->isProtectedMovement($movement)) {
+            return redirect()->back()->with('status', 'error')->with('message', 'Issue-backed or distribution movements are read-only. Use correction reversal instead.');
+        }
 
         $ok = $this->db->table('inventory_movements')->where('id', $id)->delete();
         log_message('info', 'Inventory: delete one result', ['id' => $id, 'ok' => (bool)$ok, 'affected' => $this->db->affectedRows()]);
@@ -1537,6 +1903,16 @@ class InventoryController extends BaseController
         return false;
     }
 
+    private function isProtectedMovement(array $movement): bool
+    {
+        $type = (string) ($movement['movement_type'] ?? '');
+        $sourceType = (string) ($movement['source_type'] ?? '');
+        return $type === 'distribution'
+            || in_array($sourceType, ['student_book_issue', 'student_book_issue_reversal'], true)
+            || (int) ($movement['source_id'] ?? 0) > 0
+            || (int) ($movement['reversal_of_movement_id'] ?? 0) > 0;
+    }
+
     /** Hydrate display names for a row (used in edit) */
     private function hydrateNames(array $m): array
     {
@@ -1642,13 +2018,18 @@ class InventoryController extends BaseController
     }
 
     log_message('info', 'Inventory: bulk delete attempt', ['count' => count($ids), 'ids' => $ids, 'user' => (int)(session('user_id') ?? 0)]);
-    $itemIds = $this->db->table('inventory_movements')
-        ->select('item_id')
+    $movements = $this->db->table('inventory_movements')
+        ->select('*')
         ->whereIn('id', $ids)
         ->get()->getResultArray();
+    foreach ($movements as $movement) {
+        if ($this->isProtectedMovement($movement)) {
+            return redirect()->back()->with('status','error')->with('message','Bulk delete contains issue-backed or distribution movement #' . (int) $movement['id'] . '. Use correction reversal instead.');
+        }
+    }
     $itemIds = array_values(array_unique(array_filter(array_map(
         static fn($r) => (int) ($r['item_id'] ?? 0),
-        $itemIds
+        $movements
     ))));
 
     $ok = $this->db->table('inventory_movements')->whereIn('id', $ids)->delete();

app/Controllers/View/LandingPageController.php

@@ -56,7 +56,8 @@ class LandingPageController extends BaseController
 
         // Fetch Enrollment and Refund Deadlines from Configuration
         $this->schoolYear = $this->configModel->getConfig('school_year');
-        $this->semester = $this->configModel->getConfig('semester');
+        $this->semester = getSemester();
+        $this->schoolYear = $this->selectedSchoolYearName((string) ($this->schoolYear ?? ''));
         $this->lastDayOfRegistration = $this->configModel->getConfig('enrollment_deadline') ?? 'Not set';
         $this->refundDeadline = $this->configModel->getConfig('refund_deadline') ?? 'Not set';
 
@@ -103,7 +104,7 @@ class LandingPageController extends BaseController
         // Get all class assignments for this teacher in the current term
         $assignments = $this->teacherClassModel->getClassAssignmentsByUserId(
             (int)$user_id,
-            (string)$this->schoolYear,
+            $this->selectedSchoolYearName((string) ($this->schoolYear ?? '')),
             (string)$this->semester
         );
 
@@ -126,6 +127,15 @@ class LandingPageController extends BaseController
         return $chosen;
     }
 
+    private function selectedSchoolYearName(string $fallback): string
+    {
+        try {
+            return service('schoolYearContext')->resolve(service('request'))->yearName();
+        } catch (\Throwable) {
+            return $fallback;
+        }
+    }
+
 
     public function administrator()
     {
@@ -850,8 +860,13 @@ class LandingPageController extends BaseController
             ->get()
             ->getResultArray();
 
-        // Fetch latest invoice balance
-        $paymentBalance = $this->invoiceModel->getLatestInvoiceTotalAmount($parentId);
+        $paymentRow = $this->db->table('invoices')
+            ->select('COALESCE(SUM(balance), 0) AS account_balance')
+            ->where('parent_id', $parentId)
+            ->where('school_year', $this->schoolYear)
+            ->get()
+            ->getRowArray();
+        $paymentBalance = (float) ($paymentRow['account_balance'] ?? 0);
 
         // Pass data to the view, including the deadlines
         return view('/landing_page/parent_dashboard', [

app/Controllers/View/LateSlipLogsController.php

@@ -21,8 +21,8 @@ class LateSlipLogsController extends BaseController
     {
         $req = $this->request;
 
-        $defaultYear = (string) ($this->configModel->getConfig('school_year') ?? '');
-        $defaultSem  = (string) ($this->configModel->getConfig('semester')    ?? '');
+        $defaultYear = $this->currentSchoolYearName((string) ($this->schoolYear ?? ''));
+        $defaultSem  = (string) (getSemester()    ?? '');
         $schoolYear  = trim((string) ($req->getGet('school_year') ?? $defaultYear));
         $semester    = trim((string) ($req->getGet('semester')    ?? $defaultSem));
         $q           = trim((string) ($req->getGet('q') ?? ''));

app/Controllers/View/MessagesController.php

@@ -92,6 +92,10 @@ class MessagesController extends BaseController
         $userRoleModel = new UserRoleModel();
         //$role = session()->get('role');
         $userId = session()->get('user_id');
+        if (empty($userId)) {
+            return redirect()->to('/login');
+        }
+
         // Fetch the user role from the user_roles and roles tables
         $role = $userRoleModel->select('roles.name')
             ->join('roles', 'roles.id = user_roles.role_id')
@@ -103,6 +107,11 @@ class MessagesController extends BaseController
         $attachmentPath = null;
         $file = $this->request->getFile('attachment');
         if ($file && $file->isValid() && !$file->hasMoved()) {
+            $allowedExt = ['pdf', 'jpg', 'jpeg', 'png', 'gif', 'webp', 'doc', 'docx'];
+            $ext = strtolower((string) $file->getExtension());
+            if (! in_array($ext, $allowedExt, true) || $file->getSize() > 5 * 1024 * 1024) {
+                return redirect()->back()->with('error', 'Attachment must be a document or image under 5MB.');
+            }
             $attachmentPath = $file->store();
         }
 

app/Controllers/View/MidtermController.php

@@ -36,7 +36,7 @@ class MidtermController extends BaseController
         $this->teacherClassModel = new TeacherClassModel();
         $this->semesterScoreService = service('semesterScoreService');
         $this->schoolYear = $this->configModel->getConfig('school_year');
-        $this->semester = $this->configModel->getConfig('semester');
+        $this->semester = getSemester();
         $this->gradingLockModel = new GradingLockModel();
         $this->missingScoreOverrideModel = new MissingScoreOverrideModel();
     }
@@ -122,7 +122,7 @@ class MidtermController extends BaseController
             true
         );
 
-        $studentTeacherInfo = $this->studentModel->getStudentInfoByClassSectionId($classSectionId, $semester, $schoolYear);
+        $studentTeacherInfo = $this->studentModel->getActiveStudentInfoByClassSectionId($classSectionId, $semester, $schoolYear);
         // Call the updateScoresForStudents method
         try {
 
@@ -155,7 +155,7 @@ class MidtermController extends BaseController
 
         session()->setFlashdata('status', 'Midterm exam scores updated successfully.');
 
-        $studentTeacherInfo = $this->studentModel->getStudentInfoByClassSectionId($classSectionId, $semester, $schoolYear);
+        $studentTeacherInfo = $this->studentModel->getActiveStudentInfoByClassSectionId($classSectionId, $semester, $schoolYear);
         // Call the updateScoresForStudents method
         try {
 
@@ -288,6 +288,7 @@ class MidtermController extends BaseController
             // Join the "latest midterm per student" subquery, then the actual midterm row
             ->join('(' . $latestMidtermSub . ') ml', 'ml.student_id = s.id', 'left', false)
             ->join('midterm_exam me', 'me.id = ml.max_id', 'left')
+            ->where('s.is_active', 1)
             ->orderBy('s.lastname', 'ASC')
             ->orderBy('s.firstname', 'ASC');
 

app/Controllers/View/NotificationsController.php

@@ -90,6 +90,10 @@ class NotificationsController extends BaseController
     {
         helper('url');
 
+        if ($redirect = $this->redirectWithoutLegacyTermFilters('notifications/active')) {
+            return $redirect;
+        }
+
         $targetGroup = $this->request->getGet('target_group');
 
         return view('notifications/list_active', [
@@ -102,6 +106,10 @@ class NotificationsController extends BaseController
     {
         helper(['url', 'form']);
 
+        if ($redirect = $this->redirectWithoutLegacyTermFilters('notifications/deleted')) {
+            return $redirect;
+        }
+
         return view('notifications/list_deleted', [
             'deletedNotificationsEndpoint' => site_url('api/notifications/deleted'),
             'restoreEndpoint'              => site_url('notifications/restore'),
@@ -149,6 +157,11 @@ class NotificationsController extends BaseController
             $targetGroup = null;
         }
 
+        $schoolYear = $this->currentSchoolYearName();
+        if ($schoolYear !== '' && db_connect()->fieldExists('school_year', 'notifications')) {
+            $this->notificationModel->where('school_year', $schoolYear);
+        }
+
         $rows = $this->notificationModel->getActiveNotifications($targetGroup);
         if (!is_array($rows)) {
             $rows = [];
@@ -210,4 +223,25 @@ class NotificationsController extends BaseController
             'notifications' => $notifications,
         ];
     }
+
+    private function redirectWithoutLegacyTermFilters(string $route): ?\CodeIgniter\HTTP\RedirectResponse
+    {
+        $legacyTermKeys = ['school_year', 'schoolYear', 'year', 'semester'];
+        $query = $this->request->getGet();
+        $hasLegacyTermFilter = false;
+
+        foreach ($legacyTermKeys as $key) {
+            if (array_key_exists($key, $query)) {
+                unset($query[$key]);
+                $hasLegacyTermFilter = true;
+            }
+        }
+
+        if (!$hasLegacyTermFilter) {
+            return null;
+        }
+
+        $target = site_url($route) . (!empty($query) ? '?' . http_build_query($query) : '');
+        return redirect()->to($target);
+    }
 }

app/Controllers/View/ParentAttendanceReportController.php

@@ -11,6 +11,7 @@ use App\Models\StudentClassModel;
 use App\Models\ClassSectionModel;
 use App\Models\AttendanceDataModel;
 use App\Models\AttendanceRecordModel;
+use App\Exceptions\SchoolYear\SchoolYearWriteConflictException;
 use App\Services\SemesterRangeService;
 
 class ParentAttendanceReportController extends BaseController
@@ -58,7 +59,8 @@ class ParentAttendanceReportController extends BaseController
         [$sundays, $defaultDate] = $this->computeSundays();
 
         // Load upcoming reports for preview/edit (today and forward within this school year)
-        $schoolYear = (string) $this->configModel->getConfig('school_year');
+        $schoolYearContext = $this->resolveSchoolYearContext();
+        $schoolYear = $schoolYearContext->yearName();
         $todayYmd   = local_date(utc_now(), 'Y-m-d');
         $previewRows = $this->reportModel->builder()
             ->select('parent_attendance_reports.*, s.firstname, s.lastname')
@@ -80,6 +82,8 @@ class ParentAttendanceReportController extends BaseController
             'defaultDate' => $defaultDate,   // preselected date (upcoming Sunday)
             'myReports'   => $previewRows,
             'cutoffThreshold' => $cutoffThreshold,
+            'selectedYear' => $schoolYear,
+            'isEditable' => ! $schoolYearContext->isReadonly(),
         ]);
     }
 
@@ -91,6 +95,13 @@ class ParentAttendanceReportController extends BaseController
             return redirect()->to('/login');
         }
 
+        $schoolYearContext = $this->resolveSchoolYearContext();
+        try {
+            $this->assertSchoolYearWritable($schoolYearContext);
+        } catch (SchoolYearWriteConflictException $e) {
+            return redirect()->back()->withInput()->with('error', $e->getMessage());
+        }
+
         $post = $this->request->getPost();
 
         $rules = [
@@ -141,6 +152,7 @@ class ParentAttendanceReportController extends BaseController
         $dismissTime = $post['dismiss_time'] ?? null;
         $reasonRaw   = $post['reason'] ?? null;
         $reason      = is_string($reasonRaw) ? trim($reasonRaw) : null;
+        $schoolYear  = $schoolYearContext->yearName();
 
         // Enforce Sunday-only and future-or-today selection
         $todayCheck = new \DateTime('today');
@@ -157,7 +169,7 @@ class ParentAttendanceReportController extends BaseController
         }
         $validDates = [];
 
-        $cap = $this->firstSundayOfJune((string) $this->configModel->getConfig('school_year'));
+        $cap = $this->firstSundayOfJune($schoolYear);
 
         $lateCutoff = null;
         $lateNow = null;
@@ -235,8 +247,7 @@ class ParentAttendanceReportController extends BaseController
 
         // Upper bound already enforced by $validDates building
 
-        $semester    = (string) $this->configModel->getConfig('semester');
-        $schoolYear  = (string) $this->configModel->getConfig('school_year');
+        $semester    = (string) getSemester();
         $semesterResolver = new SemesterRangeService($this->configModel);
 
         $inserted        = 0;
@@ -493,7 +504,7 @@ class ParentAttendanceReportController extends BaseController
         }
 
         // Upper bound: first Sunday of June (school year end)
-        $schoolYear = (string) $this->configModel->getConfig('school_year');
+        $schoolYear = $this->currentSchoolYearName((string) ($this->configModel->getConfig('school_year') ?? ''));
         $cap        = $this->firstSundayOfJune($schoolYear);
 
         $dates = [];
@@ -985,7 +996,7 @@ class ParentAttendanceReportController extends BaseController
             : (string)$this->configModel->getConfig('school_year');
         $semester   = (is_string($semesterParam) && $semesterParam !== '')
             ? (string)$semesterParam
-            : (string)$this->configModel->getConfig('semester');
+            : (string) getSemester();
 
         $rows = $this->reportModel->listForDateRange($start, $end ?: null, $schoolYear, $semester);
 
@@ -1295,7 +1306,7 @@ class ParentAttendanceReportController extends BaseController
         }
 
         $schoolYear = (string)$this->configModel->getConfig('school_year');
-        $semester   = (string)$this->configModel->getConfig('semester');
+        $semester   = (string) getSemester();
 
         // Fetch students with their current-year class section (if any)
         try {
@@ -1351,7 +1362,7 @@ class ParentAttendanceReportController extends BaseController
         }
 
         $schoolYear = (string)$this->configModel->getConfig('school_year');
-        $semester   = (string)$this->configModel->getConfig('semester');
+        $semester   = (string) getSemester();
 
         // Resolve parent_id of the student
         $stu = $this->studentModel->select('id, parent_id, firstname, lastname')->find($studentId);
@@ -1458,12 +1469,15 @@ class ParentAttendanceReportController extends BaseController
             return $this->response->setJSON(['ok' => true, 'students' => []]);
         }
 
+        $schoolYear = $this->currentSchoolYearName((string) ($this->configModel->getConfig('school_year') ?? ''));
+
         // Fetch existing submissions for these students on this date
         $rows = $this->reportModel->builder()
             ->select('parent_attendance_reports.student_id, parent_attendance_reports.type, parent_attendance_reports.report_date, s.firstname, s.lastname')
             ->join('students s', 's.id = parent_attendance_reports.student_id', 'left')
             ->whereIn('parent_attendance_reports.report_date', $dateValues)
             ->whereIn('parent_attendance_reports.student_id', $studentIds)
+            ->where('parent_attendance_reports.school_year', $schoolYear)
             ->get()->getResultArray();
 
         $map = [];
@@ -1505,6 +1519,13 @@ class ParentAttendanceReportController extends BaseController
             return redirect()->to('/login');
         }
 
+        $schoolYearContext = $this->resolveSchoolYearContext();
+        try {
+            $this->assertSchoolYearWritable($schoolYearContext);
+        } catch (SchoolYearWriteConflictException $e) {
+            return redirect()->back()->with('error', $e->getMessage());
+        }
+
         $id = (int) ($this->request->getPost('id') ?? 0);
         if ($id <= 0) {
             return redirect()->back()->with('error', 'Invalid report.');
@@ -1514,6 +1535,9 @@ class ParentAttendanceReportController extends BaseController
         if (!$row || (int)($row['parent_id'] ?? 0) !== (int)$parentId) {
             return redirect()->back()->with('error', 'Report not found.');
         }
+        if ((string) ($row['school_year'] ?? '') !== $schoolYearContext->yearName()) {
+            return redirect()->back()->with('error', 'Report not found for the selected school year.');
+        }
 
         // Only allow editing for 'new' status entries
         $status = (string) ($row['status'] ?? '');

app/Controllers/View/ParentFinancialAidController.php

@@ -0,0 +1,89 @@
+<?php
+
+namespace App\Controllers\View;
+
+use App\Controllers\BaseController;
+use App\Models\ConfigurationModel;
+use App\Models\FinancialAidRequestModel;
+use App\Models\StudentModel;
+
+class ParentFinancialAidController extends BaseController
+{
+    public function index()
+    {
+        $parentId = (int) session()->get('user_id');
+        if ($parentId <= 0) {
+            return redirect()->to('/login');
+        }
+
+        $schoolYear = (string) ((new ConfigurationModel())->getConfig('school_year') ?? '');
+        $model = new FinancialAidRequestModel();
+        $requests = $model
+            ->where('parent_id', $parentId)
+            ->where('school_year', $schoolYear)
+            ->orderBy('id', 'DESC')
+            ->findAll();
+
+        return view('parent/financial_aid', [
+            'schoolYear' => $schoolYear,
+            'requests' => $requests,
+            'openRequest' => $model->openRequestForParent($parentId, $schoolYear),
+            'existingRequest' => $model->requestForParentYear($parentId, $schoolYear),
+        ]);
+    }
+
+    public function submit()
+    {
+        $parentId = (int) session()->get('user_id');
+        if ($parentId <= 0) {
+            return redirect()->to('/login');
+        }
+
+        $schoolYear = (string) ((new ConfigurationModel())->getConfig('school_year') ?? '');
+        $model = new FinancialAidRequestModel();
+        if ($model->requestForParentYear($parentId, $schoolYear) !== null) {
+            return redirect()->back()->with('error', 'You can submit only one financial aid application per school year.');
+        }
+
+        $studentIds = array_map('intval', array_column(
+            (new StudentModel())->select('id')->where('parent_id', $parentId)->findAll(),
+            'id'
+        ));
+        if ($studentIds === []) {
+            return redirect()->back()->withInput()->with('error', 'No students are linked to your account.');
+        }
+
+        $householdIncomeRaw = trim((string) $this->request->getPost('household_income'));
+        if ($householdIncomeRaw === '' || ! is_numeric($householdIncomeRaw) || (float) $householdIncomeRaw < 0) {
+            return redirect()->back()->withInput()->with('error', 'Enter your household income.');
+        }
+
+        $householdSize = (int) $this->request->getPost('household_size');
+        if ($householdSize < 1) {
+            return redirect()->back()->withInput()->with('error', 'Enter your household size.');
+        }
+
+        $requestedAmountRaw = trim((string) $this->request->getPost('requested_amount'));
+        if ($requestedAmountRaw === '' || ! is_numeric($requestedAmountRaw) || (float) $requestedAmountRaw <= 0) {
+            return redirect()->back()->withInput()->with('error', 'Enter the amount you are requesting.');
+        }
+
+        $needStatement = trim((string) $this->request->getPost('need_statement'));
+        if ($needStatement === '') {
+            return redirect()->back()->withInput()->with('error', 'Please describe why you are requesting financial aid.');
+        }
+
+        $model->insert([
+            'parent_id' => $parentId,
+            'school_year' => $schoolYear,
+            'student_ids_json' => json_encode(array_values($studentIds)),
+            'household_size' => $householdSize,
+            'household_income' => round((float) $householdIncomeRaw, 2),
+            'need_statement' => $needStatement,
+            'requested_amount' => round((float) $requestedAmountRaw, 2),
+            'status' => 'submitted',
+        ]);
+
+        return redirect()->to('/parent/financial-aid')->with('success', 'Your financial aid request was submitted.');
+    }
+}

app/Controllers/View/ParticipationController.php

@@ -37,7 +37,7 @@ class ParticipationController extends BaseController
 
         $this->semesterScoreService = service('semesterScoreService');
         $this->schoolYear = $this->configModel->getConfig('school_year');
-        $this->semester = $this->configModel->getConfig('semester');
+        $this->semester = getSemester();
         $this->gradingLockModel = new GradingLockModel();
         $this->missingScoreOverrideModel = new MissingScoreOverrideModel();
     }
@@ -123,7 +123,7 @@ class ParticipationController extends BaseController
             true
         );
 
-        $studentTeacherInfo = $this->studentModel->getStudentInfoByClassSectionId($classSectionId, $semester, $schoolYear);
+        $studentTeacherInfo = $this->studentModel->getActiveStudentInfoByClassSectionId($classSectionId, $semester, $schoolYear);
         // Call the updateScoresForStudents method
         try {
 
@@ -156,7 +156,7 @@ class ParticipationController extends BaseController
 
         session()->setFlashdata('status', 'Participation scores updated successfully.');
 
-        $studentTeacherInfo = $this->studentModel->getStudentInfoByClassSectionId($classSectionId, $semester, $schoolYear);
+        $studentTeacherInfo = $this->studentModel->getActiveStudentInfoByClassSectionId($classSectionId, $semester, $schoolYear);
         // Call the updateScoresForStudents method
         try {
 

app/Controllers/View/PaymentNotificationController.php

@@ -8,6 +8,7 @@ use App\Models\ConfigurationModel;
 use App\Models\InvoiceModel;
 use App\Models\PaymentModel;
 use App\Models\FamilyGuardianModel;
+use App\Libraries\InvoiceLedgerService;
 use App\Services\EmailService;
 use App\Services\NotificationService;
 
@@ -20,6 +21,7 @@ class PaymentNotificationController extends BaseController
     protected PaymentModel $paymentModel;
     protected FamilyGuardianModel $familyGuardianModel;
     protected EmailService $emailService;
+    protected InvoiceLedgerService $invoiceLedgerService;
 
     public function __construct()
     {
@@ -30,6 +32,7 @@ class PaymentNotificationController extends BaseController
         $this->paymentModel = new PaymentModel();
         $this->familyGuardianModel = new FamilyGuardianModel();
         $this->emailService = new EmailService();
+        $this->invoiceLedgerService = new InvoiceLedgerService();
     }
 
     public function index()
@@ -87,43 +90,19 @@ class PaymentNotificationController extends BaseController
         $year = (int)$now->format('Y');
         $month= (int)$now->format('n');
 
-        // Helper: compute current total balance across invoices for this parent/year
         $computeBalance = function (int $pid) use ($schoolYear): array {
             $db = \Config\Database::connect();
             $rows = $db->table('invoices')
-                ->select('id, total_amount')
+                ->select('id')
                 ->where('parent_id', $pid)
                 ->where('school_year', $schoolYear)
                 ->get()->getResultArray();
-            $paymentsTbl = 'payments';
-            $hasStatus   = $db->fieldExists('status', $paymentsTbl);
-            $hasVoid     = $db->fieldExists('is_void', $paymentsTbl);
 
             $sumBalance = 0.0; $latestId = null;
             foreach ($rows as $ir) {
                 $iid = (int)$ir['id'];
                 if ($latestId === null) $latestId = $iid;
-                $total = (float)($ir['total_amount'] ?? 0);
-
-                $qb = $db->table('payments')->select('COALESCE(SUM(paid_amount),0) AS tot')->where('invoice_id', $iid);
-                if ($hasStatus) {
-                    $qb->groupStart()
-                        ->whereNotIn('status', ['void','voided','refunded','failed','chargeback','declined','reversed','canceled','cancelled'])
-                        ->orWhere('status IS NULL', null, false)
-                       ->groupEnd();
-                }
-                if ($hasVoid) {
-                    $qb->groupStart()
-                        ->where('is_void', 0)
-                        ->orWhere('is_void IS NULL', null, false)
-                       ->groupEnd();
-                }
-                $paid = (float)($qb->get()->getRowArray()['tot'] ?? 0);
-
-                $disc = (float)($db->table('discount_usages')->select('COALESCE(SUM(discount_amount),0) AS tot')->where('invoice_id', $iid)->get()->getRowArray()['tot'] ?? 0);
-                $rfnd = (float)($db->table('refunds')->select('COALESCE(SUM(refund_paid_amount),0) AS tot')->where('invoice_id', $iid)->whereIn('status', ['Partial','Paid'])->get()->getRowArray()['tot'] ?? 0);
-
-                $sumBalance += max(0.0, round($total - $disc - $paid - $rfnd, 2));
+                $sumBalance += (float)($this->invoiceLedgerService->calculateInvoice($iid)['balance'] ?? 0.0);
             }
             return [$sumBalance, $latestId];
         };