# App Project Implementation Plan


# Islamic Sunday School Alignment Update

This plan now treats the extension domain as **Islamic Sunday School**, not a generic or church-oriented Sunday School.

The reusable core remains `SchoolCore`. Islamic Sunday School behavior belongs in `IslamicSundaySchool` through contracts, policies, resolvers, read models, and extension profile services.

Core must stay neutral. It must not contain Islamic Sunday School-specific concepts such as Qur'an level, Arabic level, halaqa, masjid family profile, volunteer team, imam/admin notes, Jumu'ah/program session, or Islamic studies track. Those belong in the extension layer.

Preferred namespace:

```text
App\Domain\IslamicSundaySchool
```

Legacy wording using `SundaySchool` should be treated as a migration target and renamed to `IslamicSundaySchool` as code is touched.

---
Generated: 2026-05-29

## 1. Scope and Readout

This plan is based on the uploaded `app/` project slice. The zip contains the Laravel-style application layer, not the full repository. That means routes, migrations, config outside `app/`, composer metadata, tests, CI, frontend assets, and deployment files were not available unless embedded in this directory. So the plan avoids pretending the missing pieces magically exist, a level of honesty software planning could use more often.

### Inventory

- Real project files inspected: **1184**
- PHP files inspected: **1183**
- Approximate PHP LOC: **103,161**
- Controllers: **129**
- Models: **133**
- Services: **386**
- Form requests: **298**
- API resources: **167**
- Middleware: **12**
- Console commands: **14**
- Policies: **10**


## 2. Project Thesis

The app is already organized around a service-heavy backend: controllers orchestrate, request classes validate, resources shape responses, and services carry domain logic. That is the right direction. The weak point is not that the code lacks structure. The weak point is that the project is broad enough for rules to drift across domains unless the boundaries are enforced deliberately.

The plan should therefore optimize for correctness and regression safety, not cosmetic refactors. Refactoring without tests here would be performance art with a stack trace.



## 3. Main Architecture Plan

### Target shape

- Controllers stay thin: authorize, validate, call one service action, return one resource/response.
- Services own business rules and transactions.
- Form requests own validation and request normalization.
- Resources own response shape and avoid leaking internal model structure.
- Policies/Gates own permission checks.
- Events/listeners own async or side-effect workflows, especially communications.
- Console commands remain operational entry points only, not hidden domain logic.

### Global school core with domain extensions

The service layer must be redesigned as a reusable school platform, not as a Islamic Sunday School application with reusable-looking class names. A name like `StudentService` is not modular if it silently assumes masjid/community terms, semester rules, ministry roles, Islamic Sunday School attendance, or a single grading model. That is just hardcoding wearing a blazer.

Target architecture:

```text
app/
  Domain/
    SchoolCore/
      Identity/
      Students/
      Guardians/
      Staff/
      Enrollment/
      Attendance/
      Academics/
      Finance/
      Communication/
      Files/
      Reporting/
      Authorization/
    IslamicSundaySchool/
      Attendance/
      Classes/
      Scripture/
      MinistryRoles/
      LiturgicalCalendar/
      Extensions/
    Shared/
      Contracts/
      DTOs/
      ValueObjects/
      Events/
      Exceptions/
      Support/
```

The `SchoolCore` domain defines generic behavior that any school system can use: students, guardians, staff, enrollment, attendance, classes, grades, invoices, payments, files, communication, and reporting. The `IslamicSundaySchool` domain may extend or configure those behaviors, but it must not leak Islamic Sunday School-specific rules backward into the core.

Required dependency direction:

```text
Controllers -> Application Services -> Domain Contracts -> Infrastructure
IslamicSundaySchool -> SchoolCore
SchoolCore -X-> IslamicSundaySchool
```

The core must never import from `IslamicSundaySchool`. If that rule is broken, the platform is not modular; it is a themed monolith pretending to be reusable because humans enjoy labels.

### Service modularity rules

- Services must expose use-case actions, not generic god-methods. Prefer `RecordPaymentAction`, `EnrollStudentAction`, `MarkAttendanceAction`, `PromoteStudentAction` over giant services with unrelated methods.
- Core services must depend on contracts/interfaces for school-specific rules. Examples: `AttendancePolicy`, `AcademicCalendarProvider`, `GradeScalePolicy`, `TuitionPolicy`, `StudentIdentifierGenerator`, `CommunicationPreferencePolicy`.
- Islamic Sunday School behavior must be implemented as concrete policies/configuration/extensions plugged into those contracts.
- Domain concepts must use neutral names in the core: `ClassGroup`, `AcademicTerm`, `Session`, `Guardian`, `StaffMember`, `AttendanceOccurrence`, `Learner`, `Program`. Islamic Sunday School-specific aliases can exist in the extension layer.
- Every service must declare whether it is `Core`, `Extension`, `Infrastructure`, or `LegacyShim`.
- A service may not read raw request data, return HTTP responses, or know controller/resource classes. That belongs at the API boundary.
- A service may not call unrelated modules directly when a domain event or contract is the safer boundary. Finance should not directly decide messaging behavior; it should emit `PaymentRecorded` and let communication listeners handle notifications.
- All module-specific defaults must come from configuration or policy classes, not hardcoded assumptions.

### Inheritance and extension strategy

Use inheritance sparingly. The Islamic Sunday School concept should inherit from the global project only where the base behavior is stable and narrow. For business rules, prefer composition through policy contracts. Inheritance looks elegant until the third override turns it into a family curse.

Allowed:

```php
interface AttendancePolicy
{
    public function resolveStatus(AttendanceContext $context): AttendanceDecision;
}

final class StandardSchoolAttendancePolicy implements AttendancePolicy {}
final class IslamicSundaySchoolAttendancePolicy implements AttendancePolicy {}
```

Acceptable but limited:

```php
abstract class BaseAttendanceService
{
    final public function mark(AttendanceCommand $command): AttendanceResult
    {
        // shared transaction, audit, idempotency, persistence orchestration
    }

    abstract protected function policy(): AttendancePolicy;
}

final class IslamicSundaySchoolAttendanceService extends BaseAttendanceService
{
    protected function policy(): AttendancePolicy
    {
        return app(IslamicSundaySchoolAttendancePolicy::class);
    }
}
```

Forbidden:

```php
class CoreAttendanceService
{
    public function mark($student, $date)
    {
        if ($student->islamic_sunday_school_class_id) {
            // Islamic Sunday School-specific logic inside core. No.
        }
    }
}
```

### Multi-school reliability model

To make the app usable by any school system, every major record must be scoped to a school, program, or tenant boundary. The plan must verify this before refactoring services, because beautiful modular code that leaks one school’s data to another is still garbage, only now with namespaces.

Required checks:

- Define canonical scope fields: `school_id`, `program_id`, `tenant_id`, or equivalent.
- Every query in core services must apply the correct scope through a shared `SchoolContext`.
- Policies must verify both actor permission and school/program ownership.
- Background jobs, reports, exports, file downloads, and notifications must carry the same context explicitly.
- Add tests proving cross-school isolation for students, guardians, staff, payments, attendance, grades, files, and messages.

### Service package boundaries

Each major service package must have four layers:

1. `Contracts`: interfaces and extension points.
2. `Application`: use-case services/actions and transaction orchestration.
3. `Domain`: value objects, decisions, rules, events, exceptions.
4. `Infrastructure`: Eloquent repositories, storage, mail/SMS providers, external adapters.

Controllers may use Application services only. Application services may use Domain and Contracts. Infrastructure implements Contracts. Domain must not depend on Laravel HTTP, controllers, requests, or resources.


### Non-negotiable rules

- No money-changing action without an explicit transaction, audit trail, idempotency check, and test.
- No attendance, score, promotion, or enrollment mutation without actor tracking and date boundary tests.
- No file endpoint without MIME, size, storage path, authorization, and download-name tests.
- No communication endpoint without recipient preview, opt-out logic, deduplication, and send-log tests.
- No direct request parsing in controllers where a FormRequest already exists or should exist.
- No raw SQL without parameter binding review and a test proving the query behavior.
- No core service may import or reference a Islamic Sunday School namespace, table-specific shortcut, or Islamic Sunday School-specific concept.
- No reusable service is complete until it has a contract, DTO/value object input, authorization boundary, transaction rule, audit rule, and cross-school isolation test.


### Critical Implementation Review Queue

These items override ordinary module cleanup. Do not spend time prettifying controllers while these can still leak data, corrupt money, or create irreversible school records. Charming architectural theater can wait.

#### P0: Must review before feature work

1. **Payment file access authorization**
   - Replace filename-only download access with payment-id-based access.
   - Load the payment/invoice/family context before resolving any file path.
   - Authorize the current actor against the payment record, not against a guessed filename.
   - Resolve the file path only from the stored payment record.
   - Return `403` for unauthorized access and `404` for missing/unknown files.
   - Required tests: finance/admin can download, unrelated parent cannot download, teacher cannot download, guessed filename cannot download, traversal-style filename fails.

2. **Manual payment edit transaction safety**
   - Wrap payment edit and invoice recalculation in one database transaction.
   - Lock the payment row and linked invoice row with `lockForUpdate()` or equivalent.
   - Recompute balance inside the lock.
   - Reject edits that overpay, violate payment method rules, or create invalid invoice state.
   - Store before/after audit details with actor ID.
   - Required tests: concurrent edit, overpayment rejection, audit creation, invoice balance consistency.

3. **Student school ID race condition**
   - Remove pre-insert `max(id) + 1` generation.
   - Create the student first inside a transaction.
   - Generate `school_id` from the persisted student ID or a dedicated sequence.
   - Add a unique database constraint on `students.school_id`.
   - Add retry behavior for rare collisions.
   - Required tests: two concurrent student creations cannot produce duplicate school IDs.

4. **Scanner attendance transaction and idempotency**
   - Split scanner orchestration out of the controller.
   - Wrap all attendance mutations from one scan in a single transaction.
   - Add an idempotency key based on badge/student/staff, scan date, station, and scan window.
   - Prevent duplicate late slips, duplicate scan logs, and double attendance counts.
   - Required tests: duplicate scan, late scan, staff scan, student scan, invalid badge, semester boundary.

5. **Role and permission mutation authorization**
   - Map every role/permission mutation route to a policy or gate.
   - Add wrong-role and wrong-owner negative tests.
   - Log actor, target, old role/permission state, and new state.

6. **Bulk communication recipient safety**
   - Require preview/dry-run before bulk send.
   - Deduplicate recipients by canonical user/contact identity.
   - Respect opt-out and communication preferences.
   - Store send logs and failure states.
   - Required tests: preview count matches send count, duplicate recipients collapse, opted-out recipients excluded.

7. **Refund/payment/invoice audit completeness**
   - Every mutation must record actor, target, amount, old state, new state, source endpoint/job, and idempotency key where applicable.
   - Reports must reconcile against the same canonical ledger behavior as API reads.

8. **Core/extension boundary enforcement**
   - Create a `SchoolCore` service boundary and a separate `IslamicSundaySchool` extension boundary.
   - Move reusable behavior into core contracts/actions.
   - Move Islamic Sunday School-specific assumptions into policies/configuration/listeners.
   - Add a static dependency check that fails if `SchoolCore` imports `IslamicSundaySchool`.
   - Required tests: standard school attendance policy works without Sunday rules, Islamic Sunday School policy overrides only extension points, cross-school data isolation holds.

9. **School context and tenant/program isolation**
   - Introduce a `SchoolContext` or equivalent immutable context object.
   - Require context in every core service command.
   - Apply context to repositories, policies, files, jobs, reports, and notifications.
   - Required tests: actor from School A cannot read or mutate School B students, payments, files, attendance, reports, or messages.

### Module Acceptance Standard

A module is not considered hardened unless:

- every public endpoint has a permission rule;
- every mutation has an audit actor;
- every money, date, file, or message operation has edge-case tests;
- every response shape is documented or represented by an API Resource;
- every side effect is logged;
- every async/send action has retry and dedupe behavior;
- every legacy fallback is documented, quarantined, or removed;
- every controller-level validator has either been moved to a FormRequest or explicitly marked as temporary legacy behavior.
- every core service has been classified as reusable school-core behavior or extension-specific behavior;
- every extension-specific behavior is isolated behind a policy, configuration object, event listener, or adapter;
- every query and mutation has explicit school/program/tenant context;
- every module has at least one cross-school isolation test.


## 4. Evidence-Based Risk Notes

These are not accusations; they are where bugs usually crawl out wearing a tiny hat.

- **Raw SQL / raw query usage:** 59 files, 166 matches.
- **Direct request input access:** 50 files, 194 matches.
- **File operation endpoints:** 18 files, 34 matches.
- **Email or messaging behavior:** 62 files, 192 matches.
- **Auth/Gate/authorization usage:** 325 files, 482 matches.
- **Explicit DB transactions:** 48 files, 72 matches.
- **legacy compatibility surface:** 41 files, 62 matches.
- **Queued or dispatched work:** 7 files, 8 matches.
- **Cache-dependent behavior:** 5 files, 12 matches.


Review priority should follow blast radius: auth, finance, payments, attendance, grading, promotions, messaging, files, then lower-risk CRUD.



## 5. Delivery Phases

### Phase 0: Baseline and Guardrails

- Add a project map document describing module ownership, service boundaries, and route ownership.
- Add static analysis to CI: PHPStan or Larastan, Pint/PHP-CS-Fixer, and a dead-code detector if practical.
- Add a minimal smoke test suite covering auth, health checks, and one representative CRUD module.
- Create fixtures/factories for User, Student, Family, Enrollment, Invoice, Payment, AttendanceRecord, Score, and Staff.
- Freeze API response contracts for critical endpoints with JSON snapshot tests.

### Phase 1: Security and Access Control

- Inventory every controller method and map required role/permission/policy.
- Build an endpoint authorization matrix with actor role, resource type, ownership boundary, action, policy/gate/middleware, and required negative tests.
- Confirm every mutation endpoint uses authorization before business logic.
- Normalize role switching/session timeout behavior and log security-relevant events.
- Review IP ban, login attempts, password reset cleanup, registration captcha, and auth session flows.
- Add negative tests proving unauthorized roles cannot read or mutate cross-family, cross-student, cross-staff, payment, invoice, file, role, or message data.
- Treat “authenticated” as insufficient for any financial, student, attendance, role, file, or communication mutation. Logged in is not allowed; it is merely present, like a bug report with no reproduction steps.

### Phase 2: Financial Correctness

- Define canonical money rules: rounding, currency precision, refund state machine, invoice adjustment rules, and payment reconciliation.
- Decide whether money is stored as integer cents or strict fixed-decimal values; do not use floating-point arithmetic for persistent financial state.
- Wrap invoice/payment/refund/discount/reimbursement mutations in transactions and audit logs.
- Lock invoice/payment/refund rows during balance-changing edits.
- Add idempotency rules to PayPal sync, payment notifications, manual payments, refunds, and invoice generation.
- Replace filename-driven payment file access with record-driven, authorized access.
- Build reconciliation tests: invoice total = tuition + fees + event charges + extras - discounts - refunds - payments.
- Add report consistency tests so PDFs, dashboard totals, and API totals cannot disagree like three humans in a meeting.

### Phase 3: Student Lifecycle Correctness

- Model the lifecycle from registration/enrollment through attendance, grading, report cards, and promotion.
- Add date boundary tests for semesters, attendance windows, class assignment windows, grading locks, and promotion deadlines.
- Centralize student/family visibility checks.
- Make promotion eligibility deterministic and explainable through audit logs.
- Add regression tests for edge cases: missing scores, below-60 notifications, class transfers, inactive students, deleted/unverified users.

### Phase 4: Communications Reliability

- Standardize recipient resolution for Email, Messaging, Notifications, WhatsApp, and BroadcastEmail.
- Require preview/dry-run paths for bulk sends.
- Add send logs, dedupe keys, failure states, and retry strategy.
- Separate composition from delivery.
- Test opt-outs, guardian/family recipient selection, teacher/staff targeting, and notification cleanup.

### Phase 5: Operations and Reporting

- Review PDF generation paths for badges, certificates, finance reports, report cards, slips, stickers, and print requests.
- Validate all file downloads and upload paths.
- Add operational health endpoints for database, config, cleanup scheduler, and time-sensitive jobs.
- Add runbooks for cleanup commands, payment sync, attendance publishing, and notification dispatch.

