# App Project Implementation Plan 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. ### 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. ### 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. ### 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. ## 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. ## 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