melabidi/alrahma_sunday_school_api

Fork 0

Files

T

root b4e6ac03c5 remove codeigniter

2026-06-04 02:41:08 -04:00

120 KiB

Raw Blame History

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

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.
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.
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.
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.
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.
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.
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.

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.

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.

Patch the plan into issue tickets for the seven P0 items in the Critical Implementation Review Queue.
Add route inventory from routes/api.php and routes/web.php once the full repo is available.
Produce an endpoint-permission matrix from routes + controllers + policies.
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.
Implement finance/file authorization fixes before controller refactors.
Implement transaction/locking fixes for payments, invoices, refunds, and reimbursements.
Implement student school ID generation fix and database uniqueness constraint.
Extract scanner services and add duplicate-scan/idempotency behavior.
Add baseline feature tests for Auth, Finance/Payments, Attendance, Grading/Scores, Students/Families, and Communications.
Create factories and seed data for the core school domain.
Add OpenAPI generation to CI using the existing Docs/OpenAPI service surface.
Review raw SQL and direct request access matches before any large refactor.
Add idempotency and audit requirements to payment, invoice, refund, promotion, and messaging mutations.
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

120 KiB Raw Blame History Unescape Escape

App Project Implementation Plan

1. Scope and Readout

Inventory

2. Project Thesis

3. Main Architecture Plan

Target shape

Non-negotiable rules

Critical Implementation Review Queue

P0: Must review before feature work

Module Acceptance Standard

4. Evidence-Based Risk Notes

5. Delivery Phases

Phase 0: Baseline and Guardrails

Phase 1: Security and Access Control

Phase 2: Financial Correctness

Phase 3: Student Lifecycle Correctness

Phase 4: Communications Reliability

Phase 5: Operations and Reporting

Phase 6: Documentation and API Contracts

6. Module-by-Module Plan

Admin

Administrator

Api

ApiRoot

Scanner refactor acceptance criteria

Assignment

Attendance

AttendanceCommentTemplate

AttendanceTracking

Auth

BadgeScan

Badges

Billing

BroadcastEmail

Certificates

ClassPrep

ClassPreparation

ClassProgress

ClassSections

Classes

Communication

CompetitionScores

Core

Dashboard

Discounts

Docs

Documentation

Email

EmergencyContacts

Events

Exams

Expenses

ExtraCharges

Families

Family

Fees

Files

Finance

Finance P0 acceptance criteria

Frontend

Grading

Incidents

Inventory

Invoices

Messaging

Navigation

NonApi

Notifications

Parents

Payments

PaymentManualService hardening checklist

Phone

Policy

Preferences

PrintRequests

Promotions

Public

PublicWinners

PurchaseOrders

120 KiB

Raw Blame History