### Phase 6: Documentation and API Contracts

- Generate OpenAPI output from route definitions, once routes are included.
- Document each module: owner, purpose, inputs, outputs, permissions, side effects, and failure modes.
- Document legacy compatibility areas explicitly, especially legacy adapters and helper shims.
- Add API examples for primary user flows: login, role switch, parent dashboard, attendance submission, invoice payment, grading submission.



## 5A. Modular Platform Refactor Plan

This section converts the app from a Sunday-school-shaped backend into a reusable school platform with a Islamic Sunday School implementation layered on top. Do this incrementally. A big-bang rewrite would be a bonfire with sprint ceremonies.

### Phase A: Classify services

Create a service inventory with these labels:

- `Core`: reusable for any school.
- `IslamicSundaySchoolExtension`: specific to Islamic Sunday School rules, religious calendar, ministry roles, Islamic Sunday School attendance, scripture/curriculum assumptions, masjid-family/community structures, or parish-specific reporting.
- `Infrastructure`: storage, Eloquent, mail, SMS/WhatsApp, PDF, exports, payment gateways, QR/scanner hardware.
- `LegacyShim`: compatibility wrapper pending removal.

Acceptance criteria:

- Every service has a classification.
- No `Core` service contains Islamic Sunday School-specific vocabulary or table assumptions.
- Duplicate services are marked canonical/shim/deprecated.
- CI/static check prevents new dependencies from `SchoolCore` to `IslamicSundaySchool`.

### Phase B: Introduce core commands and DTOs

Replace array-shaped service calls with typed command objects. Arrays are flexible, which is another word for “bugs can hide anywhere.”

Examples:

```php
final readonly class EnrollStudentCommand
{
    public function __construct(
        public SchoolContext $context,
        public ActorId $actorId,
        public StudentProfileData $student,
        public GuardianDataCollection $guardians,
        public EnrollmentProgramId $programId,
    ) {}
}
```

Acceptance criteria:

- High-risk actions use command objects: payments, enrollment, attendance, promotion, grading, messaging, file access.
- Commands include `SchoolContext` and `ActorId`.
- Services return result DTOs, not HTTP responses.

### Phase C: Extract policy contracts

Create extension contracts for behavior likely to differ across school types:

```text
AttendancePolicy
AcademicCalendarProvider
GradeScalePolicy
PromotionPolicy
TuitionPolicy
PaymentAllocationPolicy
StudentIdentifierGenerator
GuardianRelationshipPolicy
CommunicationPreferencePolicy
ReportCardTemplateProvider
FileAccessPolicy
```

Acceptance criteria:

- Core services call contracts, not Islamic Sunday School-specific classes.
- Islamic Sunday School supplies concrete implementations.
- A basic non-Sunday `StandardSchool` implementation can run core tests.

### Phase D: Split domain modules

Refactor toward these stable core modules:

```text
SchoolCore\Identity
SchoolCore\Students
SchoolCore\Guardians
SchoolCore\Staff
SchoolCore\Enrollment
SchoolCore\Attendance
SchoolCore\Academics
SchoolCore\Finance
SchoolCore\Communication
SchoolCore\Files
SchoolCore\Reporting
SchoolCore\Authorization
```

Islamic Sunday School-specific modules should live separately:

```text
IslamicSundaySchool\Attendance
IslamicSundaySchool\Classes
IslamicSundaySchool\Curriculum
IslamicSundaySchool\MinistryRoles
IslamicSundaySchool\FamilyMasjidProfile
IslamicSundaySchool\Reports
```

Acceptance criteria:

- Core modules can be tested without booting Islamic Sunday School-specific providers.
- Islamic Sunday School modules depend on core contracts/actions.
- Shared events are neutral: `StudentEnrolled`, `AttendanceMarked`, `PaymentRecorded`, not `SundayStudentCheckedIn`.

### Phase E: Add cross-school isolation tests

For every reusable module, add tests for:

- School A actor cannot access School B records.
- Reports filter by context.
- Files cannot be guessed across schools.
- Background jobs preserve context.
- Notifications send only to recipients in context.

This is not optional. Multi-school systems fail here first, then everyone acts surprised, as if databases spontaneously developed opinions.

### Phase F: Introduce extension registration

Use a service provider or module registry to bind school-type implementations:

```php
final class IslamicSundaySchoolServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(AttendancePolicy::class, IslamicSundaySchoolAttendancePolicy::class);
        $this->app->bind(AcademicCalendarProvider::class, IslamicSundaySchoolCalendarProvider::class);
        $this->app->bind(StudentIdentifierGenerator::class, IslamicSundaySchoolStudentIdentifierGenerator::class);
    }
}
```

Acceptance criteria:

- Extension bindings are centralized.
- Core defaults exist for generic school behavior.
- Tests can swap policy implementations without changing core services.

### Phase G: Migration strategy

Do not rewrite everything at once. Use strangler-style migration:

1. Pick one high-risk module: Attendance or Finance.
2. Define core contracts and commands.
3. Wrap legacy service behind the new contract if needed.
4. Add tests against the contract.
5. Move Islamic Sunday School-specific logic into an extension policy.
6. Replace controller calls with the new application action.
7. Delete or quarantine the old path after route parity is proven.

Success metric: a generic school implementation can run the same service tests with different policies.

## 6. Module-by-Module Plan

Each module gets the same discipline: define ownership, confirm validation, confirm authorization, isolate service logic, test happy paths and failures, document side effects.



### Admin

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 2 services, 3 requests, 5 resources.

**Services:** CompetitionWinnersDomain, CompetitionWinnersAdminService
**Requests:** StoreCompetitionWinnerRequest, UpdateCompetitionWinnerRequest, SaveCompetitionScoresRequest
**Resources:** PrintRecipientsResource, TeacherSubmissionReportResource, AdminNotificationAlertsResource, ProgressGroupResource, ProgressReportDetailResource
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### Administrator

**Priority:** P2/P3 Feature hardening
**Detected surface:** 8 controllers, 18 services, 5 requests, 0 resources.

**Controllers:** AdministratorAbsenceController, AdministratorDashboardController, AdministratorEnrollmentController, AdministratorNotificationController, AdministratorPromotionController, AdministratorTeacherSubmissionController, EmergencyContactController, TeacherClassAssignmentController
**Services:** AdministratorUserSearchService, AdministratorAbsenceService, AdministratorDashboardService, AdministratorMetricsService, AdministratorEnrollmentStatusService, AdministratorEnrollmentEventService, AdministratorNotificationService, AdminNotificationSubjectService, TeacherSubmissionSupportService, AdministratorSharedService, TeacherSubmissionNotificationService, TeacherSubmissionReportService ...
**Requests:** SavePrintRecipientsRequest, SaveAdminNotificationSubjectsRequest, SubmitAdministratorAbsenceRequest, UpdateEnrollmentStatusesRequest, SendTeacherSubmissionNotificationsRequest
**Plan:**
- Centralize identity lookup and cross-entity authorization.
- Test directory/search pagination and visibility filtering.
- Ensure updates cannot orphan related records or break family/student/staff links.
- Add lifecycle tests for active, inactive, newly enrolled, transferred, and deleted/unverified users.

### Api

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 0 services, 4 requests, 0 resources.

**Requests:** SaveAdminNotificationSubjectsRequest, IndexAdminProgressRequest, SendTeacherSubmissionNotificationsRequest, SavePrintNotificationRecipientsRequest
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### ApiRoot

**Priority:** P2/P3 Feature hardening
**Detected surface:** 7 controllers, 0 services, 0 requests, 0 resources.

**Controllers:** BaseApiController, request adapter, RolePermissionController, RoleSwitcherController, ScannerController, StatsController, UserController
**Plan:**
- Quarantine legacy/root controllers and define canonical replacements for duplicate controller names.
- Split `ScannerController` into a FormRequest, scanner orchestration service, badge lookup service, student scan service, staff scan service, late-arrival service, scan logger, and response factory.
- Add transaction boundaries and idempotency around scanner attendance mutations.
- Define whether `BaseApiController`, `request adapter`, root role controllers, and namespaced role controllers are canonical or shims.
- Ensure shim classes contain no business logic.
- Add feature tests for scanner flows, role switching, stats visibility, and user visibility.

#### Scanner refactor acceptance criteria

- One public scan endpoint delegates to one scanner service action.
- All scan input is validated through a dedicated FormRequest.
- A duplicate scan within the configured duplicate window does not double-count attendance or create duplicate late-slip records.
- Student and staff scan paths have separate service-level tests.
- Scan logs are written once per accepted mutation and include actor/station/source context.

### Assignment

**Priority:** P2/P3 Feature hardening
**Detected surface:** 1 controllers, 5 services, 2 requests, 2 resources.

**Controllers:** AssignmentApiController
**Services:** AssignmentSectionService, AssignmentMetaService, AssignmentService, AssignmentContextService, AssignmentDataLoaderService
**Requests:** StoreAssignmentRequest, StoreStudentAssignmentRequest
**Resources:** AssignmentOverviewResource, AssignmentSectionResource
**Plan:**
- Define the academic workflow state machine and valid transitions.
- Test teacher/admin/parent role boundaries.
- Protect uploads and generated academic files.
- Add audit logs for status changes, submissions, and deadline changes.

### Attendance

**Priority:** P1 Student lifecycle
**Detected surface:** 6 controllers, 16 services, 7 requests, 7 resources.

**Controllers:** AdminAttendanceApiController, AttendanceCommentTemplateController, EarlyDismissalsController, LateSlipLogsController, StaffAttendanceApiController, TeacherAttendanceApiController
**Services:** SemesterRangeService, TeacherAttendanceSubmissionService, AttendanceAutoPublishJobService, AttendanceAutoPublishService, LateSlipLogQueryService, AttendanceConsequenceService, AttendanceRecordSyncService, AttendanceDailySummaryService, AttendanceService, StudentAttendanceWriterService, LateSlipLogCommandService, AttendanceSummaryRebuildService ...
**Requests:** SaveStaffAttendanceCellRequest, UpdateAttendanceManagementRequest, LateSlipLogIndexRequest, TeacherSubmitAttendanceRequest, SaveAdminAttendanceRequest, TeacherUpdateGridRequest, AdminAddAttendanceEntryRequest
**Resources:** DailyAttendanceResource, AdminAttendanceResource, LateSlipLogCollection, LateSlipLogResource, TeacherGridResource, StaffMonthResource, TeacherAttendanceFormResource
**Plan:**
- Lock down date and semester boundary behavior before changing implementation.
- Test teacher/admin/parent visibility separately.
- Ensure auto-publish, notification, late slip, early dismissal, scanner scan, and violation rules are deterministic.
- Record who changed attendance, when, station/source context when relevant, and why.
- Move scan-driven attendance mutations into transactional services shared by scanner and attendance modules where appropriate.
- Add idempotency tests for repeated scanner submissions and repeated auto-publish attempts.

### AttendanceCommentTemplate

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 0 services, 2 requests, 0 resources.

**Requests:** StoreAttendanceCommentTemplateRequest, UpdateAttendanceCommentTemplateRequest
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### AttendanceTracking

**Priority:** P1 Student lifecycle
**Detected surface:** 1 controllers, 12 services, 5 requests, 0 resources.

**Controllers:** AttendanceTrackingController
**Services:** AttendanceNotificationLogService, AttendanceViolationStudentResolverService, AttendanceNotificationWorkflowService, AttendanceTrackingService, ViolationRuleEngineService, AttendanceMailerService, AttendanceParentLookupService, AttendanceCommunicationSupportService, AttendanceEmailComposerService, AttendancePendingViolationService, AttendanceCaseQueryService, DefaultAttendanceMailerService
**Requests:** RecordAttendanceTrackingRequest, ComposeAttendanceEmailRequest, SendAttendanceManualEmailRequest, ParentsInfoRequest, SaveAttendanceNotificationNoteRequest
**Plan:**
- Lock down date and semester boundary behavior before changing implementation.
- Test teacher/admin/parent visibility separately.
- Ensure auto-publish, notification, late slip, early dismissal, and violation rules are deterministic.
- Record who changed attendance, when, and why.

### Auth

**Priority:** P0 Security/Foundation
**Detected surface:** 7 controllers, 9 services, 3 requests, 1 resources.

**Controllers:** AuthController, AuthSessionController, IpBanController, RegisterController, RolePermissionController, RoleSwitcherController, SessionTimeoutController
**Services:** RegistrationCaptchaService, PermissionCheckService, ApiRegistrationService, RegistrationService, ApiLoginSecurityService, AuthSessionService, UserRoleService, PasswordResetCleanupService, RegistrationFormatterService
**Requests:** RegisterRequest, SetRoleSessionRequest, LoginSessionRequest
**Resources:** RegisterResource
**Plan:**
- Map every endpoint to required auth state, role, and permission.
- Test login throttling, IP bans, password reset cleanup, session timeout, role switching, and registration captcha.
- Confirm security logs include actor, IP, user agent, outcome, and reason.
- Reject role changes that create privilege escalation or stale-session leaks.

### BadgeScan

**Priority:** P2/P3 Feature hardening
**Detected surface:** 1 controllers, 1 services, 0 requests, 0 resources.

**Controllers:** BadgeScanController
**Services:** BadgeScanService
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### Badges

**Priority:** P2 Operations
**Detected surface:** 1 controllers, 7 services, 3 requests, 0 resources.

**Controllers:** BadgeController
**Services:** BadgeTextFormatter, BadgeStudentLookupService, BadgeFormDataService, BadgePdfService, BadgeUserLookupService, BadgeService, BadgePrintLogService
**Requests:** BadgePrintStatusRequest, GenerateBadgePdfRequest, LogBadgePrintRequest
**Plan:**
- Review upload/download/PDF generation permissions.
- Validate file type, file size, generated names, and storage paths.
- Add tests for inventory movement consistency and purchase-order state transitions where applicable.
- Make printable outputs reproducible from stable data snapshots.

### Billing

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 3 services, 0 requests, 0 resources.

**Services:** BalanceCalculationService, BillingTotalsService, ChargeService
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### BroadcastEmail

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 5 services, 0 requests, 0 resources.

**Services:** BroadcastEmailComposerService, BroadcastEmailRecipientService, BroadcastEmailDispatchService, BroadcastEmailImageService, BroadcastEmailSenderOptionsService
**Plan:**
- Separate recipient selection, message composition, dispatch, and logging.
- Add preview/dry-run tests before bulk sending.
- Deduplicate sends and persist failure states.
- Verify opt-outs, guardian selection, role targeting, and retry behavior.

### Certificates

**Priority:** P2/P3 Feature hardening
**Detected surface:** 1 controllers, 1 services, 0 requests, 0 resources.

**Controllers:** CertificateController
**Services:** CertificatePdfService
**Plan:**
- Review upload/download/PDF generation permissions.
- Validate file type, file size, generated names, and storage paths.
- Add tests for inventory movement consistency and purchase-order state transitions where applicable.
- Make printable outputs reproducible from stable data snapshots.

### ClassPrep

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 2 services, 0 requests, 0 resources.

**Services:** ClassRosterService, StickerCountService
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### ClassPreparation

**Priority:** P2/P3 Feature hardening
**Detected surface:** 1 controllers, 9 services, 4 requests, 2 resources.

**Controllers:** ClassPreparationController
**Services:** ClassPreparationAdjustmentWriterService, ClassPreparationCalculatorService, ClassPreparationLogService, ClassPreparationAdjustmentService, ClassPreparationContextService, ClassPreparationService, ClassPreparationPrintService, ClassPreparationRosterService, ClassPreparationInventoryService
**Requests:** ClassPreparationMarkPrintedRequest, ClassPreparationPrintRequest, ClassPreparationIndexRequest, ClassPreparationAdjustmentRequest
**Resources:** ClassPreparationPrintResource, ClassPreparationResultResource
**Plan:**
- Define the academic workflow state machine and valid transitions.
- Test teacher/admin/parent role boundaries.
- Protect uploads and generated academic files.
- Add audit logs for status changes, submissions, and deadline changes.

### ClassProgress

**Priority:** P2/P3 Feature hardening
**Detected surface:** 1 controllers, 5 services, 5 requests, 4 resources.

**Controllers:** ClassProgressController
**Services:** ClassProgressRuleService, ClassProgressAttachmentService, ClassProgressQueryService, ClassProgressMetaService, ClassProgressMutationService
**Requests:** ClassProgressStoreRequest, ClassProgressMetaRequest, ClassProgressIndexRequest, ClassProgressFormRequest, ClassProgressUpdateRequest
**Resources:** ClassProgressGroupCollection, ClassProgressAttachmentResource, ClassProgressShowResource, ClassProgressReportResource
**Plan:**
- Define the academic workflow state machine and valid transitions.
- Test teacher/admin/parent role boundaries.
- Protect uploads and generated academic files.
- Add audit logs for status changes, submissions, and deadline changes.

### ClassSections

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 4 services, 0 requests, 0 resources.

**Services:** ClassSectionCommandService, ClassAttendanceService, ClassSectionSeedService, ClassSectionQueryService
**Plan:**
- Define the academic workflow state machine and valid transitions.
- Test teacher/admin/parent role boundaries.
- Protect uploads and generated academic files.
- Add audit logs for status changes, submissions, and deadline changes.

### Classes

**Priority:** P2/P3 Feature hardening
**Detected surface:** 1 controllers, 0 services, 3 requests, 4 resources.

**Controllers:** ClassController
**Requests:** ClassSectionUpdateRequest, ClassSectionStoreRequest, ClassSectionIndexRequest
**Resources:** ClassSectionCollection, ClassSectionResource, ClassAttendanceResource, ClassAttendanceStudentResource
**Plan:**
- Define the academic workflow state machine and valid transitions.
- Test teacher/admin/parent role boundaries.
- Protect uploads and generated academic files.
- Add audit logs for status changes, submissions, and deadline changes.

### Communication

**Priority:** P1 Communications
**Detected surface:** 1 controllers, 6 services, 0 requests, 0 resources.

**Controllers:** CommunicationController
**Services:** CommunicationFamilyService, CommunicationSendService, CommunicationTemplateService, CommunicationPreviewService, CommunicationStudentService, CommunicationLogService
**Plan:**
- Separate recipient selection, message composition, dispatch, and logging.
- Add preview/dry-run tests before bulk sending.
- Deduplicate sends and persist failure states.
- Verify opt-outs, guardian selection, role targeting, and retry behavior.

### CompetitionScores

**Priority:** P2/P3 Feature hardening
**Detected surface:** 1 controllers, 4 services, 0 requests, 0 resources.

**Controllers:** CompetitionScoresController
**Services:** CompetitionScoresRosterService, CompetitionScoresSaveService, CompetitionScoresContextService, CompetitionScoresQueryService
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### Core

**Priority:** P2/P3 Feature hardening
**Detected surface:** 2 controllers, 0 services, 0 requests, 0 resources.

**Controllers:** BaseApiController, request adapter
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### Dashboard

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 1 services, 0 requests, 0 resources.

**Services:** DashboardRouteService
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### Discounts

**Priority:** P0 Financial correctness
**Detected surface:** 1 controllers, 5 services, 3 requests, 2 resources.

**Controllers:** DiscountController
**Services:** DiscountParentService, DiscountApplyService, DiscountInvoiceService, DiscountVoucherService, DiscountContextService
**Requests:** UpdateDiscountVoucherRequest, ApplyDiscountVoucherRequest, StoreDiscountVoucherRequest
**Resources:** DiscountVoucherResource, DiscountParentResource
**Plan:**
- Define one source of truth for monetary calculations and rounding.
- Require transactions around every mutation that changes balance, invoice state, refund state, payment state, or reimbursement status.
- Add audit logs and idempotency keys for external payment/payment-notification flows.
- Build reconciliation tests across API, reports, dashboards, and PDFs.

### Docs

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 3 services, 0 requests, 0 resources.

**Services:** DocsCatalogService, ApiDocsService, OpenApiRouteExporter
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### Documentation

**Priority:** P2/P3 Feature hardening
**Detected surface:** 2 controllers, 0 services, 0 requests, 0 resources.

**Controllers:** ApiDocsAdminController, DocsCatalogController
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### Email

**Priority:** P1 Communications
**Detected surface:** 3 controllers, 5 services, 2 requests, 3 resources.

**Controllers:** BroadcastEmailController, EmailController, EmailExtractorController
**Services:** EmailAttachmentService, EmailExtractorService, EmailProfileService, EmailDispatchService, EmailSenderOptionsService
**Requests:** EmailExtractorCompareRequest, EmailSendRequest
**Resources:** EmailSenderResource, EmailExtractorEmailsResource, EmailExtractorCompareResource
**Plan:**
- Separate recipient selection, message composition, dispatch, and logging.
- Add preview/dry-run tests before bulk sending.
- Deduplicate sends and persist failure states.
- Verify opt-outs, guardian selection, role targeting, and retry behavior.

### EmergencyContacts

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 2 services, 2 requests, 3 resources.

**Services:** EmergencyContactDirectoryService, EmergencyContactCrudService
**Requests:** EmergencyContactParentRequest, EmergencyContactUpdateRequest
**Resources:** EmergencyContactGroupResource, EmergencyContactStudentResource, EmergencyContactResource
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### Events

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 6 services, 6 requests, 3 resources.

**Services:** EventChargeService, EventStudentChargeService, EventCategoryService, EventListService, EventChargeQueryService, EventManagementService
**Requests:** EventIndexRequest, EventUpdateRequest, EventStoreRequest, EventStudentsWithChargesRequest, EventChargeUpdateRequest, EventChargeIndexRequest
**Resources:** EventChargeResource, EventResource, EventStudentChargeResource
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### Exams

**Priority:** P2/P3 Feature hardening
**Detected surface:** 1 controllers, 4 services, 3 requests, 1 resources.

**Controllers:** ExamDraftController
**Services:** ExamDraftTeacherService, ExamDraftAdminService, ExamDraftConfigService, ExamDraftFileService
**Requests:** ExamDraftTeacherStoreRequest, ExamDraftAdminLegacyRequest, ExamDraftAdminReviewRequest
**Resources:** ExamDraftResource
**Plan:**
- Define the academic workflow state machine and valid transitions.
- Test teacher/admin/parent role boundaries.
- Protect uploads and generated academic files.
- Add audit logs for status changes, submissions, and deadline changes.

### Expenses

**Priority:** P0 Financial correctness
**Detected surface:** 1 controllers, 7 services, 3 requests, 2 resources.

**Controllers:** ExpenseController
**Services:** ExpenseQueryService, ExpenseStaffService, ExpenseRetailorService, ExpenseReceiptService, ExpenseWriteService, ExpenseContextService, ExpenseStatusService
**Requests:** UpdateExpenseRequest, StoreExpenseRequest, UpdateExpenseStatusRequest
**Resources:** ExpenseResource, ExpenseStaffResource
**Plan:**
- Define one source of truth for monetary calculations and rounding.
- Require transactions around every mutation that changes balance, invoice state, refund state, payment state, or reimbursement status.
- Add audit logs and idempotency keys for external payment/payment-notification flows.
- Build reconciliation tests across API, reports, dashboards, and PDFs.

### ExtraCharges

**Priority:** P0 Financial correctness
**Detected surface:** 1 controllers, 6 services, 2 requests, 3 resources.

**Controllers:** ExtraChargesController
**Services:** ExtraChargesMetaService, ExtraChargesInvoiceService, ExtraChargesParentService, ExtraChargesChargeService, ExtraChargesContextService, ExtraChargesListService
**Requests:** UpdateExtraChargeRequest, StoreExtraChargeRequest
**Resources:** ExtraChargeInvoiceOptionResource, ExtraChargeResource, ExtraChargeParentOptionResource
**Plan:**
- Define one source of truth for monetary calculations and rounding.
- Require transactions around every mutation that changes balance, invoice state, refund state, payment state, or reimbursement status.
- Add audit logs and idempotency keys for external payment/payment-notification flows.
- Build reconciliation tests across API, reports, dashboards, and PDFs.

### Families

**Priority:** P1 Student lifecycle
**Detected surface:** 0 controllers, 4 services, 14 requests, 7 resources.

**Services:** FamilyNotificationService, FamilyFinanceService, FamilyMutationService, FamilyQueryService
**Requests:** FamilyImportLegacyRequest, FamilyUnlinkStudentRequest, FamilySetPrimaryHomeRequest, FamilyAdminCardRequest, FamiliesByStudentRequest, FamilyBootstrapRequest, FamilyAttachSecondByEmailRequest, FamilyAdminSearchRequest ...
**Resources:** FamilyPaymentResource, FamilyInvoiceResource, FamilySearchItemResource, FamilyResource, FamilyGuardianResource, FamilyStudentResource, FamilyEmergencyContactResource
**Plan:**
- Centralize identity lookup and cross-entity authorization.
- Test directory/search pagination and visibility filtering.
- Ensure updates cannot orphan related records or break family/student/staff links.
- Add lifecycle tests for active, inactive, newly enrolled, transferred, and deleted/unverified users.

### Family

**Priority:** P2/P3 Feature hardening
**Detected surface:** 2 controllers, 0 services, 0 requests, 0 resources.

**Controllers:** FamilyAdminController, FamilyController
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### Fees

**Priority:** P0 Financial correctness
**Detected surface:** 0 controllers, 6 services, 2 requests, 6 resources.

**Services:** FeeConfigService, TuitionCalculationService, FeeRefundCalculatorService, FeeGradeService, FeeRefundDetailService, FeeStudentFeeService
**Requests:** FeeTuitionTotalRequest, FeeRefundRequest
**Resources:** FeeRefundResource, FeeFamilyBalanceResource, ChargeActionResource, ChargeListResource, FeeTuitionBreakdownResource, FeeTuitionTotalResource
**Plan:**
- Define one source of truth for monetary calculations and rounding.
- Require transactions around every mutation that changes balance, invoice state, refund state, payment state, or reimbursement status.
- Add audit logs and idempotency keys for external payment/payment-notification flows.
- Build reconciliation tests across API, reports, dashboards, and PDFs.

### Files

**Priority:** P2 Operations
**Detected surface:** 0 controllers, 2 services, 1 requests, 1 resources.

**Services:** FileServeService, ExamDraftDownloadNameService
**Requests:** FileNameRequest
**Resources:** FileMetaResource
**Plan:**
- Review upload/download/PDF generation permissions.
- Validate file type, file size, generated names, and storage paths.
- Add tests for inventory movement consistency and purchase-order state transitions where applicable.
- Make printable outputs reproducible from stable data snapshots.

### Finance

**Priority:** P0 Financial correctness
**Detected surface:** 14 controllers, 8 services, 12 requests, 9 resources.

**Controllers:** ChargeController, FeeCalculationController, FinancialController, InvoiceController, PaymentController, PaymentEventChargesController, PaymentManualController, PaymentNotificationController, PaymentTransactionController, PaypalPaymentController ...
**Services:** FinancialPdfReportService, FinancialSchoolYearService, FinancialPaymentService, FinancialReportService, FinancialSummaryService, FinancialChartService, FinancialDonationRecipientService, FinancialUnpaidParentsService
**Requests:** FinancialUnpaidParentsRequest, FeeTuitionTotalRequest, ChargeListRequest, FinancialReportRequest, FinancialSummaryRequest, MarkEventChargePaidRequest, FeeTuitionBreakdownRequest, StoreExtraChargeRequest ...
**Resources:** FinancialReportResource, FinancialSummaryResource, FinancialExpenseSummaryResource, FinancialInvoiceResource, FinancialPaymentResource, FinancialRefundResource, FinancialUnpaidParentResource, FinancialDiscountResource ...
**Plan:**
- Define one source of truth for monetary calculations and rounding.
- Require transactions around every mutation that changes balance, invoice state, refund state, payment state, or reimbursement status.
- Add audit logs and idempotency keys for external payment/payment-notification flows.
- Harden payment file access before any broader finance refactor: no filename-only authorization, no arbitrary file resolution, no unaudited downloads.
- Lock affected invoice/payment/refund/reimbursement rows during edits and recalculations.
- Normalize all finance responses through resources so dashboards, APIs, reports, and PDFs do not compute separate truths, because apparently one truth was not complicated enough.
- Build reconciliation tests across API, reports, dashboards, and PDFs.

#### Finance P0 acceptance criteria

- Manual payment create/edit/delete and invoice recalculation run inside transactions.
- Payment edits create before/after audit records.
- Payment file downloads are authorized by payment/invoice ownership or finance role.
- Wrong-role and wrong-owner tests exist for invoices, payments, refunds, reimbursements, and downloadable files.
- All finance mutation tests assert final ledger/invoice balance, not just HTTP status.

### Frontend

**Priority:** P2/P3 Feature hardening
**Detected surface:** 4 controllers, 9 services, 2 requests, 6 resources.

**Controllers:** FrontendController, InfoIconController, LandingPageController, PageController
**Services:** LandingPageTeacherSummaryService, LandingPageRoleService, LandingPageParentDashboardService, LandingPageService, StaticPageService, FrontendPageService, ContactSubmissionService, LandingPageContextService, ProfileIconService
**Requests:** LandingTeacherRequest, ContactSubmitRequest
**Resources:** LandingPageResource, ContactSubmissionResource, FrontendPageResource, FrontendUserResource, ProfileIconResource, PageContentResource
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### Grading

**Priority:** P1 Student lifecycle
**Detected surface:** 2 controllers, 9 services, 18 requests, 3 resources.

**Controllers:** GradingController, HomeworkTrackingController
**Services:** BelowSixtyEmailService, GradingLockService, GradingOverviewService, GradingPlacementService, HomeworkTrackingService, GradingScoreService, GradingBelowSixtyService, HomeworkTrackingCalendarService, GradingRefreshService
**Requests:** BelowSixtyListRequest, BelowSixtySendRequest, GradingLockAllRequest, BelowSixtyMeetingRequest, PlacementLevelsRequest, GradingRefreshRequest, GradingScoreShowRequest, HomeworkTrackingRequest ...
**Resources:** BelowSixtyStudentResource, GradingScoreResource, HomeworkTrackingTeacherResource
**Plan:**
- Centralize score formulas and missing-score behavior.
- Add golden test cases for semester score, quiz, homework, project, participation, final/midterm, and prediction risk calculations.
- Prove grading locks block writes but not allowed reads.
- Verify below-60 communication and parent visibility rules.

### Incidents

**Priority:** P2/P3 Feature hardening
**Detected surface:** 1 controllers, 4 services, 5 requests, 4 resources.

**Controllers:** IncidentController
**Services:** CurrentIncidentService, IncidentHistoryService, IncidentLookupService, IncidentAnalysisService
**Requests:** IncidentCancelRequest, IncidentCloseRequest, IncidentStoreRequest, IncidentListRequest, IncidentStateRequest
**Resources:** IncidentStudentOptionResource, IncidentAnalysisStudentResource, IncidentResource, IncidentGradeResource
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### Inventory

**Priority:** P2 Operations
**Detected surface:** 5 controllers, 8 services, 19 requests, 5 resources.

**Controllers:** InventoryCategoryController, InventoryController, InventoryMovementController, SupplierController, SupplyCategoryController
**Services:** InventorySummaryService, InventoryCategoryService, InventoryItemService, InventoryContextService, SupplierService, InventoryMovementService, SupplyCategoryService, InventoryTeacherDistributionService
**Requests:** InventoryItemIndexRequest, SupplierUpdateRequest, InventoryCategoryStoreRequest, InventoryTeacherDistributionRequest, InventoryItemUpdateRequest, InventoryItemStoreRequest, InventoryTeacherDistributionStoreRequest, InventoryCategoryUpdateRequest ...
**Resources:** InventoryItemResource, InventoryCategoryResource, InventoryMovementResource, SupplierResource, SupplyCategoryResource
**Plan:**
- Review upload/download/PDF generation permissions.
- Validate file type, file size, generated names, and storage paths.
- Add tests for inventory movement consistency and purchase-order state transitions where applicable.
- Make printable outputs reproducible from stable data snapshots.

### Invoices

**Priority:** P0 Financial correctness
**Detected surface:** 0 controllers, 8 services, 4 requests, 2 resources.

**Services:** InvoiceGradeService, InvoiceConfigService, InvoicePaymentService, InvoiceTuitionService, InvoiceManagementService, InvoicePdfService, InvoiceService, InvoiceGenerationService
**Requests:** InvoiceStatusRequest, InvoiceManagementRequest, InvoiceParentRequest, InvoiceGenerateRequest
**Resources:** InvoiceManagementParentResource, InvoiceResource
**Plan:**
- Define one source of truth for monetary calculations and rounding.
- Require transactions around every mutation that changes balance, invoice state, refund state, payment state, or reimbursement status.
- Add audit logs and idempotency keys for external payment/payment-notification flows.
- Build reconciliation tests across API, reports, dashboards, and PDFs.

### Messaging

**Priority:** P1 Communications
**Detected surface:** 2 controllers, 3 services, 3 requests, 3 resources.

**Controllers:** MessagesController, WhatsappController
**Services:** MessageRecipientService, MessageCommandService, MessageQueryService
**Requests:** MessageSendRequest, MessageIndexRequest, MessageUpdateRequest
**Resources:** MessageResource, MessageCollection, RecipientResource
**Plan:**
- Separate recipient selection, message composition, dispatch, and logging.
- Add preview/dry-run tests before bulk sending.
- Deduplicate sends and persist failure states.
- Verify opt-outs, guardian selection, role targeting, and retry behavior.

### Navigation

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 2 services, 0 requests, 0 resources.

**Services:** NavBuilderService, NavbarService
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### NonApi

**Priority:** P2/P3 Feature hardening
**Detected surface:** 3 controllers, 0 services, 0 requests, 0 resources.

**Controllers:** Controller, DocsController, TeacherCalendarPageController
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### Notifications

**Priority:** P1 Communications
**Detected surface:** 1 controllers, 12 services, 5 requests, 2 resources.

**Controllers:** NotificationController
**Services:** NotificationDispatchService, NotificationRecipientService, NotificationShowService, NotificationManagementService, NotificationReadService, NotificationUserListService, NotificationCleanupService, UserNotificationDispatchService, NotificationTriggerService, NotificationSendService, NotificationActiveService, NotificationDeletedService
**Requests:** NotificationSendRequest, NotificationActiveRequest, NotificationDeletedRequest, NotificationUpdateRequest, NotificationIndexRequest
**Resources:** UserNotificationResource, NotificationResource
**Plan:**
- Separate recipient selection, message composition, dispatch, and logging.
- Add preview/dry-run tests before bulk sending.
- Deduplicate sends and persist failure states.
- Verify opt-outs, guardian selection, role targeting, and retry behavior.

### Parents

**Priority:** P1 Student lifecycle
**Detected surface:** 5 controllers, 14 services, 16 requests, 4 resources.

**Controllers:** AuthorizedUserInviteController, AuthorizedUsersController, ParentAttendanceReportController, ParentController, ParentPromotionController
**Services:** ParentEventParticipationService, ParentRegistrationService, PrimaryParentUserResolver, ParentAttendanceReportCalendarService, ParentAttendanceService, AuthorizedUsersManagementService, ParentEnrollmentService, ParentInvoiceService, ParentProgressQueryService, ParentAttendanceReportService, ParentReportCardService, ParentConfigService ...
**Requests:** ParentAttendanceReportUpdateRequest, ParentAttendanceReportListRequest, ParentAttendanceReportSubmitRequest, ParentEmergencyContactRequest, UpdateAuthorizedUserRequest, ParentAttendanceReportCheckRequest, ParentProfileUpdateRequest, ParentInvoiceRequest ...
**Resources:** ParentEmergencyContactResource, ParentAttendanceReportResource, ParentStudentResource, ParentAttendanceResource
**Plan:**
- Centralize identity lookup and cross-entity authorization.
- Test directory/search pagination and visibility filtering.
- Ensure updates cannot orphan related records or break family/student/staff links.
- Add lifecycle tests for active, inactive, newly enrolled, transferred, and deleted/unverified users.

### Payments

**Priority:** P0 Financial correctness
**Detected surface:** 0 controllers, 14 services, 15 requests, 4 resources.

**Services:** PaymentNotificationDispatchService, PaymentMissedCheckService, PaymentManualService, PaymentLookupService, PaymentTestNotificationService, PaypalPaymentSyncService, PaymentBalanceService, PaypalPaymentService, PaymentTransactionService, PaymentEnrollmentEventService, PaymentNotificationService, PaymentPlanService ...
**Requests:** PaymentManualSearchRequest, PaymentEventChargesListRequest, PaymentNotificationSendRequest, PaymentNotificationListRequest, PaymentCreateRequest, PaypalTransactionsListRequest, PaymentManualEditRequest, PaymentEventChargesStoreRequest ...
**Resources:** PaymentNotificationLogResource, PaymentTransactionResource, PaypalTransactionResource, PaymentResource
**Plan:**
- Define one source of truth for payment state transitions, balance calculations, file handling, and notification dispatch.
- Wrap manual payment edits and invoice recalculation in one transaction with row locks.
- Replace filename-only check-file downloads with payment-record-based downloads and authorization.
- Add idempotency keys for PayPal sync, notification dispatch, manual payment creation, and retry flows.
- Store audit trails for payment create/edit/delete, refund application, missed-check updates, and external transaction sync.
- Add reconciliation tests across API, reports, dashboards, and PDFs.

#### PaymentManualService hardening checklist

- `recordPayment()` and `editPayment()` use the same transaction/audit/recalculation rules.
- `serveCheckFile()` cannot be called with only a user-supplied filename; it must resolve files from a payment record.
- Upload validation covers extension, MIME, size, storage path, and scan-friendly safe names.
- Tests cover unrelated parent access, unrelated staff access, valid finance/admin access, guessed filename, missing file, and duplicate edit attempts.

### Phone

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 1 services, 0 requests, 0 resources.

**Services:** PhoneFormatterService
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### Policy

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 1 services, 0 requests, 0 resources.

**Services:** PolicyContentService
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### Preferences

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 3 services, 2 requests, 3 resources.

**Services:** PreferencesCommandService, PreferencesQueryService, PreferencesOptionsService
**Requests:** PreferencesIndexRequest, PreferencesUpsertRequest
**Resources:** PreferencesListResource, PreferencesCollection, PreferencesResource
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### PrintRequests

**Priority:** P2 Operations
**Detected surface:** 1 controllers, 1 services, 0 requests, 0 resources.

**Controllers:** PrintRequestsController
**Services:** PrintRequestsPortalService
**Plan:**
- Review upload/download/PDF generation permissions.
- Validate file type, file size, generated names, and storage paths.
- Add tests for inventory movement consistency and purchase-order state transitions where applicable.
- Make printable outputs reproducible from stable data snapshots.

### Promotions

**Priority:** P1 Student lifecycle
**Detected surface:** 0 controllers, 7 services, 8 requests, 4 resources.

**Services:** PromotionStatusService, PromotionEnrollmentService, PromotionReminderService, LevelProgressionService, PromotionAuditService, PromotionQueryService, PromotionEligibilityService
**Requests:** SendReminderRequest, ParentPromotionOverviewRequest, AdminListPromotionsRequest, EvaluateEligibilityRequest, UpdatePromotionStatusRequest, ParentEnrollmentStepRequest, SetEnrollmentDeadlineRequest, UpsertLevelProgressionRequest
**Resources:** LevelProgressionResource, PromotionAuditLogResource, PromotionReminderResource, StudentPromotionResource
**Plan:**
- Define the academic workflow state machine and valid transitions.
- Test teacher/admin/parent role boundaries.
- Protect uploads and generated academic files.
- Add audit logs for status changes, submissions, and deadline changes.

### Public

**Priority:** P2/P3 Feature hardening
**Detected surface:** 1 controllers, 0 services, 0 requests, 0 resources.

**Controllers:** PublicWinnersController
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### PublicWinners

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 1 services, 0 requests, 0 resources.

**Services:** PublicWinnersPortalService
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### PurchaseOrders

**Priority:** P2 Operations
**Detected surface:** 0 controllers, 4 services, 3 requests, 2 resources.

**Services:** PurchaseOrderStatusService, PurchaseOrderReceiveService, PurchaseOrderCreateService, PurchaseOrderQueryService
**Requests:** PurchaseOrderIndexRequest, PurchaseOrderStoreRequest, PurchaseOrderReceiveRequest
**Resources:** PurchaseOrderResource, PurchaseOrderItemResource
**Plan:**
- Review upload/download/PDF generation permissions.
- Validate file type, file size, generated names, and storage paths.
- Add tests for inventory movement consistency and purchase-order state transitions where applicable.
- Make printable outputs reproducible from stable data snapshots.

### Refunds

**Priority:** P0 Financial correctness
**Detected surface:** 0 controllers, 9 services, 6 requests, 1 resources.

**Services:** RefundSummaryService, RefundInvoiceAdjustmentService, RefundPolicyService, RefundPayoutService, RefundRequestService, RefundQueryService, RefundOverpaymentService, RefundDecisionService, RefundNotificationService
**Requests:** RefundStoreRequest, RefundPaymentRequest, RefundDecisionRequest, RefundRecalculateRequest, RefundIndexRequest, RefundRejectRequest
**Resources:** RefundResource
**Plan:**
- Define one source of truth for monetary calculations and rounding.
- Require transactions around every mutation that changes balance, invoice state, refund state, payment state, or reimbursement status.
- Add audit logs and idempotency keys for external payment/payment-notification flows.
- Build reconciliation tests across API, reports, dashboards, and PDFs.

### Reimbursements

**Priority:** P0 Financial correctness
**Detected surface:** 0 controllers, 11 services, 13 requests, 5 resources.

**Services:** ReimbursementFileService, ReimbursementBatchAssignmentService, ReimbursementContextService, ReimbursementExportService, ReimbursementLookupService, ReimbursementEmailService, ReimbursementRecipientService, ReimbursementBatchService, ReimbursementQueryService, ReimbursementDonationService, ReimbursementCrudService
**Requests:** ReimbursementBatchAdminFileRequest, ReimbursementUpdateRequest, ReimbursementBatchCreateRequest, ReimbursementBatchEmailRequest, ReimbursementProcessRequest, ReimbursementExportBatchRequest, ReimbursementIndexRequest, ReimbursementExportRequest ...
**Resources:** ReimbursementRecipientResource, ReimbursementExpenseResource, ReimbursementBatchResource, ReimbursementResource, ReimbursementUnderProcessingItemResource
**Plan:**
- Define one source of truth for monetary calculations and rounding.
- Require transactions around every mutation that changes balance, invoice state, refund state, payment state, or reimbursement status.
- Add audit logs and idempotency keys for external payment/payment-notification flows.
- Build reconciliation tests across API, reports, dashboards, and PDFs.

### Reports

**Priority:** P2 Operations
**Detected surface:** 4 controllers, 9 services, 11 requests, 8 resources.

**Controllers:** FilesController, ReportCardsController, SlipPrinterController, StickersController
**Services:** SlipPrinterFormatterService, SlipPrinterPdfService, SlipPrinterService, SlipPrinterConfigService, StickerPrintService, StickerPresetService, StickerQueryService, StickerContextService, ReportCardService
**Requests:** SlipPreviewRequest, SlipLogListRequest, SlipPrintRequest, SlipReprintRequest, StickerStudentsByClassRequest, StickerPrintRequest, StickerFormDataRequest, ReportCardCompletenessRequest ...
**Resources:** LateSlipLogResource, StickerStudentResource, StickerPresetResource, StickerClassSectionResource, ReportCardStudentMetaResource, ReportCardAcknowledgementResource, ReportCardClassSectionResource, ReportCardCompletenessStudentResource
**Plan:**
- Review upload/download/PDF generation permissions.
- Validate file type, file size, generated names, and storage paths.
- Add tests for inventory movement consistency and purchase-order state transitions where applicable.
- Make printable outputs reproducible from stable data snapshots.

### Roles

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 8 services, 9 requests, 4 resources.

**Services:** RolePermissionService, RoleDashboardService, RoleCrudService, RoleAssignmentService, RoleSwitchService, RoleStaffService, PermissionCrudService, RoleQueryService
**Requests:** AssignUserRolesRequest, RolePermissionUpdateRequest, UserRoleListRequest, PermissionUpdateRequest, PermissionStoreRequest, RoleSwitchRequest, RoleStoreRequest, RoleUpdateRequest ...
**Resources:** RolePermissionResource, RoleResource, UserWithRolesResource, PermissionResource
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### Root

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 8 services, 1 requests, 1 resources.

**Services:** FeeCalculationService, SemesterRangeService, ApplicationUrlService, SchoolIdService, AssignmentService, AttendanceCommentTemplateService, PhoneFormatterService, EmailService
**Requests:** ApiFormRequest
**Resources:** TeacherSubmissionRowResource
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### School

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 4 services, 0 requests, 0 resources.

**Services:** AccountEventService, SemesterSelectionService, EnrollmentEventService, PaymentEventService
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### SchoolIds

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 2 services, 1 requests, 1 resources.

**Services:** SchoolIdAssignmentService, SchoolIdGenerationService
**Requests:** SchoolIdAssignRequest
**Resources:** SchoolIdResource
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### Scores

**Priority:** P1 Student lifecycle
**Detected surface:** 9 controllers, 16 services, 10 requests, 3 resources.

**Controllers:** FinalController, HomeworkController, MidtermController, ParticipationController, ProjectController, QuizController, ScoreCommentController, ScoreController, ScorePredictorController
**Services:** ParticipationScoreService, QuizCalculator, QuizScoreService, ScoreCommentService, ScoreDashboardService, HomeworkCalculator, SemesterScoreService, ScorePredictorRiskService, ProjectScoreService, HomeworkScoreService, ScoreTermService, ProjectCalculator ...
**Requests:** ScoreCommentSaveRequest, ScorePredictorRequest, ScoreLockRequest, ScoreUpdateRequest, ScoreOverviewRequest, ScoreStudentRequest, ScoreCommentListRequest, ScoreClassRequest ...
**Resources:** ScorePredictorStudentResource, ScoreCommentResource, ScoreStudentResource
**Plan:**
- Centralize score formulas and missing-score behavior.
- Add golden test cases for semester score, quiz, homework, project, participation, final/midterm, and prediction risk calculations.
- Prove grading locks block writes but not allowed reads.
- Verify below-60 communication and parent visibility rules.

### Security

**Priority:** P0 Security/Foundation
**Detected surface:** 0 controllers, 3 services, 3 requests, 2 resources.

**Services:** IpBanCommandService, IpBanQueryService, Pbkdf2Hasher
**Requests:** IpBanIndexRequest, IpUnbanRequest, IpBanRequest
**Resources:** IpBanCollection, IpBanResource
**Plan:**
- Map every endpoint to required auth state, role, and permission.
- Test login throttling, IP bans, password reset cleanup, session timeout, role switching, and registration captcha.
- Confirm security logs include actor, IP, user agent, outcome, and reason.
- Reject role changes that create privilege escalation or stale-session leaks.

### Semesters

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 1 services, 4 requests, 2 resources.

**Services:** SemesterConfigService
**Requests:** SchoolYearRangeRequest, SemesterResolveRequest, SemesterNormalizeRequest, SemesterRangeRequest
**Resources:** SemesterResolveResource, SemesterRangeResource
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### Settings

**Priority:** P2/P3 Feature hardening
**Detected surface:** 6 controllers, 8 services, 8 requests, 5 resources.

**Controllers:** ConfigurationAdminController, EventController, PolicyController, PreferencesController, SchoolCalendarController, SettingsController
**Services:** SettingsService, ConfigurationService, SchoolCalendarMutationService, SchoolCalendarNotificationService, SchoolCalendarContextService, SchoolCalendarQueryService, SchoolCalendarFormatterService, SchoolCalendarMeetingService
**Requests:** SchoolCalendarStoreRequest, ConfigurationStoreRequest, SettingsUpdateRequest, SchoolCalendarIndexRequest, ConfigurationUpdateRequest, SchoolCalendarUpdateRequest, PolicyShowRequest, SchoolCalendarOptionsRequest
**Resources:** PolicyResource, SchoolCalendarEventResource, SettingsResource, ConfigurationResource, SchoolCalendarEventDetailResource
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### Staff

**Priority:** P2/P3 Feature hardening
**Detected surface:** 3 controllers, 3 services, 3 requests, 2 resources.

**Controllers:** StaffController, TeacherController, TimeOffNotificationController
**Services:** StaffQueryService, StaffTimeOffLinkService, StaffCommandService
**Requests:** StaffIndexRequest, StaffUpdateRequest, StaffStoreRequest
**Resources:** StaffCollection, StaffResource
**Plan:**
- Centralize identity lookup and cross-entity authorization.
- Test directory/search pagination and visibility filtering.
- Ensure updates cannot orphan related records or break family/student/staff links.
- Add lifecycle tests for active, inactive, newly enrolled, transferred, and deleted/unverified users.

### Students

**Priority:** P1 Student lifecycle
**Detected surface:** 1 controllers, 7 services, 7 requests, 4 resources.

**Controllers:** StudentController
**Services:** StudentScoreCardService, StudentStatusService, StudentDirectoryService, StudentAutoDistributionService, StudentConfigService, StudentProfileService, StudentAssignmentService
**Requests:** StudentRemoveClassRequest, StudentUpdateRequest, StudentAssignClassRequest, StudentSetActiveRequest, StudentPromotionTotalsRequest, StudentAssignmentListRequest, StudentAutoDistributeRequest
**Resources:** StudentAssignmentResource, StudentRemovedResource, StudentClassSectionResource, StudentScoreCardRowResource
**Plan:**
- Centralize identity lookup and cross-entity authorization.
- Replace any `max(id) + 1` style school ID generation with persisted-ID or database-sequence-based generation.
- Add a unique database constraint on `students.school_id` and retry logic for rare collisions.
- Test directory/search pagination and visibility filtering.
- Ensure updates cannot orphan related records or break family/student/staff links.
- Add lifecycle tests for active, inactive, newly enrolled, transferred, and deleted/unverified users.

#### Student creation acceptance criteria

- Student creation runs in a transaction.
- School ID is generated only after the student has a persisted ID or from a dedicated sequence.
- Concurrent student creation cannot create duplicate school IDs.
- Parent/family/student visibility tests prove users cannot create, view, or mutate records outside their boundary.

### Subjects

**Priority:** P2/P3 Feature hardening
**Detected surface:** 1 controllers, 1 services, 2 requests, 2 resources.

**Controllers:** SubjectCurriculumController
**Services:** SubjectCurriculumService
**Requests:** SubjectCurriculumUpdateRequest, SubjectCurriculumStoreRequest
**Resources:** SubjectCurriculumResource, SubjectClassResource
**Plan:**
- Define the academic workflow state machine and valid transitions.
- Test teacher/admin/parent role boundaries.
- Protect uploads and generated academic files.
- Add audit logs for status changes, submissions, and deadline changes.

### Support

**Priority:** P2/P3 Feature hardening
**Detected surface:** 2 controllers, 2 services, 3 requests, 3 resources.

**Controllers:** ContactController, SupportController
**Services:** SupportRequestService, ContactMessageService
**Requests:** SupportRequestStoreRequest, SupportRequestIndexRequest, ContactSendRequest
**Resources:** ContactMessageResource, SupportRequestResource, SupportRequestCollection
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### System

**Priority:** P0 Security/Foundation
**Detected surface:** 9 controllers, 6 services, 2 requests, 4 resources.

**Controllers:** AccessDeniedController, DashboardController, DashboardRedirectController, DatabaseHealthController, HealthController, NavBuilderController, SchoolIdController, SemesterRangeController, StatsController
**Services:** HealthCheckService, CleanupSchedulerService, GlobalConfigService, DatabaseHealthService, ConfigUpdateService, TimeService
**Requests:** NavItemStoreRequest, NavItemReorderRequest
**Resources:** DashboardRouteResource, NavItemResource, HealthStatusResource, NavBuilderDataResource
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### Teachers

**Priority:** P2/P3 Feature hardening
**Detected surface:** 0 controllers, 4 services, 6 requests, 4 resources.

**Services:** TeacherAbsenceService, TeacherDashboardService, TeacherConfigService, TeacherAssignmentService
**Requests:** TeacherClassViewRequest, TeacherAbsenceSubmitRequest, TeacherAssignmentDeleteRequest, TeacherAssignmentStoreRequest, TeacherAssignmentListRequest, TeacherSwitchClassRequest
**Resources:** TeacherAbsenceResource, TeacherStudentResource, TeacherClassResource, TeacherAssignmentResource
**Plan:**
- Centralize identity lookup and cross-entity authorization.
- Test directory/search pagination and visibility filtering.
- Ensure updates cannot orphan related records or break family/student/staff links.
- Add lifecycle tests for active, inactive, newly enrolled, transferred, and deleted/unverified users.

### Ui

**Priority:** P2/P3 Feature hardening
**Detected surface:** 1 controllers, 1 services, 1 requests, 1 resources.

**Controllers:** UiController
**Services:** UiStyleService
**Requests:** UiStyleRequest
**Resources:** UiStyleResource
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### Users

**Priority:** P2/P3 Feature hardening
**Detected surface:** 1 controllers, 6 services, 4 requests, 2 resources.

**Controllers:** UserController
**Services:** UserListService, LoginActivityService, InactiveUserCleanupService, UserManagementService, UserEventService, DeleteUnverifiedUserService
**Requests:** UserStoreRequest, UserListRequest, UserUpdateRequest, LoginActivityRequest
**Resources:** LoginActivityResource, UserWithRolesResource
**Plan:**
- Confirm all inputs are validated through FormRequest classes.
- Confirm all reads and writes are authorized.
- Move business rules out of controllers if any remain.
- Add feature tests for list/show/create/update/delete and key failure paths.

### Utilities

**Priority:** P2/P3 Feature hardening
**Detected surface:** 2 controllers, 0 services, 1 requests, 1 resources.

**Controllers:** PhoneFormatterController, ProofreadController
**Requests:** PhoneFormatRequest
**Resources:** PhoneFormatResource
**Plan:**
- Confirm config reads/writes are permissioned and validated.
- Add health/config smoke tests.
- Document public versus authenticated surfaces.
- Keep UI/style/static-page services separated from domain mutations.

### Whatsapp

**Priority:** P1 Communications
**Detected surface:** 0 controllers, 8 services, 7 requests, 5 resources.

**Services:** WhatsappContactService, WhatsappInviteService, WhatsappLinkService, WhatsappContextService, WhatsappInviteNotificationService, WhatsappMembershipService, WhatsappInviteBundleService, WhatsappInviteEmailService
**Requests:** WhatsappLinkIndexRequest, WhatsappMembershipUpdateRequest, WhatsappLinkStoreRequest, WhatsappLinkUpdateRequest, WhatsappParentContactsRequest, WhatsappParentContactsByClassRequest, WhatsappInviteSendRequest
**Resources:** WhatsappParentContactResource, WhatsappGroupLinkResource, WhatsappClassSectionParentResource, WhatsappGroupLinkCollection, WhatsappClassSectionContactResource
**Plan:**
- Separate recipient selection, message composition, dispatch, and logging.
- Add preview/dry-run tests before bulk sending.
- Deduplicate sends and persist failure states.
- Verify opt-outs, guardian selection, role targeting, and retry behavior.


## 7. Cross-Cutting Test Matrix

| Area | Minimum tests | Failure tests | Regression traps |
|---|---:|---:|---|
| Auth / Security | Login, refresh, logout, role switch, timeout | Invalid creds, banned IP, stale role, unauthorized role | Privilege escalation, session confusion |
| Finance / Payments | Invoice generation, manual payment, PayPal sync, refunds | Duplicate webhook, failed payment, partial refund | Balance mismatch, rounding drift |
| Attendance | Teacher submit, admin edit, parent report | Out-of-window edit, unauthorized class, duplicate submit | Semester boundary, timezone/date errors |
| Grading / Scores | Score calculations, locks, below-60 notification | Missing score, locked write, invalid class | Formula drift, notification spam |
| Students / Families | Profile, guardians, enrollments, authorized users | Cross-family read/write, inactive student | Orphan relationships |
| Communications | Preview, send, log, retry | Invalid recipient, opt-out, duplicate send | Bulk-send mistakes |
| Files / Reports | Upload, download, PDF generation | Bad MIME, oversize file, unauthorized file | Path traversal, stale report data |
| Inventory / Ops | Item movement, PO receive, print requests | Negative stock, duplicate receive | Count mismatch |


## 8. Refactor Rules

- Do not start by renaming everything. That is not architecture; that is sweeping broken glass into a different corner.
- Start with tests around the highest-risk behavior, then refactor behind those tests.
- One module per pull request unless a shared contract demands otherwise.
- For each PR, include: risk summary, affected endpoints, permission impact, migration impact, rollback path, and test evidence.
- Any service over roughly 300 lines should be reviewed for split points, but line count alone is not a crime. Unclear responsibility is the crime.
- Any controller doing calculations, direct DB orchestration, or multi-step workflow should delegate to a service.
- Any duplicated request validation should be consolidated into shared rules or dedicated FormRequests.

## 9. Immediate Next Work Queue

Work in this order. Alphabetical cleanup is banned until P0 is closed, because alphabetical order has never once saved a ledger.

1. Patch the plan into issue tickets for the seven P0 items in the Critical Implementation Review Queue.
2. Add route inventory from `routes/api.php` and `routes/web.php` once the full repo is available.
3. Produce an endpoint-permission matrix from routes + controllers + policies.
4. Write failing/covering tests for payment file access, manual payment edit transaction safety, student school ID concurrency, scanner idempotency, role mutation authorization, bulk communication recipient safety, and refund/payment/invoice auditing.
5. Implement finance/file authorization fixes before controller refactors.
6. Implement transaction/locking fixes for payments, invoices, refunds, and reimbursements.
7. Implement student school ID generation fix and database uniqueness constraint.
8. Extract scanner services and add duplicate-scan/idempotency behavior.
9. Add baseline feature tests for Auth, Finance/Payments, Attendance, Grading/Scores, Students/Families, and Communications.
10. Create factories and seed data for the core school domain.
11. Add OpenAPI generation to CI using the existing Docs/OpenAPI service surface.
12. Review raw SQL and direct request access matches before any large refactor.
13. Add idempotency and audit requirements to payment, invoice, refund, promotion, and messaging mutations.
14. Write runbooks for console commands and operational cleanup jobs.

## 10. Definition of Done

A module is not considered done until all of this is true:

- All public endpoints have route docs and permission mapping.
- All inputs use FormRequests or clearly justified validation.
- All responses use Resources or documented response builders.
- All mutations are transactional where consistency matters.
- All side effects are logged and testable.
- All critical behavior has feature tests and at least one negative authorization test.
- All money/date/file/message behavior has edge-case tests.
- No endpoint relies on undocumented legacy behavior unless that behavior is explicitly preserved and tested.

## Appendix A: Controller Groups

- **Administrator:** 8 controllers. AdministratorAbsenceController, AdministratorDashboardController, AdministratorEnrollmentController, AdministratorNotificationController, AdministratorPromotionController, AdministratorTeacherSubmissionController, EmergencyContactController, TeacherClassAssignmentController
- **ApiRoot:** 7 controllers. BaseApiController, request adapter, RolePermissionController, RoleSwitcherController, ScannerController, StatsController, UserController
- **Assignment:** 1 controllers. AssignmentApiController
- **Attendance:** 6 controllers. AdminAttendanceApiController, AttendanceCommentTemplateController, EarlyDismissalsController, LateSlipLogsController, StaffAttendanceApiController, TeacherAttendanceApiController
- **AttendanceTracking:** 1 controllers. AttendanceTrackingController
- **Auth:** 7 controllers. AuthController, AuthSessionController, IpBanController, RegisterController, RolePermissionController, RoleSwitcherController, SessionTimeoutController
- **BadgeScan:** 1 controllers. BadgeScanController
- **Badges:** 1 controllers. BadgeController
- **Certificates:** 1 controllers. CertificateController
- **ClassPreparation:** 1 controllers. ClassPreparationController
- **ClassProgress:** 1 controllers. ClassProgressController
- **Classes:** 1 controllers. ClassController
- **Communication:** 1 controllers. CommunicationController
- **CompetitionScores:** 1 controllers. CompetitionScoresController
- **Core:** 2 controllers. BaseApiController, request adapter
- **Discounts:** 1 controllers. DiscountController
- **Documentation:** 2 controllers. ApiDocsAdminController, DocsCatalogController
- **Email:** 3 controllers. BroadcastEmailController, EmailController, EmailExtractorController
- **Exams:** 1 controllers. ExamDraftController
- **Expenses:** 1 controllers. ExpenseController
- **ExtraCharges:** 1 controllers. ExtraChargesController
- **Family:** 2 controllers. FamilyAdminController, FamilyController
- **Finance:** 14 controllers. ChargeController, FeeCalculationController, FinancialController, InvoiceController, PaymentController, PaymentEventChargesController, PaymentManualController, PaymentNotificationController, PaymentTransactionController, PaypalPaymentController, PaypalTransactionsController, PurchaseOrderController, RefundController, ReimbursementController
- **Frontend:** 4 controllers. FrontendController, InfoIconController, LandingPageController, PageController
- **Grading:** 2 controllers. GradingController, HomeworkTrackingController
- **Incidents:** 1 controllers. IncidentController
- **Inventory:** 5 controllers. InventoryCategoryController, InventoryController, InventoryMovementController, SupplierController, SupplyCategoryController
- **Messaging:** 2 controllers. MessagesController, WhatsappController
- **NonApi:** 3 controllers. Controller, DocsController, TeacherCalendarPageController
- **Notifications:** 1 controllers. NotificationController
- **Parents:** 5 controllers. AuthorizedUserInviteController, AuthorizedUsersController, ParentAttendanceReportController, ParentController, ParentPromotionController
- **PrintRequests:** 1 controllers. PrintRequestsController
- **Public:** 1 controllers. PublicWinnersController
- **Reports:** 4 controllers. FilesController, ReportCardsController, SlipPrinterController, StickersController
- **Scores:** 9 controllers. FinalController, HomeworkController, MidtermController, ParticipationController, ProjectController, QuizController, ScoreCommentController, ScoreController, ScorePredictorController
- **Settings:** 6 controllers. ConfigurationAdminController, EventController, PolicyController, PreferencesController, SchoolCalendarController, SettingsController
- **Staff:** 3 controllers. StaffController, TeacherController, TimeOffNotificationController
- **Students:** 1 controllers. StudentController
- **Subjects:** 1 controllers. SubjectCurriculumController
- **Support:** 2 controllers. ContactController, SupportController
- **System:** 9 controllers. AccessDeniedController, DashboardController, DashboardRedirectController, DatabaseHealthController, HealthController, NavBuilderController, SchoolIdController, SemesterRangeController, StatsController
- **Ui:** 1 controllers. UiController
- **Users:** 1 controllers. UserController
- **Utilities:** 2 controllers. PhoneFormatterController, ProofreadController

## Appendix B: Service Groups

- **Admin:** 2 services, 1,089 LOC. CompetitionWinnersDomain, CompetitionWinnersAdminService
- **Administrator:** 18 services, 2,196 LOC. AdministratorUserSearchService, AdministratorAbsenceService, AdministratorDashboardService, AdministratorMetricsService, AdministratorEnrollmentStatusService, AdministratorEnrollmentEventService, AdministratorNotificationService, AdminNotificationSubjectService, TeacherSubmissionSupportService, AdministratorSharedService, TeacherSubmissionNotificationService, TeacherSubmissionReportService, AdminNotificationUserService, AdministratorEnrollmentRefundService, AdminPrintRecipientService, AdministratorTeacherSubmissionService, AdministratorEnrollmentService, AdministratorEnrollmentQueryService
- **Assignment:** 5 services, 421 LOC. AssignmentSectionService, AssignmentMetaService, AssignmentService, AssignmentContextService, AssignmentDataLoaderService
- **Attendance:** 16 services, 3,241 LOC. SemesterRangeService, TeacherAttendanceSubmissionService, AttendanceAutoPublishJobService, AttendanceAutoPublishService, LateSlipLogQueryService, AttendanceConsequenceService, AttendanceRecordSyncService, AttendanceDailySummaryService, AttendanceService, StudentAttendanceWriterService, LateSlipLogCommandService, AttendanceSummaryRebuildService, StaffAttendanceService, AttendanceQueryService, AttendancePolicyService, AttendanceCommentService
- **AttendanceTracking:** 12 services, 2,979 LOC. AttendanceNotificationLogService, AttendanceViolationStudentResolverService, AttendanceNotificationWorkflowService, AttendanceTrackingService, ViolationRuleEngineService, AttendanceMailerService, AttendanceParentLookupService, AttendanceCommunicationSupportService, AttendanceEmailComposerService, AttendancePendingViolationService, AttendanceCaseQueryService, DefaultAttendanceMailerService
- **Auth:** 9 services, 870 LOC. RegistrationCaptchaService, PermissionCheckService, ApiRegistrationService, RegistrationService, ApiLoginSecurityService, AuthSessionService, UserRoleService, PasswordResetCleanupService, RegistrationFormatterService
- **BadgeScan:** 1 services, 108 LOC. BadgeScanService
- **Badges:** 7 services, 2,815 LOC. BadgeTextFormatter, BadgeStudentLookupService, BadgeFormDataService, BadgePdfService, BadgeUserLookupService, BadgeService, BadgePrintLogService
- **Billing:** 3 services, 751 LOC. BalanceCalculationService, BillingTotalsService, ChargeService
- **BroadcastEmail:** 5 services, 241 LOC. BroadcastEmailComposerService, BroadcastEmailRecipientService, BroadcastEmailDispatchService, BroadcastEmailImageService, BroadcastEmailSenderOptionsService
- **Certificates:** 1 services, 144 LOC. CertificatePdfService
- **ClassPrep:** 2 services, 205 LOC. ClassRosterService, StickerCountService
- **ClassPreparation:** 9 services, 653 LOC. ClassPreparationAdjustmentWriterService, ClassPreparationCalculatorService, ClassPreparationLogService, ClassPreparationAdjustmentService, ClassPreparationContextService, ClassPreparationService, ClassPreparationPrintService, ClassPreparationRosterService, ClassPreparationInventoryService
- **ClassProgress:** 5 services, 941 LOC. ClassProgressRuleService, ClassProgressAttachmentService, ClassProgressQueryService, ClassProgressMetaService, ClassProgressMutationService
- **ClassSections:** 4 services, 190 LOC. ClassSectionCommandService, ClassAttendanceService, ClassSectionSeedService, ClassSectionQueryService
- **Communication:** 6 services, 374 LOC. CommunicationFamilyService, CommunicationSendService, CommunicationTemplateService, CommunicationPreviewService, CommunicationStudentService, CommunicationLogService
- **CompetitionScores:** 4 services, 325 LOC. CompetitionScoresRosterService, CompetitionScoresSaveService, CompetitionScoresContextService, CompetitionScoresQueryService
- **Dashboard:** 1 services, 70 LOC. DashboardRouteService
- **Discounts:** 5 services, 792 LOC. DiscountParentService, DiscountApplyService, DiscountInvoiceService, DiscountVoucherService, DiscountContextService
- **Docs:** 3 services, 244 LOC. DocsCatalogService, ApiDocsService, OpenApiRouteExporter
- **Email:** 5 services, 395 LOC. EmailAttachmentService, EmailExtractorService, EmailProfileService, EmailDispatchService, EmailSenderOptionsService
- **EmergencyContacts:** 2 services, 142 LOC. EmergencyContactDirectoryService, EmergencyContactCrudService
- **Events:** 6 services, 496 LOC. EventChargeService, EventStudentChargeService, EventCategoryService, EventListService, EventChargeQueryService, EventManagementService
- **Exams:** 4 services, 532 LOC. ExamDraftTeacherService, ExamDraftAdminService, ExamDraftConfigService, ExamDraftFileService
- **Expenses:** 7 services, 231 LOC. ExpenseQueryService, ExpenseStaffService, ExpenseRetailorService, ExpenseReceiptService, ExpenseWriteService, ExpenseContextService, ExpenseStatusService
- **ExtraCharges:** 6 services, 475 LOC. ExtraChargesMetaService, ExtraChargesInvoiceService, ExtraChargesParentService, ExtraChargesChargeService, ExtraChargesContextService, ExtraChargesListService
- **Families:** 4 services, 827 LOC. FamilyNotificationService, FamilyFinanceService, FamilyMutationService, FamilyQueryService
- **Fees:** 6 services, 952 LOC. FeeConfigService, TuitionCalculationService, FeeRefundCalculatorService, FeeGradeService, FeeRefundDetailService, FeeStudentFeeService
- **Files:** 2 services, 159 LOC. FileServeService, ExamDraftDownloadNameService
- **Finance:** 8 services, 1,150 LOC. FinancialPdfReportService, FinancialSchoolYearService, FinancialPaymentService, FinancialReportService, FinancialSummaryService, FinancialChartService, FinancialDonationRecipientService, FinancialUnpaidParentsService
- **Frontend:** 9 services, 1,011 LOC. LandingPageTeacherSummaryService, LandingPageRoleService, LandingPageParentDashboardService, LandingPageService, StaticPageService, FrontendPageService, ContactSubmissionService, LandingPageContextService, ProfileIconService
- **Grading:** 9 services, 1,969 LOC. BelowSixtyEmailService, GradingLockService, GradingOverviewService, GradingPlacementService, HomeworkTrackingService, GradingScoreService, GradingBelowSixtyService, HomeworkTrackingCalendarService, GradingRefreshService
- **Incidents:** 4 services, 499 LOC. CurrentIncidentService, IncidentHistoryService, IncidentLookupService, IncidentAnalysisService
- **Inventory:** 8 services, 1,449 LOC. InventorySummaryService, InventoryCategoryService, InventoryItemService, InventoryContextService, SupplierService, InventoryMovementService, SupplyCategoryService, InventoryTeacherDistributionService
- **Invoices:** 8 services, 1,248 LOC. InvoiceGradeService, InvoiceConfigService, InvoicePaymentService, InvoiceTuitionService, InvoiceManagementService, InvoicePdfService, InvoiceService, InvoiceGenerationService
- **Messaging:** 3 services, 334 LOC. MessageRecipientService, MessageCommandService, MessageQueryService
- **Navigation:** 2 services, 273 LOC. NavBuilderService, NavbarService
- **Notifications:** 12 services, 451 LOC. NotificationDispatchService, NotificationRecipientService, NotificationShowService, NotificationManagementService, NotificationReadService, NotificationUserListService, NotificationCleanupService, UserNotificationDispatchService, NotificationTriggerService, NotificationSendService, NotificationActiveService, NotificationDeletedService
- **Parents:** 14 services, 2,306 LOC. ParentEventParticipationService, ParentRegistrationService, PrimaryParentUserResolver, ParentAttendanceReportCalendarService, ParentAttendanceService, AuthorizedUsersManagementService, ParentEnrollmentService, ParentInvoiceService, ParentProgressQueryService, ParentAttendanceReportService, ParentReportCardService, ParentConfigService, ParentProfileService, ParentEmergencyContactService
- **Payments:** 14 services, 2,096 LOC. PaymentNotificationDispatchService, PaymentMissedCheckService, PaymentManualService, PaymentLookupService, PaymentTestNotificationService, PaypalPaymentSyncService, PaymentBalanceService, PaypalPaymentService, PaymentTransactionService, PaymentEnrollmentEventService, PaymentNotificationService, PaymentPlanService, PaymentEventChargesService, PaypalTransactionsService
- **Phone:** 1 services, 23 LOC. PhoneFormatterService
- **Policy:** 1 services, 51 LOC. PolicyContentService
- **Preferences:** 3 services, 190 LOC. PreferencesCommandService, PreferencesQueryService, PreferencesOptionsService
- **PrintRequests:** 1 services, 558 LOC. PrintRequestsPortalService
- **Promotions:** 7 services, 1,740 LOC. PromotionStatusService, PromotionEnrollmentService, PromotionReminderService, LevelProgressionService, PromotionAuditService, PromotionQueryService, PromotionEligibilityService
- **PublicWinners:** 1 services, 115 LOC. PublicWinnersPortalService
- **PurchaseOrders:** 4 services, 252 LOC. PurchaseOrderStatusService, PurchaseOrderReceiveService, PurchaseOrderCreateService, PurchaseOrderQueryService
- **Refunds:** 9 services, 1,210 LOC. RefundSummaryService, RefundInvoiceAdjustmentService, RefundPolicyService, RefundPayoutService, RefundRequestService, RefundQueryService, RefundOverpaymentService, RefundDecisionService, RefundNotificationService
- **Reimbursements:** 11 services, 1,776 LOC. ReimbursementFileService, ReimbursementBatchAssignmentService, ReimbursementContextService, ReimbursementExportService, ReimbursementLookupService, ReimbursementEmailService, ReimbursementRecipientService, ReimbursementBatchService, ReimbursementQueryService, ReimbursementDonationService, ReimbursementCrudService
- **Reports:** 9 services, 2,445 LOC. SlipPrinterFormatterService, SlipPrinterPdfService, SlipPrinterService, SlipPrinterConfigService, StickerPrintService, StickerPresetService, StickerQueryService, StickerContextService, ReportCardService
- **Roles:** 8 services, 545 LOC. RolePermissionService, RoleDashboardService, RoleCrudService, RoleAssignmentService, RoleSwitchService, RoleStaffService, PermissionCrudService, RoleQueryService
- **Root:** 8 services, 550 LOC. FeeCalculationService, SemesterRangeService, ApplicationUrlService, SchoolIdService, AssignmentService, AttendanceCommentTemplateService, PhoneFormatterService, EmailService
- **School:** 4 services, 990 LOC. AccountEventService, SemesterSelectionService, EnrollmentEventService, PaymentEventService
- **SchoolIds:** 2 services, 41 LOC. SchoolIdAssignmentService, SchoolIdGenerationService
- **Scores:** 16 services, 2,846 LOC. ParticipationScoreService, QuizCalculator, QuizScoreService, ScoreCommentService, ScoreDashboardService, HomeworkCalculator, SemesterScoreService, ScorePredictorRiskService, ProjectScoreService, HomeworkScoreService, ScoreTermService, ProjectCalculator, ScorePredictorDataService, ScorePredictorService, ExamScoreService, AttendanceCalculator
- **Security:** 3 services, 171 LOC. IpBanCommandService, IpBanQueryService, Pbkdf2Hasher
- **Semesters:** 1 services, 42 LOC. SemesterConfigService
- **Settings:** 8 services, 656 LOC. SettingsService, ConfigurationService, SchoolCalendarMutationService, SchoolCalendarNotificationService, SchoolCalendarContextService, SchoolCalendarQueryService, SchoolCalendarFormatterService, SchoolCalendarMeetingService
- **Staff:** 3 services, 325 LOC. StaffQueryService, StaffTimeOffLinkService, StaffCommandService
- **Students:** 7 services, 1,254 LOC. StudentScoreCardService, StudentStatusService, StudentDirectoryService, StudentAutoDistributionService, StudentConfigService, StudentProfileService, StudentAssignmentService
- **Subjects:** 1 services, 80 LOC. SubjectCurriculumService
- **Support:** 2 services, 123 LOC. SupportRequestService, ContactMessageService
- **System:** 6 services, 353 LOC. HealthCheckService, CleanupSchedulerService, GlobalConfigService, DatabaseHealthService, ConfigUpdateService, TimeService
- **Teachers:** 4 services, 641 LOC. TeacherAbsenceService, TeacherDashboardService, TeacherConfigService, TeacherAssignmentService
- **Ui:** 1 services, 95 LOC. UiStyleService
- **Users:** 6 services, 647 LOC. UserListService, LoginActivityService, InactiveUserCleanupService, UserManagementService, UserEventService, DeleteUnverifiedUserService
- **Whatsapp:** 8 services, 1,407 LOC. WhatsappContactService, WhatsappInviteService, WhatsappLinkService, WhatsappContextService, WhatsappInviteNotificationService, WhatsappMembershipService, WhatsappInviteBundleService, WhatsappInviteEmailService

## Appendix C: Request Groups

- **Admin:** 3 requests. StoreCompetitionWinnerRequest, UpdateCompetitionWinnerRequest, SaveCompetitionScoresRequest
- **Administrator:** 5 requests. SavePrintRecipientsRequest, SaveAdminNotificationSubjectsRequest, SubmitAdministratorAbsenceRequest, UpdateEnrollmentStatusesRequest, SendTeacherSubmissionNotificationsRequest
- **Api:** 4 requests. SaveAdminNotificationSubjectsRequest, IndexAdminProgressRequest, SendTeacherSubmissionNotificationsRequest, SavePrintNotificationRecipientsRequest
- **Assignment:** 2 requests. StoreAssignmentRequest, StoreStudentAssignmentRequest
- **Attendance:** 7 requests. SaveStaffAttendanceCellRequest, UpdateAttendanceManagementRequest, LateSlipLogIndexRequest, TeacherSubmitAttendanceRequest, SaveAdminAttendanceRequest, TeacherUpdateGridRequest, AdminAddAttendanceEntryRequest
- **AttendanceCommentTemplate:** 2 requests. StoreAttendanceCommentTemplateRequest, UpdateAttendanceCommentTemplateRequest
- **AttendanceTracking:** 5 requests. RecordAttendanceTrackingRequest, ComposeAttendanceEmailRequest, SendAttendanceManualEmailRequest, ParentsInfoRequest, SaveAttendanceNotificationNoteRequest
- **Auth:** 3 requests. RegisterRequest, SetRoleSessionRequest, LoginSessionRequest
- **Badges:** 3 requests. BadgePrintStatusRequest, GenerateBadgePdfRequest, LogBadgePrintRequest
- **ClassPreparation:** 4 requests. ClassPreparationMarkPrintedRequest, ClassPreparationPrintRequest, ClassPreparationIndexRequest, ClassPreparationAdjustmentRequest
- **ClassProgress:** 5 requests. ClassProgressStoreRequest, ClassProgressMetaRequest, ClassProgressIndexRequest, ClassProgressFormRequest, ClassProgressUpdateRequest
- **Classes:** 3 requests. ClassSectionUpdateRequest, ClassSectionStoreRequest, ClassSectionIndexRequest
- **Discounts:** 3 requests. UpdateDiscountVoucherRequest, ApplyDiscountVoucherRequest, StoreDiscountVoucherRequest
- **Email:** 2 requests. EmailExtractorCompareRequest, EmailSendRequest
- **EmergencyContacts:** 2 requests. EmergencyContactParentRequest, EmergencyContactUpdateRequest
- **Events:** 6 requests. EventIndexRequest, EventUpdateRequest, EventStoreRequest, EventStudentsWithChargesRequest, EventChargeUpdateRequest, EventChargeIndexRequest
- **Exams:** 3 requests. ExamDraftTeacherStoreRequest, ExamDraftAdminLegacyRequest, ExamDraftAdminReviewRequest
- **Expenses:** 3 requests. UpdateExpenseRequest, StoreExpenseRequest, UpdateExpenseStatusRequest
- **ExtraCharges:** 2 requests. UpdateExtraChargeRequest, StoreExtraChargeRequest
- **Families:** 14 requests. FamilyImportLegacyRequest, FamilyUnlinkStudentRequest, FamilySetPrimaryHomeRequest, FamilyAdminCardRequest, FamiliesByStudentRequest, FamilyBootstrapRequest, FamilyAttachSecondByEmailRequest, FamilyAdminSearchRequest, FamilySetGuardianFlagsRequest, FamilyAdminIndexRequest, FamilyComposeEmailRequest, FamilyUnlinkGuardianRequest, GuardiansByFamilyRequest, FamilyAttachSecondByUserRequest
- **Fees:** 2 requests. FeeTuitionTotalRequest, FeeRefundRequest
- **Files:** 1 requests. FileNameRequest
- **Finance:** 12 requests. FinancialUnpaidParentsRequest, FeeTuitionTotalRequest, ChargeListRequest, FinancialReportRequest, FinancialSummaryRequest, MarkEventChargePaidRequest, FeeTuitionBreakdownRequest, StoreExtraChargeRequest, StoreEventChargeRequest, FeeFamilyBalanceRequest, ApplyExtraChargeRequest, FeeRefundRequest
- **Frontend:** 2 requests. LandingTeacherRequest, ContactSubmitRequest
- **Grading:** 18 requests. BelowSixtyListRequest, BelowSixtySendRequest, GradingLockAllRequest, BelowSixtyMeetingRequest, PlacementLevelsRequest, GradingRefreshRequest, GradingScoreShowRequest, HomeworkTrackingRequest, GradingScoreUpdateRequest, PlacementRequest, PlacementBatchUpdateRequest, BelowSixtyEmailRequest, BelowSixtyStatusRequest, PlacementBatchRequest, GradingLockRequest, PlacementLevelRequest, BelowSixtyMeetingSaveRequest, GradingOverviewRequest
- **Incidents:** 5 requests. IncidentCancelRequest, IncidentCloseRequest, IncidentStoreRequest, IncidentListRequest, IncidentStateRequest
- **Inventory:** 19 requests. InventoryItemIndexRequest, SupplierUpdateRequest, InventoryCategoryStoreRequest, InventoryTeacherDistributionRequest, InventoryItemUpdateRequest, InventoryItemStoreRequest, InventoryTeacherDistributionStoreRequest, InventoryCategoryUpdateRequest, SupplyCategoryStoreRequest, InventoryCategoryIndexRequest, InventoryAdjustRequest, InventoryAuditRequest, SupplierIndexRequest, InventoryMovementIndexRequest, InventoryMovementBulkDeleteRequest, SupplierStoreRequest, InventoryMovementUpdateRequest, InventoryMovementStoreRequest ...
- **Invoices:** 4 requests. InvoiceStatusRequest, InvoiceManagementRequest, InvoiceParentRequest, InvoiceGenerateRequest
- **Messaging:** 3 requests. MessageSendRequest, MessageIndexRequest, MessageUpdateRequest
- **Notifications:** 5 requests. NotificationSendRequest, NotificationActiveRequest, NotificationDeletedRequest, NotificationUpdateRequest, NotificationIndexRequest
- **Parents:** 16 requests. ParentAttendanceReportUpdateRequest, ParentAttendanceReportListRequest, ParentAttendanceReportSubmitRequest, ParentEmergencyContactRequest, UpdateAuthorizedUserRequest, ParentAttendanceReportCheckRequest, ParentProfileUpdateRequest, ParentInvoiceRequest, ParentEnrollmentRequest, SignParentReportCardRequest, ParentAttendanceRequest, StoreAuthorizedUserRequest, ParentStudentUpdateRequest, ParentEventParticipationRequest, ParentEnrollmentActionRequest, ParentRegistrationRequest
- **Payments:** 15 requests. PaymentManualSearchRequest, PaymentEventChargesListRequest, PaymentNotificationSendRequest, PaymentNotificationListRequest, PaymentCreateRequest, PaypalTransactionsListRequest, PaymentManualEditRequest, PaymentEventChargesStoreRequest, PaymentUpdateBalanceRequest, PaymentManualUpdateRequest, PaymentManualSuggestRequest, PaypalExecuteRequest, PaymentByParentRequest, PaymentTransactionStatusRequest, PaymentTransactionCreateRequest
- **Preferences:** 2 requests. PreferencesIndexRequest, PreferencesUpsertRequest
- **Promotions:** 8 requests. SendReminderRequest, ParentPromotionOverviewRequest, AdminListPromotionsRequest, EvaluateEligibilityRequest, UpdatePromotionStatusRequest, ParentEnrollmentStepRequest, SetEnrollmentDeadlineRequest, UpsertLevelProgressionRequest
- **PurchaseOrders:** 3 requests. PurchaseOrderIndexRequest, PurchaseOrderStoreRequest, PurchaseOrderReceiveRequest
- **Refunds:** 6 requests. RefundStoreRequest, RefundPaymentRequest, RefundDecisionRequest, RefundRecalculateRequest, RefundIndexRequest, RefundRejectRequest
- **Reimbursements:** 13 requests. ReimbursementBatchAdminFileRequest, ReimbursementUpdateRequest, ReimbursementBatchCreateRequest, ReimbursementBatchEmailRequest, ReimbursementProcessRequest, ReimbursementExportBatchRequest, ReimbursementIndexRequest, ReimbursementExportRequest, ReimbursementMarkDonationRequest, ReimbursementBatchAssignmentRequest, ReimbursementStoreRequest, ReimbursementBatchLockRequest, ReimbursementUnderProcessingRequest
- **Reports:** 11 requests. SlipPreviewRequest, SlipLogListRequest, SlipPrintRequest, SlipReprintRequest, StickerStudentsByClassRequest, StickerPrintRequest, StickerFormDataRequest, ReportCardCompletenessRequest, ReportCardPdfRequest, ReportCardAcknowledgementRequest, ReportCardMetaRequest
- **Roles:** 9 requests. AssignUserRolesRequest, RolePermissionUpdateRequest, UserRoleListRequest, PermissionUpdateRequest, PermissionStoreRequest, RoleSwitchRequest, RoleStoreRequest, RoleUpdateRequest, RoleListRequest
- **Root:** 1 requests. ApiFormRequest
- **SchoolIds:** 1 requests. SchoolIdAssignRequest
- **Scores:** 10 requests. ScoreCommentSaveRequest, ScorePredictorRequest, ScoreLockRequest, ScoreUpdateRequest, ScoreOverviewRequest, ScoreStudentRequest, ScoreCommentListRequest, ScoreClassRequest, ScoreCommentUpdateRequest, ScoreAddColumnRequest
- **Security:** 3 requests. IpBanIndexRequest, IpUnbanRequest, IpBanRequest
- **Semesters:** 4 requests. SchoolYearRangeRequest, SemesterResolveRequest, SemesterNormalizeRequest, SemesterRangeRequest
- **Settings:** 8 requests. SchoolCalendarStoreRequest, ConfigurationStoreRequest, SettingsUpdateRequest, SchoolCalendarIndexRequest, ConfigurationUpdateRequest, SchoolCalendarUpdateRequest, PolicyShowRequest, SchoolCalendarOptionsRequest
- **Staff:** 3 requests. StaffIndexRequest, StaffUpdateRequest, StaffStoreRequest
- **Students:** 7 requests. StudentRemoveClassRequest, StudentUpdateRequest, StudentAssignClassRequest, StudentSetActiveRequest, StudentPromotionTotalsRequest, StudentAssignmentListRequest, StudentAutoDistributeRequest
- **Subjects:** 2 requests. SubjectCurriculumUpdateRequest, SubjectCurriculumStoreRequest
- **Support:** 3 requests. SupportRequestStoreRequest, SupportRequestIndexRequest, ContactSendRequest
- **System:** 2 requests. NavItemStoreRequest, NavItemReorderRequest
- **Teachers:** 6 requests. TeacherClassViewRequest, TeacherAbsenceSubmitRequest, TeacherAssignmentDeleteRequest, TeacherAssignmentStoreRequest, TeacherAssignmentListRequest, TeacherSwitchClassRequest
- **Ui:** 1 requests. UiStyleRequest
- **Users:** 4 requests. UserStoreRequest, UserListRequest, UserUpdateRequest, LoginActivityRequest
- **Utilities:** 1 requests. PhoneFormatRequest
- **Whatsapp:** 7 requests. WhatsappLinkIndexRequest, WhatsappMembershipUpdateRequest, WhatsappLinkStoreRequest, WhatsappLinkUpdateRequest, WhatsappParentContactsRequest, WhatsappParentContactsByClassRequest, WhatsappInviteSendRequest

## Appendix D: Resource Groups

- **Admin:** 5 resources. PrintRecipientsResource, TeacherSubmissionReportResource, AdminNotificationAlertsResource, ProgressGroupResource, ProgressReportDetailResource
- **Assignment:** 2 resources. AssignmentOverviewResource, AssignmentSectionResource
- **Attendance:** 7 resources. DailyAttendanceResource, AdminAttendanceResource, LateSlipLogCollection, LateSlipLogResource, TeacherGridResource, StaffMonthResource, TeacherAttendanceFormResource
- **Auth:** 1 resources. RegisterResource
- **ClassPreparation:** 2 resources. ClassPreparationPrintResource, ClassPreparationResultResource
- **ClassProgress:** 4 resources. ClassProgressGroupCollection, ClassProgressAttachmentResource, ClassProgressShowResource, ClassProgressReportResource
- **Classes:** 4 resources. ClassSectionCollection, ClassSectionResource, ClassAttendanceResource, ClassAttendanceStudentResource
- **Discounts:** 2 resources. DiscountVoucherResource, DiscountParentResource
- **Email:** 3 resources. EmailSenderResource, EmailExtractorEmailsResource, EmailExtractorCompareResource
- **EmergencyContacts:** 3 resources. EmergencyContactGroupResource, EmergencyContactStudentResource, EmergencyContactResource
- **Events:** 3 resources. EventChargeResource, EventResource, EventStudentChargeResource
- **Exams:** 1 resources. ExamDraftResource
- **Expenses:** 2 resources. ExpenseResource, ExpenseStaffResource
- **ExtraCharges:** 3 resources. ExtraChargeInvoiceOptionResource, ExtraChargeResource, ExtraChargeParentOptionResource
- **Families:** 7 resources. FamilyPaymentResource, FamilyInvoiceResource, FamilySearchItemResource, FamilyResource, FamilyGuardianResource, FamilyStudentResource, FamilyEmergencyContactResource
- **Fees:** 6 resources. FeeRefundResource, FeeFamilyBalanceResource, ChargeActionResource, ChargeListResource, FeeTuitionBreakdownResource, FeeTuitionTotalResource
- **Files:** 1 resources. FileMetaResource
- **Finance:** 9 resources. FinancialReportResource, FinancialSummaryResource, FinancialExpenseSummaryResource, FinancialInvoiceResource, FinancialPaymentResource, FinancialRefundResource, FinancialUnpaidParentResource, FinancialDiscountResource, FinancialReimbursementSummaryResource
- **Frontend:** 6 resources. LandingPageResource, ContactSubmissionResource, FrontendPageResource, FrontendUserResource, ProfileIconResource, PageContentResource
- **Grading:** 3 resources. BelowSixtyStudentResource, GradingScoreResource, HomeworkTrackingTeacherResource
- **Incidents:** 4 resources. IncidentStudentOptionResource, IncidentAnalysisStudentResource, IncidentResource, IncidentGradeResource
- **Inventory:** 5 resources. InventoryItemResource, InventoryCategoryResource, InventoryMovementResource, SupplierResource, SupplyCategoryResource
- **Invoices:** 2 resources. InvoiceManagementParentResource, InvoiceResource
- **Messaging:** 3 resources. MessageResource, MessageCollection, RecipientResource
- **Notifications:** 2 resources. UserNotificationResource, NotificationResource
- **Parents:** 4 resources. ParentEmergencyContactResource, ParentAttendanceReportResource, ParentStudentResource, ParentAttendanceResource
- **Payments:** 4 resources. PaymentNotificationLogResource, PaymentTransactionResource, PaypalTransactionResource, PaymentResource
- **Preferences:** 3 resources. PreferencesListResource, PreferencesCollection, PreferencesResource
- **Promotions:** 4 resources. LevelProgressionResource, PromotionAuditLogResource, PromotionReminderResource, StudentPromotionResource
- **PurchaseOrders:** 2 resources. PurchaseOrderResource, PurchaseOrderItemResource
- **Refunds:** 1 resources. RefundResource
- **Reimbursements:** 5 resources. ReimbursementRecipientResource, ReimbursementExpenseResource, ReimbursementBatchResource, ReimbursementResource, ReimbursementUnderProcessingItemResource
- **Reports:** 8 resources. LateSlipLogResource, StickerStudentResource, StickerPresetResource, StickerClassSectionResource, ReportCardStudentMetaResource, ReportCardAcknowledgementResource, ReportCardClassSectionResource, ReportCardCompletenessStudentResource
- **Roles:** 4 resources. RolePermissionResource, RoleResource, UserWithRolesResource, PermissionResource
- **Root:** 1 resources. TeacherSubmissionRowResource
- **SchoolIds:** 1 resources. SchoolIdResource
- **Scores:** 3 resources. ScorePredictorStudentResource, ScoreCommentResource, ScoreStudentResource
- **Security:** 2 resources. IpBanCollection, IpBanResource
- **Semesters:** 2 resources. SemesterResolveResource, SemesterRangeResource
- **Settings:** 5 resources. PolicyResource, SchoolCalendarEventResource, SettingsResource, ConfigurationResource, SchoolCalendarEventDetailResource
- **Staff:** 2 resources. StaffCollection, StaffResource
- **Students:** 4 resources. StudentAssignmentResource, StudentRemovedResource, StudentClassSectionResource, StudentScoreCardRowResource
- **Subjects:** 2 resources. SubjectCurriculumResource, SubjectClassResource
- **Support:** 3 resources. ContactMessageResource, SupportRequestResource, SupportRequestCollection
- **System:** 4 resources. DashboardRouteResource, NavItemResource, HealthStatusResource, NavBuilderDataResource
- **Teachers:** 4 resources. TeacherAbsenceResource, TeacherStudentResource, TeacherClassResource, TeacherAssignmentResource
- **Ui:** 1 resources. UiStyleResource
- **Users:** 2 resources. LoginActivityResource, UserWithRolesResource
- **Utilities:** 1 resources. PhoneFormatResource
- **Whatsapp:** 5 resources. WhatsappParentContactResource, WhatsappGroupLinkResource, WhatsappClassSectionParentResource, WhatsappGroupLinkCollection, WhatsappClassSectionContactResource

## Appendix E: Implementation Fix Tickets

These tickets are the plan’s mandatory implementation layer. Each one should become a tracked issue with tests before code changes begin.

### Ticket P0-001: Payment file access hardening

**Problem:** Filename-driven file serving can allow users to request files without proving access to the payment record.

**Implementation:**

- Change the endpoint contract from `{filename}` to `{payment}` or `{payment}/file`.
- Load the payment with invoice/family context.
- Authorize using a policy or gate before resolving file path.
- Resolve file path from the stored payment record only.
- Keep basename/path traversal protection as defense-in-depth, not as the primary access control.
- Log download attempts with actor, payment, result, and source IP where available.

**Tests:**

- finance/admin success;
- owning parent success if business rules allow it;
- unrelated parent forbidden;
- teacher/staff forbidden unless explicitly allowed;
- guessed filename forbidden;
- traversal filename rejected;
- missing file returns `404` without leaking storage path.

### Ticket P0-002: Manual payment edit transaction safety

**Problem:** Payment edit and invoice recalculation must not be split across unprotected operations.

**Implementation:**

- Wrap edit, invoice lookup, balance recompute, payment update, and audit insert in one transaction.
- Lock payment and invoice rows before recalculation.
- Recalculate after mutation inside the same transaction.
- Enforce no-overpayment and valid method/status transitions.
- Write before/after audit data.

**Tests:**

- successful edit updates invoice balance;
- rejected edit leaves payment and invoice unchanged;
- two concurrent edits do not corrupt balance;
- audit row contains actor and before/after values.

### Ticket P0-003: Student school ID generation

**Problem:** `max(id) + 1` style generation is race-prone.

**Implementation:**

- Create the student first, then derive school ID from the persisted ID, or use a database-backed sequence.
- Add a unique constraint to `students.school_id`.
- Save school ID inside the same transaction.
- Add retry behavior for collision.

**Tests:**

- normal create assigns expected school ID format;
- duplicate school ID violates database constraint;
- concurrent create does not produce duplicates;
- rollback does not leave orphaned related records.

### Ticket P0-004: Scanner service extraction and idempotency

**Problem:** Scanner logic is too large for a controller and mixes validation, lookup, mutation, late-slip behavior, logging, and response formatting.

**Implementation:**

- Add `ScannerRequest`.
- Create `ScannerService` as the orchestration entry point.
- Extract `BadgeLookupService`, `StudentScanService`, `StaffScanService`, `LateArrivalService`, `AttendanceScanLogger`, and `ScannerResponseFactory`.
- Put attendance mutations inside one transaction.
- Add duplicate-scan/idempotency protection.

**Tests:**

- valid student scan;
- valid staff scan;
- invalid badge;
- duplicate scan;
- late arrival;
- semester/date boundary;
- scan log written exactly once per accepted mutation.

### Ticket P0-005: Role and permission mutation authorization

**Problem:** Role/permission mutations have high blast radius and must not rely on casual controller checks.

**Implementation:**

- Define canonical role/permission controllers.
- Mark duplicate root/auth controllers as canonical, shim, deprecated, or accidental duplicate.
- Route only to canonical controllers.
- Use a policy/gate for every mutation.
- Log actor, target, old state, and new state.

**Tests:**

- super-admin/admin allowed according to policy;
- lower-role forbidden;
- user cannot mutate own privilege unless explicitly allowed;
- deprecated/shim routes cannot bypass policy.

### Ticket P0-006: Bulk communication safety

**Problem:** Bulk send behavior can accidentally spam, duplicate, or target the wrong recipients.

**Implementation:**

- Require preview/dry-run before send.
- Canonicalize and deduplicate recipients.
- Apply opt-outs/preferences.
- Log send attempts, failures, and retries.
- Separate message composition from delivery.

**Tests:**

- preview count equals eligible send count;
- duplicate guardians collapse;
- opted-out recipients are excluded;
- failed sends are logged and retryable;
- wrong-role sender cannot bulk send.

### Ticket P0-007: Refund/payment/invoice audit completeness

**Problem:** Financial state must be reconstructable after the fact. “Trust me, it updated” is not an audit strategy, it is a confession.

**Implementation:**

- Standardize audit fields across payments, invoices, refunds, discounts, reimbursements, and external sync.
- Include actor, target, amount, old state, new state, source, and idempotency key.
- Ensure reports use the same canonical ledger/balance behavior as API reads.

**Tests:**

- each financial mutation creates audit data;
- reports reconcile with API totals;
- repeated external sync does not double-apply;
- failed mutation does not write misleading audit success.

## Appendix E: Notable Review Queues

### Raw SQL review queue

- `app/Services/Finance/FinancialSummaryService.php`: 28 matches
- `app/Services/Grading/GradingOverviewService.php`: 11 matches
- `app/Services/Finance/FinancialReportService.php`: 10 matches
- `app/Models/User.php`: 7 matches
- `app/Models/AttendanceData.php`: 6 matches
- `app/Services/Refunds/RefundOverpaymentService.php`: 6 matches
- `app/Services/Reports/ReportCards/ReportCardService.php`: 6 matches
- `app/Services/AttendanceTracking/ViolationRuleEngineService.php`: 5 matches
- `app/Services/AttendanceTracking/AttendanceCaseQueryService.php`: 4 matches
- `app/Services/Grading/GradingBelowSixtyService.php`: 4 matches
- `app/Services/Grading/HomeworkTrackingService.php`: 4 matches
- `app/Models/Payment.php`: 3 matches
- `app/Services/Attendance/AttendanceQueryService.php`: 3 matches
- `app/Services/Inventory/InventoryItemService.php`: 3 matches
- `app/Services/Inventory/InventoryMovementService.php`: 3 matches
- `app/Services/Payments/PaymentMissedCheckService.php`: 3 matches
- `app/Services/Scores/ScoreDashboardService.php`: 3 matches
- `app/Services/Scores/ScorePredictorDataService.php`: 3 matches
- `app/Models/Invoice.php`: 2 matches
- `app/Models/Role.php`: 2 matches
- `app/Models/TeacherClass.php`: 2 matches
- `app/Services/Admin/CompetitionWinners/CompetitionWinnersAdminService.php`: 2 matches
- `app/Services/Attendance/AttendanceDailySummaryService.php`: 2 matches
- `app/Services/AttendanceTracking/AttendancePendingViolationService.php`: 2 matches
- `app/Services/Families/FamilyQueryService.php`: 2 matches
- `app/Services/Finance/FinancialPaymentService.php`: 2 matches
- `app/Services/Promotions/PromotionQueryService.php`: 2 matches
- `app/Services/Refunds/RefundPayoutService.php`: 2 matches
- `app/Services/Refunds/RefundQueryService.php`: 2 matches
- `app/Services/Staff/StaffQueryService.php`: 2 matches
- `app/Services/Whatsapp/WhatsappInviteBundleService.php`: 2 matches
- `app/Models/AdditionalCharge.php`: 1 matches
- `app/Models/AttendanceRecord.php`: 1 matches
- `app/Models/AttendanceTracking.php`: 1 matches
- `app/Models/Project.php`: 1 matches
- `app/Models/RoleNavItem.php`: 1 matches
- `app/Models/StaffAttendance.php`: 1 matches
- `app/Models/StudentAllergy.php`: 1 matches
- `app/Models/StudentMedicalCondition.php`: 1 matches
- `app/Models/WhatsappGroupMembership.php`: 1 matches
- ... 19 more files

### Direct request access review queue

- `app/Http/Controllers/Api/AttendanceTracking/AttendanceTrackingController.php`: 16 matches
- `app/Http/Controllers/Api/Attendance/AttendanceCommentTemplateController.php`: 15 matches
- `app/Http/Controllers/Api/Communication/CommunicationController.php`: 12 matches
- `app/Http/Controllers/Api/Badges/BadgeController.php`: 9 matches
- `app/Http/Controllers/Api/Email/BroadcastEmailController.php`: 9 matches
- `app/Http/Controllers/Api/ExtraCharges/ExtraChargesController.php`: 9 matches
- `app/Http/Controllers/Api/Students/StudentController.php`: 9 matches
- `app/Http/Controllers/Api/Attendance/StaffAttendanceApiController.php`: 8 matches
- `app/Http/Controllers/Api/Attendance/EarlyDismissalsController.php`: 7 matches
- `app/Http/Controllers/Api/ClassPreparation/ClassPreparationController.php`: 7 matches
- `app/Http/Controllers/Api/Attendance/TeacherAttendanceApiController.php`: 5 matches
- `app/Http/Controllers/Api/Certificates/CertificateController.php`: 5 matches
- `app/Http/Controllers/Api/Reports/ReportCardsController.php`: 5 matches
- `app/Http/Controllers/Api/CompetitionScores/CompetitionScoresController.php`: 4 matches
- `app/Http/Controllers/Api/Finance/ReimbursementController.php`: 4 matches
- `app/Http/Controllers/Api/PrintRequests/PrintRequestsController.php`: 4 matches
- `app/Http/Controllers/Api/Administrator/AdministratorEnrollmentController.php`: 3 matches
- `app/Http/Controllers/Api/Assignment/AssignmentApiController.php`: 3 matches
- `app/Http/Controllers/Api/Finance/InvoiceController.php`: 3 matches
- `app/Http/Controllers/Api/Finance/PaymentManualController.php`: 3 matches
- `app/Http/Controllers/Api/Parents/AuthorizedUserInviteController.php`: 3 matches
- `app/Http/Controllers/Api/Scores/ScoreCommentController.php`: 3 matches
- `app/Http/Controllers/Api/Scores/ScoreController.php`: 3 matches
- `app/Services/Administrator/AdministratorAbsenceService.php`: 3 matches
- `app/Http/Controllers/Api/Administrator/AdministratorNotificationController.php`: 2 matches
- `app/Http/Controllers/Api/Attendance/AdminAttendanceApiController.php`: 2 matches
- `app/Http/Controllers/Api/Auth/AuthSessionController.php`: 2 matches
- `app/Http/Controllers/Api/Auth/RegisterController.php`: 2 matches
- `app/Http/Controllers/Api/Classes/ClassController.php`: 2 matches
- `app/Http/Controllers/Api/Finance/PaymentController.php`: 2 matches
- `app/Http/Controllers/Api/Finance/PaymentTransactionController.php`: 2 matches
- `app/Http/Controllers/Api/Finance/PurchaseOrderController.php`: 2 matches
- `app/Http/Controllers/Api/Incidents/IncidentController.php`: 2 matches
- `app/Http/Controllers/Api/Scores/FinalController.php`: 2 matches
- `app/Http/Controllers/Api/Scores/HomeworkController.php`: 2 matches
- `app/Http/Controllers/Api/Scores/MidtermController.php`: 2 matches
- `app/Http/Controllers/Api/Scores/ParticipationController.php`: 2 matches
- `app/Http/Controllers/Api/Scores/ProjectController.php`: 2 matches
- `app/Http/Controllers/Api/Scores/QuizController.php`: 2 matches
- `app/Services/Administrator/TeacherSubmissionNotificationService.php`: 2 matches
- ... 10 more files

### File operation review queue

- `app/Services/Reimbursements/ReimbursementEmailService.php`: 5 matches
- `app/Http/Controllers/Api/Students/StudentController.php`: 3 matches
- `app/Services/Badges/BadgePdfService.php`: 3 matches
- `app/ThirdParty/fpdf/fpdf.php`: 3 matches
- `app/Http/Controllers/Api/ClassProgress/ClassProgressController.php`: 2 matches
- `app/Http/Controllers/Api/Finance/ReimbursementController.php`: 2 matches
- `app/Services/Payments/PaymentManualService.php`: 2 matches
- `app/Services/PrintRequests/PrintRequestsPortalService.php`: 2 matches
- `app/Services/System/ConfigUpdateService.php`: 2 matches
- `app/Services/Whatsapp/WhatsappInviteEmailService.php`: 2 matches
- `app/Http/Controllers/Api/Attendance/EarlyDismissalsController.php`: 1 matches
- `app/Http/Controllers/Api/Finance/FinancialController.php`: 1 matches
- `app/Http/Controllers/Api/Finance/PaypalTransactionsController.php`: 1 matches
- `app/Http/Controllers/Api/PrintRequests/PrintRequestsController.php`: 1 matches
- `app/Services/Attendance/StaffAttendanceService.php`: 1 matches
- `app/Services/Finance/FinancialChartService.php`: 1 matches
- `app/Services/Parents/ParentAttendanceReportService.php`: 1 matches
- `app/Services/Reimbursements/ReimbursementFileService.php`: 1 matches

### Queue/dispatch review queue

- `app/Services/Promotions/PromotionReminderService.php`: 2 matches
- `app/Console/Commands/DeleteUnverifiedUsersCommand.php`: 1 matches
- `app/Services/Administrator/AdministratorEnrollmentEventService.php`: 1 matches
- `app/Services/Grading/GradingBelowSixtyService.php`: 1 matches
- `app/Services/Notifications/NotificationTriggerService.php`: 1 matches
- `app/Services/Whatsapp/WhatsappInviteNotificationService.php`: 1 matches
- `app/Services/Whatsapp/WhatsappInviteService.php`: 1 matches

### Legacy compatibility review queue

- `app/Services/Parents/ParentAttendanceReportService.php`: 4 matches
- `app/Config/Database.php`: 3 matches
- `app/Helpers/app_helpers.php`: 3 matches
- `app/Http/Controllers/Api/Attendance/AttendanceCommentTemplateController.php`: 3 matches
- `app/Http/Controllers/Api/Auth/RegisterController.php`: 3 matches
- `app/Http/Controllers/Api/BaseApiController.php`: 3 matches
- `app/Http/Controllers/Api/Core/BaseApiController.php`: 2 matches
- `app/Services/Admin/CompetitionWinners/CompetitionWinnersAdminService.php`: 2 matches
- `app/Services/AttendanceTracking/AttendanceTrackingService.php`: 2 matches
- `app/Services/Auth/ApiLoginSecurityService.php`: 2 matches
- `app/Services/Auth/ApiRegistrationService.php`: 2 matches
- `app/Services/Discounts/DiscountApplyService.php`: 2 matches
- `app/Services/ExtraCharges/ExtraChargesChargeService.php`: 2 matches
- `app/Services/Payments/PaymentManualService.php`: 2 matches
- `app/Http/Controllers/Api/Auth/AuthController.php`: 1 matches
- `app/Http/Controllers/Api/Auth/AuthSessionController.php`: 1 matches
- `app/Http/Controllers/Api/request adapter.php`: 1 matches
- `app/Http/Controllers/Api/Core/request adapter.php`: 1 matches
- `app/Http/Controllers/Api/System/HealthController.php`: 1 matches
- `app/Http/Controllers/Api/Utilities/ProofreadController.php`: 1 matches
- `app/Http/Middleware/EnsureClassProgressTeacherPortalAccess.php`: 1 matches
- `app/Http/Middleware/EnsureParentProgressAccess.php`: 1 matches
- `app/Http/Middleware/EnsurePrintRequestsAdminAccess.php`: 1 matches
- `app/Http/Middleware/EnsurePrintRequestsTeacherAccess.php`: 1 matches
- `app/Http/Middleware/TeacherPortalAuthenticate.php`: 1 matches
- `app/Http/Requests/Admin/SaveCompetitionScoresRequest.php`: 1 matches
- `app/Http/Requests/Admin/StoreCompetitionWinnerRequest.php`: 1 matches
- `app/Http/Requests/Admin/UpdateCompetitionWinnerRequest.php`: 1 matches
- `app/Models/database compatibility layer.php`: 1 matches
- `app/Models/User.php`: 1 matches
- `app/Services/Admin/CompetitionWinners/CompetitionWinnersDomain.php`: 1 matches
- `app/Services/Attendance/StaffAttendanceService.php`: 1 matches
- `app/Services/Auth/AuthSessionService.php`: 1 matches
- `app/Services/BadgeScan/BadgeScanService.php`: 1 matches
- `app/Services/Docs/DocsCatalogService.php`: 1 matches
- `app/Services/Parents/AuthorizedUsersManagementService.php`: 1 matches
- `app/Services/Parents/ParentProgressQueryService.php`: 1 matches
- `app/Services/Parents/ParentReportCardService.php`: 1 matches
- `app/Services/Parents/PrimaryParentUserResolver.php`: 1 matches
- `app/Services/PrintRequests/PrintRequestsPortalService.php`: 1 matches
- ... 1 more files


## Appendix B: Reusable School Platform Tickets

### MSP-001: Create `SchoolContext`

**Goal:** Provide one immutable context object for school/program/tenant scoping.

**Acceptance criteria:**

- Contains school/program/tenant identifiers as required by the chosen model.
- Created at API boundary after authentication.
- Passed into all high-risk service commands.
- Used by repositories, policies, jobs, files, reports, and notifications.
- Cross-school access tests fail before the fix and pass after.

### MSP-002: Classify all services

**Goal:** Separate reusable core services from Islamic Sunday School extension services and infrastructure adapters.

**Acceptance criteria:**

- Every service is labeled `Core`, `IslamicSundaySchoolExtension`, `Infrastructure`, or `LegacyShim`.
- Each duplicate service has a canonical owner.
- CI/static check blocks `SchoolCore -> IslamicSundaySchool` dependencies.

### MSP-003: Extract attendance policy architecture

**Goal:** Make attendance reusable for daily schools, weekly programs, Islamic Sunday School, tutoring programs, and hybrid systems.

**Acceptance criteria:**

- `AttendancePolicy` contract exists.
- Standard and Islamic Sunday School implementations exist.
- Scanner flow uses a command object with context and actor.
- Duplicate scan/idempotency tests pass for both standard and Sunday policies.

### MSP-004: Extract finance policy architecture

**Goal:** Make invoices/payments/refunds reusable across school types.

**Acceptance criteria:**

- `TuitionPolicy`, `PaymentAllocationPolicy`, and `LedgerPolicy` or equivalent contracts exist.
- Manual payment edit remains transaction-safe.
- Islamic Sunday School-specific discounts/fees are extension rules, not core assumptions.
- Ledger reconciliation tests pass across at least two policy configurations.

### MSP-005: Extract student identifier generation

**Goal:** Remove hardcoded ID generation and support different school ID formats.

**Acceptance criteria:**

- `StudentIdentifierGenerator` contract exists.
- Core generator is sequence-safe.
- Islamic Sunday School generator is a concrete extension binding if it uses a special format.
- Unique DB constraint and retry behavior exist.

### MSP-006: Create extension registration provider

**Goal:** Make Islamic Sunday School a plugin-style implementation of generic school contracts.

**Acceptance criteria:**

- All Islamic Sunday School-specific bindings live in one or more providers.
- Core services can run with default bindings.
- Tests can swap bindings without editing service code.

### MSP-007: Neutralize domain vocabulary in core

**Goal:** Ensure core model/service names work for any school system.

**Acceptance criteria:**

- Core uses neutral terms: `Student`, `Guardian`, `StaffMember`, `ClassGroup`, `Session`, `AcademicTerm`, `Program`.
- Islamic Sunday School-specific aliases remain in extension/API presentation only.
- No masjid/community/ministry/Sunday vocabulary exists inside `SchoolCore`.
