alrahma_sunday_school_api/docs/controller_plan.md

API Controller Plan

Generated from the uploaded Api(1).zip controller tree. This is a controller-by-controller implementation and hardening plan, not a routing map, because no route file was included. Yes, apparently we are deriving architecture from controllers now, because civilization is fragile.

• Controller files found: 124
• Scope: Api/**/*.php files ending in Controller.php
• Default standard for every controller: validate with FormRequest or explicit validator, keep business logic in services, return consistent JSON envelopes, enforce auth/permissions, log failures without PII, and cover endpoints with feature tests.

Global cleanup plan

1. Normalize namespaces and duplicates. There are root controllers and module controllers with overlapping names, especially BaseApiController, RolePermissionController, RoleSwitcherController, StatsController, and UserController. Decide which are canonical and deprecate the rest.
2. Make controllers thin. Anything doing calculations, scans, finance state changes, reporting, or multi-table writes belongs in a service/action class.
3. Standardize response shape. Use one success/error format, predictable status codes, and resource classes for payloads.
4. Permission matrix. For each endpoint, define roles allowed, ownership rules, and school/tenant scoping. Write denied-path tests first, because hope is not access control.
5. Audit mutating operations. Store actor, before/after, timestamp, and reason for attendance, finance, grades, family/student/staff changes.
6. Test by risk. Finance, auth, attendance, grading, and mass communication get transaction/idempotency/authorization tests before cosmetic endpoints.

Table of contents

• Administrator (8)
• Assignment (1)
• Attendance (6)
• AttendanceTracking (1)
• Auth (7)
• BadgeScan (1)
• Badges (1)
• Certificates (1)
• ClassPreparation (1)
• ClassProgress (1)
• Classes (1)
• Communication (1)
• CompetitionScores (1)
• Core (1)
• Discounts (1)
• Documentation (2)
• Email (3)
• Exams (1)
• Expenses (1)
• ExtraCharges (1)
• Family (2)
• Finance (14)
• Frontend (4)
• Grading (2)
• Incidents (1)
• Inventory (5)
• Messaging (2)
• Notifications (1)
• Parents (5)
• PrintRequests (1)
• Public (1)
• Reports (4)
• Root (6)
• Scores (9)
• Settings (6)
• Staff (3)
• Students (1)
• Subjects (1)
• Support (2)
• System (9)
• Ui (1)
• Users (1)
• Utilities (2)

Administrator

AdministratorAbsenceController

File: Api/Administrator/AdministratorAbsenceController.php
Purpose: manage school identity and operations workflow for administrator absence.
Public methods: index(), store(Request $request) Detected dependencies: Services: AdministratorAbsenceService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission.

AdministratorDashboardController

File: Api/Administrator/AdministratorDashboardController.php
Purpose: manage school identity and operations workflow for administrator dashboard.
Public methods: metrics(), userSearch(Request $request) Detected dependencies: Services: AdministratorDashboardService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

AdministratorEnrollmentController

File: Api/Administrator/AdministratorEnrollmentController.php
Purpose: manage school identity and operations workflow for administrator enrollment.
Public methods: index(Request $request), newStudents(), updateStatuses(Request $request) Detected dependencies: Services: AdministratorEnrollmentService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping.

AdministratorNotificationController

File: Api/Administrator/AdministratorNotificationController.php
Purpose: manage school identity and operations workflow for administrator notification.
Public methods: alerts(), saveAlerts(Request $request), printRecipients(), savePrintRecipients(Request $request) Detected dependencies: Services: AdministratorNotificationService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Validate file type, size, storage path, and access ownership.
• Generated documents need reproducible inputs and predictable naming.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

AdministratorPromotionController

File: Api/Administrator/AdministratorPromotionController.php
Purpose: manage school identity and operations workflow for administrator promotion.
Public methods: index(AdminListPromotionsRequest $request), show(int $promotionId), summary(AdminListPromotionsRequest $request), evaluate(EvaluateEligibilityRequest $request), updateStatus(UpdatePromotionStatusRequest $request, int $promotionId), setDeadline(SetEnrollmentDeadlineRequest $request, ?int $promotionId = null), sendReminder(SendReminderRequest $request, int $promotionId), dispatchScheduledReminders(), reminders(int $promotionId), audit(int $promotionId), expireDeadlines(), adminCompleteEnrollment(ParentEnrollmentStepRequest $request, int $promotionId), levelProgressions(), upsertLevelProgression(UpsertLevelProgressionRequest $request), seedLevelProgressions() Detected dependencies: Services: LevelProgressionService, PromotionAuditService, PromotionEligibilityService, PromotionEnrollmentService, PromotionQueryService, PromotionReminderService, PromotionStatusService | Requests: AdminListPromotionsRequest, EvaluateEligibilityRequest, ParentEnrollmentStepRequest, SendReminderRequest, SetEnrollmentDeadlineRequest, UpdatePromotionStatusRequest, UpsertLevelProgressionRequest | Resources: LevelProgressionResource, PromotionAuditLogResource, PromotionReminderResource, StudentPromotionResource | Models: PromotionAuditLog, PromotionReminderLog, StudentPromotionRecord

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Mutating endpoints need request validation, service-layer ownership, and database transactions where multiple rows change.
• This controller is large enough to hide bugs. Split orchestration from business logic before it becomes archaeology.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record.

AdministratorTeacherSubmissionController

File: Api/Administrator/AdministratorTeacherSubmissionController.php
Purpose: manage school identity and operations workflow for administrator teacher submission.
Public methods: index(), notify(Request $request) Detected dependencies: Services: AdministratorTeacherSubmissionService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping.

EmergencyContactController

File: Api/Administrator/EmergencyContactController.php
Purpose: manage school identity and operations workflow for emergency contact.
Public methods: index(Request $request), show(EmergencyContactParentRequest $request, int $contactId), update(EmergencyContactUpdateRequest $request, int $contactId), destroy(EmergencyContactParentRequest $request, int $contactId) Detected dependencies: Services: EmergencyContactCrudService, EmergencyContactDirectoryService | Requests: EmergencyContactParentRequest, EmergencyContactUpdateRequest | Resources: EmergencyContactGroupResource, EmergencyContactResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

TeacherClassAssignmentController

File: Api/Administrator/TeacherClassAssignmentController.php
Purpose: manage school identity and operations workflow for teacher class assignment.
Public methods: index(TeacherAssignmentListRequest $request), store(TeacherAssignmentStoreRequest $request), destroy(TeacherAssignmentDeleteRequest $request) Detected dependencies: Services: TeacherAssignmentService | Requests: TeacherAssignmentDeleteRequest, TeacherAssignmentListRequest, TeacherAssignmentStoreRequest | Resources: TeacherAssignmentResource, TeacherClassResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission; delete success, already deleted, protected record.

Assignment

AssignmentApiController

File: Api/Assignment/AssignmentApiController.php
Purpose: serve assignment api API responsibilities.
Public methods: index(Request $request), store(Request $request), classAssignmentData() Detected dependencies: Services: AssignmentService | Resources: AssignmentOverviewResource, AssignmentSectionResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission.

Attendance

AdminAttendanceApiController

File: Api/Attendance/AdminAttendanceApiController.php
Purpose: manage attendance workflow for admin attendance api.
Public methods: dailyData(Request $request), updateManagement(UpdateAttendanceManagementRequest $request), addEntry(AdminAddAttendanceEntryRequest $request) Detected dependencies: Services: AttendanceQueryService, AttendanceService | Requests: AdminAddAttendanceEntryRequest, UpdateAttendanceManagementRequest | Resources: DailyAttendanceResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; update authorization, partial payload, concurrency/transaction rollback.

AttendanceCommentTemplateController

File: Api/Attendance/AttendanceCommentTemplateController.php
Purpose: manage attendance workflow for attendance comment template.
Public methods: bootstrapUrls(), index(Request $request), listData(Request $request), show(int $id), store(Request $request), update(Request $request, int $id), destroy(int $id), legacySave(Request $request), legacyDelete(Request $request) Detected dependencies: Services: ApplicationUrlService, AttendanceCommentTemplateService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Mutating endpoints need request validation, service-layer ownership, and database transactions where multiple rows change.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

EarlyDismissalsController

File: Api/Attendance/EarlyDismissalsController.php
Purpose: manage attendance workflow for early dismissals.
Public methods: index(Request $request), studentOptions(), store(Request $request), uploadSignature(Request $request) Detected dependencies: Models: Configuration, EarlyDismissalSignature

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Extract business logic into service/action classes if the controller currently queries models or mutates state directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission.

LateSlipLogsController

File: Api/Attendance/LateSlipLogsController.php
Purpose: manage attendance workflow for late slip logs.
Public methods: index(LateSlipLogIndexRequest $request), show(int $id), destroy(int $id) Detected dependencies: Services: LateSlipLogCommandService, LateSlipLogQueryService | Requests: LateSlipLogIndexRequest | Resources: LateSlipLogCollection, LateSlipLogResource | Models: LateSlipLog

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; delete success, already deleted, protected record.

StaffAttendanceApiController

File: Api/Attendance/StaffAttendanceApiController.php
Purpose: manage attendance workflow for staff attendance api.
Public methods: monthData(Request $request), admins(Request $request), saveAdmins(SaveAdminAttendanceRequest $request), saveCell(SaveStaffAttendanceCellRequest $request), monthCsv(Request $request) Detected dependencies: Services: StaffAttendanceService | Requests: SaveAdminAttendanceRequest, SaveStaffAttendanceCellRequest | Resources: AdminAttendanceResource, StaffMonthResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; update authorization, partial payload, concurrency/transaction rollback.

TeacherAttendanceApiController

File: Api/Attendance/TeacherAttendanceApiController.php
Purpose: manage attendance workflow for teacher attendance api.
Public methods: grid(Request $request), form(Request $request), submit(TeacherSubmitAttendanceRequest $request) Detected dependencies: Services: AttendanceQueryService, AttendanceService | Requests: TeacherSubmitAttendanceRequest | Resources: TeacherAttendanceFormResource, TeacherGridResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission.

AttendanceTracking

AttendanceTrackingController

File: Api/AttendanceTracking/AttendanceTrackingController.php
Purpose: manage attendance workflow for attendance tracking.
Public methods: pendingViolations(Request $request), notifiedViolations(Request $request), studentCase(int $studentId, Request $request), record(Request $request), sendAutoEmails(Request $request), compose(Request $request), sendManualEmail(Request $request), parentsInfo(Request $request), saveNotificationNote(Request $request) Detected dependencies: Services: AttendanceTrackingService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

Auth

AuthController

File: Api/Auth/AuthController.php
Purpose: handle authentication/authorization workflow for auth.
Public methods: login(Request $request, ApiLoginSecurityService $security), refresh(Request $request), me(), logout(Request $request) Detected dependencies: Services: ApiLoginSecurityService | Models: User

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Feature tests: happy path, unauthorized path, invalid input, service exception; role matrix: allowed, denied, expired session.

AuthSessionController

File: Api/Auth/AuthSessionController.php
Purpose: handle authentication/authorization workflow for auth session.
Public methods: loginMask(Request $request), login(LoginSessionRequest $request), logout(Request $request), selectRole(Request $request), setRole(SetRoleSessionRequest $request) Detected dependencies: Services: ApplicationUrlService, ApiLoginSecurityService, AuthSessionService | Requests: LoginSessionRequest, SetRoleSessionRequest | Models: User

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• This controller is large enough to hide bugs. Split orchestration from business logic before it becomes archaeology.
• Feature tests: happy path, unauthorized path, invalid input, service exception; role matrix: allowed, denied, expired session.

IpBanController

File: Api/Auth/IpBanController.php
Purpose: handle authentication/authorization workflow for ip ban.
Public methods: index(IpBanIndexRequest $request), show(int $id), ban(IpBanRequest $request), unban(IpUnbanRequest $request) Detected dependencies: Services: IpBanCommandService, IpBanQueryService | Requests: IpBanIndexRequest, IpBanRequest, IpUnbanRequest | Resources: IpBanCollection, IpBanResource | Models: IpAttempt

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; role matrix: allowed, denied, expired session.

RegisterController

File: Api/Auth/RegisterController.php
Purpose: handle authentication/authorization workflow for register.
Public methods: captcha(), store(Request $request) Detected dependencies: Services: ApiRegistrationService, RegistrationCaptchaService, RegistrationService | Resources: RegisterResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: create/submit validation, happy path, duplicate submission; role matrix: allowed, denied, expired session.

RolePermissionController

File: Api/Auth/RolePermissionController.php
Purpose: handle authentication/authorization workflow for role permission.
Public methods: roles(RoleListRequest $request), showRole(int $roleId), storeRole(RoleStoreRequest $request), updateRole(RoleUpdateRequest $request, int $roleId), deleteRole(int $roleId), users(UserRoleListRequest $request), assignRoles(AssignUserRolesRequest $request, int $userId), permissions(), showPermission(int $permissionId), storePermission(PermissionStoreRequest $request), updatePermission(PermissionUpdateRequest $request, int $permissionId), deletePermission(int $permissionId), rolePermissions(int $roleId), updateRolePermissions(RolePermissionUpdateRequest $request, int $roleId) Detected dependencies: Services: PermissionCrudService, RoleAssignmentService, RoleCrudService, RolePermissionService, RoleQueryService | Requests: AssignUserRolesRequest, PermissionStoreRequest, PermissionUpdateRequest, RoleListRequest, RolePermissionUpdateRequest, RoleStoreRequest, RoleUpdateRequest, UserRoleListRequest | Resources: PermissionResource, RolePermissionResource, RoleResource, UserWithRolesResource | Models: Permission, Role

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: update authorization, partial payload, concurrency/transaction rollback; role matrix: allowed, denied, expired session.

RoleSwitcherController

File: Api/Auth/RoleSwitcherController.php
Purpose: handle authentication/authorization workflow for role switcher.
Public methods: index(), switch(RoleSwitchRequest $request) Detected dependencies: Services: RoleSwitchService | Requests: RoleSwitchRequest

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; role matrix: allowed, denied, expired session.

SessionTimeoutController

File: Api/Auth/SessionTimeoutController.php
Purpose: handle authentication/authorization workflow for session timeout.
Public methods: getTimeoutConfig(), checkTimeout(Request $request), pingActivity(Request $request) Detected dependencies: Services: ApplicationUrlService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Feature tests: happy path, unauthorized path, invalid input, service exception; role matrix: allowed, denied, expired session.

BadgeScan

BadgeScanController

File: Api/BadgeScan/BadgeScanController.php
Purpose: serve badge scan API responsibilities.
Public methods: scan(Request $request), logs() Detected dependencies: Services: BadgeScanService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

Badges

BadgeController

File: Api/Badges/BadgeController.php
Purpose: serve badge API responsibilities.
Public methods: generatePdf(Request $request), printStatus(Request $request), logPrint(Request $request), formData(Request $request) Detected dependencies: Services: BadgeFormDataService, BadgePdfService, BadgePrintLogService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

Certificates

CertificateController

File: Api/Certificates/CertificateController.php
Purpose: serve certificate API responsibilities.
Public methods: formOptions(Request $request), generate(Request $request) Detected dependencies: Services: CertificatePdfService | Models: Configuration

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

ClassPreparation

ClassPreparationController

File: Api/ClassPreparation/ClassPreparationController.php
Purpose: serve class preparation API responsibilities.
Public methods: index(ClassPreparationIndexRequest $request), markPrinted(ClassPreparationMarkPrintedRequest $request), saveAdjustments(ClassPreparationAdjustmentRequest $request), print(ClassPreparationPrintRequest $request), stickerCounts(Request $request), studentsByClass(Request $request, int $classSectionId) Detected dependencies: Services: ClassRosterService, StickerCountService, ClassPreparationService | Requests: ClassPreparationAdjustmentRequest, ClassPreparationIndexRequest, ClassPreparationMarkPrintedRequest, ClassPreparationPrintRequest | Resources: ClassPreparationPrintResource, ClassPreparationResultResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Validate file type, size, storage path, and access ownership.
• Generated documents need reproducible inputs and predictable naming.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping.

ClassProgress

ClassProgressController

File: Api/ClassProgress/ClassProgressController.php
Purpose: serve class progress API responsibilities.
Public methods: meta(ClassProgressMetaRequest $request), legacySubmitForm(ClassProgressMetaRequest $request), index(ClassProgressIndexRequest $request), store(ClassProgressStoreRequest $request), show(ClassProgressReport $class_progress), update(ClassProgressUpdateRequest $request, ClassProgressReport $class_progress), destroy(ClassProgressReport $class_progress), downloadAttachment(int $attachment), downloadLegacyAttachment(ClassProgressReport $class_progress) Detected dependencies: Services: ClassProgressAttachmentService, ClassProgressMetaService, ClassProgressMutationService, ClassProgressQueryService | Requests: ClassProgressIndexRequest, ClassProgressMetaRequest, ClassProgressStoreRequest, ClassProgressUpdateRequest | Resources: ClassProgressGroupCollection, ClassProgressReportResource, ClassProgressShowResource | Models: ClassProgressAttachment, ClassProgressReport, Configuration, User

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

Classes

ClassController

File: Api/Classes/ClassController.php
Purpose: serve class API responsibilities.
Public methods: index(ClassSectionIndexRequest $request), show(ClassSection $classSection), store(ClassSectionStoreRequest $request), update(ClassSectionUpdateRequest $request, ClassSection $classSection), destroy(ClassSection $classSection), attendance(Request $request, int $classSectionId), seedDefaults() Detected dependencies: Services: ClassAttendanceService, ClassSectionCommandService, ClassSectionQueryService, ClassSectionSeedService | Requests: ClassSectionIndexRequest, ClassSectionStoreRequest, ClassSectionUpdateRequest | Resources: ClassAttendanceResource, ClassSectionCollection, ClassSectionResource | Models: ClassSection

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

Communication

CommunicationController

File: Api/Communication/CommunicationController.php
Purpose: serve communication API responsibilities.
Public methods: options(), families(int $studentId), guardians(int $familyId), preview(Request $request), send(Request $request) Detected dependencies: Services: CommunicationFamilyService, CommunicationPreviewService, CommunicationSendService, CommunicationStudentService, CommunicationTemplateService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

CompetitionScores

CompetitionScoresController

File: Api/CompetitionScores/CompetitionScoresController.php
Purpose: manage academic scoring/grading workflow for competition scores.
Public methods: index(Request $request), edit(Request $request, int $id), save(Request $request, int $id) Detected dependencies: Services: CompetitionScoresContextService, CompetitionScoresQueryService, CompetitionScoresRosterService, CompetitionScoresSaveService | Models: Competition

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission.

Core

BaseApiController

File: Api/Core/BaseApiController.php
Purpose: shared API response, validation, auth, and compatibility foundation.
Public methods: No public endpoint methods detected. Detected dependencies: Models: User

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Extract business logic into service/action classes if the controller currently queries models or mutates state directly.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• This controller is large enough to hide bugs. Split orchestration from business logic before it becomes archaeology.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

Discounts

DiscountController

File: Api/Discounts/DiscountController.php
Purpose: serve discount API responsibilities.
Public methods: options(), apply(ApplyDiscountVoucherRequest $request), listVouchers(), storeVoucher(StoreDiscountVoucherRequest $request), updateVoucher(UpdateDiscountVoucherRequest $request, int $id), showVoucher(int $id), deleteVoucher(int $id) Detected dependencies: Services: DiscountApplyService, DiscountContextService, DiscountParentService, DiscountVoucherService | Requests: ApplyDiscountVoucherRequest, StoreDiscountVoucherRequest, UpdateDiscountVoucherRequest | Resources: DiscountParentResource, DiscountVoucherResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

Documentation

ApiDocsAdminController

File: Api/Documentation/ApiDocsAdminController.php
Purpose: serve api docs admin API responsibilities.
Public methods: index(), public() Detected dependencies: Services: ApiDocsService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping.

DocsCatalogController

File: Api/Documentation/DocsCatalogController.php
Purpose: serve docs catalog API responsibilities.
Public methods: index(Request $request), ui(), swagger(), swaggerMergedJson() Detected dependencies: Services: DocsCatalogService, OpenApiRouteExporter

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Validate file type, size, storage path, and access ownership.
• Generated documents need reproducible inputs and predictable naming.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping.

Email

BroadcastEmailController

File: Api/Email/BroadcastEmailController.php
Purpose: serve broadcast email API responsibilities.
Public methods: options(), send(Request $request), uploadImage(Request $request) Detected dependencies: Services: BroadcastEmailComposerService, BroadcastEmailDispatchService, BroadcastEmailImageService, BroadcastEmailRecipientService, BroadcastEmailSenderOptionsService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

EmailController

File: Api/Email/EmailController.php
Purpose: serve email API responsibilities.
Public methods: senders(), send(EmailSendRequest $request) Detected dependencies: Services: EmailAttachmentService, EmailDispatchService, EmailSenderOptionsService | Requests: EmailSendRequest | Resources: EmailSenderResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

EmailExtractorController

File: Api/Email/EmailExtractorController.php
Purpose: serve email extractor API responsibilities.
Public methods: emails(), compare(EmailExtractorCompareRequest $request) Detected dependencies: Services: EmailExtractorService | Requests: EmailExtractorCompareRequest | Resources: EmailExtractorCompareResource, EmailExtractorEmailsResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

Exams

ExamDraftController

File: Api/Exams/ExamDraftController.php
Purpose: serve exam draft API responsibilities.
Public methods: teacherIndex(), teacherStore(ExamDraftTeacherStoreRequest $request), adminIndex(), adminUploadLegacy(ExamDraftAdminLegacyRequest $request), adminReview(ExamDraftAdminReviewRequest $request) Detected dependencies: Services: ExamDraftAdminService, ExamDraftTeacherService | Requests: ExamDraftAdminLegacyRequest, ExamDraftAdminReviewRequest, ExamDraftTeacherStoreRequest | Resources: ExamDraftResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

Expenses

ExpenseController

File: Api/Expenses/ExpenseController.php
Purpose: serve expense API responsibilities.
Public methods: options(), index(), show(int $id), store(StoreExpenseRequest $request), update(UpdateExpenseRequest $request, int $id), updateStatus(UpdateExpenseStatusRequest $request, int $id) Detected dependencies: Services: ExpenseContextService, ExpenseQueryService, ExpenseReceiptService, ExpenseRetailorService, ExpenseStaffService, ExpenseStatusService, ExpenseWriteService | Requests: StoreExpenseRequest, UpdateExpenseRequest, UpdateExpenseStatusRequest | Resources: ExpenseResource, ExpenseStaffResource | Models: Expense

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Mutating endpoints need request validation, service-layer ownership, and database transactions where multiple rows change.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback.

ExtraCharges

ExtraChargesController

File: Api/ExtraCharges/ExtraChargesController.php
Purpose: manage finance workflow for extra charges, with money-state integrity as the main risk.
Public methods: list(Request $request), options(Request $request), parentOptions(Request $request), invoicesForParent(Request $request), store(StoreExtraChargeRequest $request), update(UpdateExtraChargeRequest $request, int $id), void(int $id), reverse(int $id) Detected dependencies: Services: ExtraChargesChargeService, ExtraChargesContextService, ExtraChargesInvoiceService, ExtraChargesListService, ExtraChargesMetaService, ExtraChargesParentService | Requests: StoreExtraChargeRequest, UpdateExtraChargeRequest | Resources: ExtraChargeInvoiceOptionResource, ExtraChargeParentOptionResource, ExtraChargeResource | Models: AdditionalCharge

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; idempotency and ledger/audit consistency.

Family

FamilyAdminController

File: Api/Family/FamilyAdminController.php
Purpose: manage school identity and operations workflow for family admin.
Public methods: index(FamilyAdminIndexRequest $request), search(FamilyAdminSearchRequest $request), card(FamilyAdminCardRequest $request), composeEmail(FamilyComposeEmailRequest $request) Detected dependencies: Services: FamilyNotificationService, FamilyQueryService | Requests: FamilyAdminCardRequest, FamilyAdminIndexRequest, FamilyAdminSearchRequest, FamilyComposeEmailRequest | Resources: FamilyResource, FamilySearchItemResource | Models: Configuration

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping.

FamilyController

File: Api/Family/FamilyController.php
Purpose: manage school identity and operations workflow for family.
Public methods: familiesByStudent(FamiliesByStudentRequest $request, int $studentId), guardiansByFamily(GuardiansByFamilyRequest $request, int $familyId), bootstrap(FamilyBootstrapRequest $request), attachSecondByUser(FamilyAttachSecondByUserRequest $request), attachSecondByEmail(FamilyAttachSecondByEmailRequest $request), setPrimaryHome(FamilySetPrimaryHomeRequest $request), setGuardianFlags(FamilySetGuardianFlagsRequest $request), unlinkGuardian(FamilyUnlinkGuardianRequest $request), unlinkStudent(FamilyUnlinkStudentRequest $request), importSecondParentsFromLegacy(FamilyImportLegacyRequest $request) Detected dependencies: Services: FamilyMutationService, FamilyQueryService | Requests: FamiliesByStudentRequest, FamilyAttachSecondByEmailRequest, FamilyAttachSecondByUserRequest, FamilyBootstrapRequest, FamilyImportLegacyRequest, FamilySetGuardianFlagsRequest, FamilySetPrimaryHomeRequest, FamilyUnlinkGuardianRequest… | Resources: FamilyGuardianResource, FamilyResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

Finance

ChargeController

File: Api/Finance/ChargeController.php
Purpose: manage finance workflow for charge, with money-state integrity as the main risk.
Public methods: index(ChargeListRequest $request), storeExtra(StoreExtraChargeRequest $request), storeEvent(StoreEventChargeRequest $request), cancelExtra(int $id), applyExtra(ApplyExtraChargeRequest $request, int $id), cancelEvent(Request $request, int $id), markEventPaid(MarkEventChargePaidRequest $request, int $id) Detected dependencies: Services: ChargeService | Requests: ApplyExtraChargeRequest, ChargeListRequest, MarkEventChargePaidRequest, StoreEventChargeRequest, StoreExtraChargeRequest | Resources: ChargeActionResource, ChargeListResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; idempotency and ledger/audit consistency.

FeeCalculationController

File: Api/Finance/FeeCalculationController.php
Purpose: manage finance workflow for fee calculation, with money-state integrity as the main risk.
Public methods: refund(FeeRefundRequest $request), tuitionTotal(FeeTuitionTotalRequest $request), tuitionBreakdown(FeeTuitionBreakdownRequest $request), familyBalance(FeeFamilyBalanceRequest $request) Detected dependencies: Services: BalanceCalculationService, FeeRefundCalculatorService, FeeStudentFeeService, TuitionCalculationService | Requests: FeeFamilyBalanceRequest, FeeRefundRequest, FeeTuitionBreakdownRequest, FeeTuitionTotalRequest | Resources: FeeFamilyBalanceResource, FeeRefundResource, FeeTuitionBreakdownResource, FeeTuitionTotalResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Feature tests: happy path, unauthorized path, invalid input, service exception; idempotency and ledger/audit consistency.

FinancialController

File: Api/Finance/FinancialController.php
Purpose: manage finance workflow for financial, with money-state integrity as the main risk.
Public methods: report(FinancialReportRequest $request), summary(FinancialSummaryRequest $request), unpaidParents(FinancialUnpaidParentsRequest $request), downloadCsv(FinancialReportRequest $request), downloadPdf(FinancialReportRequest $request) Detected dependencies: Services: FinancialPdfReportService, FinancialReportService, FinancialSchoolYearService, FinancialSummaryService, FinancialUnpaidParentsService | Requests: FinancialReportRequest, FinancialSummaryRequest, FinancialUnpaidParentsRequest | Resources: FinancialReportResource, FinancialSummaryResource, FinancialUnpaidParentResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Validate file type, size, storage path, and access ownership.
• Generated documents need reproducible inputs and predictable naming.
• Feature tests: happy path, unauthorized path, invalid input, service exception; idempotency and ledger/audit consistency.

InvoiceController

File: Api/Finance/InvoiceController.php
Purpose: manage finance workflow for invoice, with money-state integrity as the main risk.
Public methods: management(InvoiceManagementRequest $request), generate(Request $request), byParent(InvoiceParentRequest $request, int $parentId), parentPayment(InvoiceParentRequest $request), updateStatus(InvoiceStatusRequest $request, int $invoiceId), unpaid(), pdf(int $invoiceId) Detected dependencies: Services: InvoiceGenerationService, InvoiceManagementService, InvoicePaymentService, InvoicePdfService | Requests: InvoiceManagementRequest, InvoiceParentRequest, InvoiceStatusRequest | Resources: InvoiceManagementParentResource, InvoiceResource | Models: Invoice

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception; idempotency and ledger/audit consistency.

PaymentController

File: Api/Finance/PaymentController.php
Purpose: manage finance workflow for payment, with money-state integrity as the main risk.
Public methods: store(Request $request), byParent(PaymentByParentRequest $request, int $parentId), updateBalance(Request $request, int $paymentId) Detected dependencies: Services: PaymentBalanceService, PaymentLookupService, PaymentPlanService | Requests: PaymentByParentRequest | Resources: PaymentResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: create/submit validation, happy path, duplicate submission; idempotency and ledger/audit consistency.

PaymentEventChargesController

File: Api/Finance/PaymentEventChargesController.php
Purpose: manage finance workflow for payment event charges, with money-state integrity as the main risk.
Public methods: index(PaymentEventChargesListRequest $request), store(Request $request), enrolledStudents(PaymentEventChargesListRequest $request, int $parentId) Detected dependencies: Services: PaymentEventChargesService | Requests: PaymentEventChargesListRequest

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission; idempotency and ledger/audit consistency.

PaymentManualController

File: Api/Finance/PaymentManualController.php
Purpose: manage finance workflow for payment manual, with money-state integrity as the main risk.
Public methods: search(Request $request), suggest(Request $request), record(PaymentManualUpdateRequest $request, int $invoiceId), edit(PaymentManualEditRequest $request, int $paymentId), file(Request $request, string $filename) Detected dependencies: Services: PaymentManualService | Requests: PaymentManualEditRequest, PaymentManualUpdateRequest

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception; idempotency and ledger/audit consistency.

PaymentNotificationController

File: Api/Finance/PaymentNotificationController.php
Purpose: manage finance workflow for payment notification, with money-state integrity as the main risk.
Public methods: index(PaymentNotificationListRequest $request), send(PaymentNotificationSendRequest $request) Detected dependencies: Services: PaymentNotificationService | Requests: PaymentNotificationListRequest, PaymentNotificationSendRequest | Resources: PaymentNotificationLogResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; idempotency and ledger/audit consistency.

PaymentTransactionController

File: Api/Finance/PaymentTransactionController.php
Purpose: manage finance workflow for payment transaction, with money-state integrity as the main risk.
Public methods: store(Request $request), byPayment(int $paymentId), updateStatus(Request $request, string $transactionId) Detected dependencies: Services: PaymentTransactionService | Resources: PaymentTransactionResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: create/submit validation, happy path, duplicate submission; idempotency and ledger/audit consistency.

PaypalPaymentController

File: Api/Finance/PaypalPaymentController.php
Purpose: manage finance workflow for paypal payment, with money-state integrity as the main risk.
Public methods: redirect(), create(int $paymentId), execute(PaypalExecuteRequest $request), cancel() Detected dependencies: Services: PaypalPaymentService | Requests: PaypalExecuteRequest

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: create/submit validation, happy path, duplicate submission; idempotency and ledger/audit consistency.

PaypalTransactionsController

File: Api/Finance/PaypalTransactionsController.php
Purpose: manage finance workflow for paypal transactions, with money-state integrity as the main risk.
Public methods: index(PaypalTransactionsListRequest $request), downloadCsv(PaypalTransactionsListRequest $request) Detected dependencies: Services: PaypalTransactionsService | Requests: PaypalTransactionsListRequest | Resources: PaypalTransactionResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; idempotency and ledger/audit consistency.

PurchaseOrderController

File: Api/Finance/PurchaseOrderController.php
Purpose: manage finance workflow for purchase order, with money-state integrity as the main risk.
Public methods: index(PurchaseOrderIndexRequest $request), options(), show(int $id), store(Request $request), receive(Request $request, int $id), cancel(int $id) Detected dependencies: Services: PurchaseOrderCreateService, PurchaseOrderQueryService, PurchaseOrderReceiveService, PurchaseOrderStatusService | Requests: PurchaseOrderIndexRequest | Resources: PurchaseOrderItemResource, PurchaseOrderResource | Models: PurchaseOrder

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; idempotency and ledger/audit consistency.

RefundController

File: Api/Finance/RefundController.php
Purpose: manage finance workflow for refund, with money-state integrity as the main risk.
Public methods: index(RefundIndexRequest $request), show(int $refundId), store(RefundStoreRequest $request), update(RefundDecisionRequest $request, int $refundId), destroy(int $refundId), approve(int $refundId), reject(RefundRejectRequest $request, int $refundId), recordPayment(RefundPaymentRequest $request, int $refundId), recalculateOverpayments(RefundRecalculateRequest $request), parentBalances(int $parentId) Detected dependencies: Services: RefundDecisionService, RefundOverpaymentService, RefundPayoutService, RefundQueryService, RefundRequestService, RefundSummaryService | Requests: RefundDecisionRequest, RefundIndexRequest, RefundPaymentRequest, RefundRecalculateRequest, RefundRejectRequest, RefundStoreRequest | Resources: RefundResource | Models: Configuration

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record; idempotency and ledger/audit consistency.

ReimbursementController

File: Api/Finance/ReimbursementController.php
Purpose: manage finance workflow for reimbursement, with money-state integrity as the main risk.
Public methods: underProcessing(ReimbursementUnderProcessingRequest $request), markDonation(Request $request), createBatch(Request $request), updateBatchAssignment(ReimbursementBatchAssignmentRequest $request), lockBatch(ReimbursementBatchLockRequest $request), uploadBatchAdminFile(ReimbursementBatchAdminFileRequest $request), serveAdminCheckFile(FileNameRequest $request, string $name, string $mode = 'inline'), index(ReimbursementIndexRequest $request), sendBatchEmail(ReimbursementBatchEmailRequest $request), export(ReimbursementExportRequest $request), exportBatch(ReimbursementExportBatchRequest $request), store(Request $request), process(ReimbursementProcessRequest $request), reimbursedExpenses(), update(Request $request, int $id) Detected dependencies: Services: FileServeService, ReimbursementBatchAssignmentService, ReimbursementBatchService, ReimbursementContextService, ReimbursementCrudService, ReimbursementDonationService, ReimbursementEmailService, ReimbursementExportService… | Requests: FileNameRequest, ReimbursementBatchAdminFileRequest, ReimbursementBatchAssignmentRequest, ReimbursementBatchEmailRequest, ReimbursementBatchLockRequest, ReimbursementExportBatchRequest, ReimbursementExportRequest, ReimbursementIndexRequest… | Resources: ReimbursementBatchResource, ReimbursementExpenseResource, ReimbursementRecipientResource, ReimbursementResource, ReimbursementUnderProcessingItemResource | Models: Reimbursement, ReimbursementBatch

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; idempotency and ledger/audit consistency.

Frontend

FrontendController

File: Api/Frontend/FrontendController.php
Purpose: serve frontend API responsibilities.
Public methods: index(), facility(), team(), callToAction(), testimonial(), notFound(), fetchUser() Detected dependencies: Services: FrontendPageService | Resources: FrontendPageResource, FrontendUserResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping.

InfoIconController

File: Api/Frontend/InfoIconController.php
Purpose: serve info icon API responsibilities.
Public methods: profileIcon() Detected dependencies: Services: ProfileIconService | Resources: ProfileIconResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

LandingPageController

File: Api/Frontend/LandingPageController.php
Purpose: serve landing page API responsibilities.
Public methods: index(LandingTeacherRequest $request), teacher(LandingTeacherRequest $request), parent(), administrator(), admin(), student(), guest() Detected dependencies: Services: LandingPageService | Requests: LandingTeacherRequest | Resources: LandingPageResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping.

PageController

File: Api/Frontend/PageController.php
Purpose: serve page API responsibilities.
Public methods: privacyPolicy(), termsOfService(), helpCenter(), submitContact(ContactSubmitRequest $request) Detected dependencies: Services: ContactSubmissionService, StaticPageService | Requests: ContactSubmitRequest | Resources: ContactSubmissionResource, PageContentResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

Grading

GradingController

File: Api/Grading/GradingController.php
Purpose: manage academic scoring/grading workflow for grading.
Public methods: overview(GradingOverviewRequest $request), show(GradingScoreShowRequest $request, string $type, int $classSectionId, int $studentId), update(GradingScoreUpdateRequest $request), toggleLock(GradingLockRequest $request), lockAll(GradingLockAllRequest $request), refresh(GradingRefreshRequest $request), placement(PlacementRequest $request), updatePlacementLevel(PlacementLevelRequest $request), updatePlacementLevels(PlacementLevelsRequest $request), createPlacementBatch(PlacementBatchRequest $request), showPlacementBatch(int $batchId), updatePlacementBatch(PlacementBatchUpdateRequest $request, int $batchId), belowSixty(BelowSixtyListRequest $request), belowSixtyEmail(BelowSixtyEmailRequest $request), sendBelowSixtyEmail(BelowSixtySendRequest $request), updateBelowSixtyStatus(BelowSixtyStatusRequest $request), belowSixtyMeeting(BelowSixtyMeetingRequest $request), saveBelowSixtyMeeting(BelowSixtyMeetingSaveRequest $request) Detected dependencies: Services: GradingBelowSixtyService, GradingLockService, GradingOverviewService, GradingPlacementService, GradingRefreshService, GradingScoreService | Requests: BelowSixtyEmailRequest, BelowSixtyMeetingRequest, BelowSixtyMeetingSaveRequest, BelowSixtySendRequest, BelowSixtyStatusRequest, BelowSixtyListRequest, GradingLockAllRequest, GradingLockRequest… | Resources: BelowSixtyStudentResource, GradingScoreResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: show success, missing record, unauthorized record; update authorization, partial payload, concurrency/transaction rollback.

HomeworkTrackingController

File: Api/Grading/HomeworkTrackingController.php
Purpose: manage academic scoring/grading workflow for homework tracking.
Public methods: index(HomeworkTrackingRequest $request) Detected dependencies: Services: HomeworkTrackingService | Requests: HomeworkTrackingRequest | Resources: HomeworkTrackingTeacherResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Validate file type, size, storage path, and access ownership.
• Generated documents need reproducible inputs and predictable naming.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping.

Incidents

IncidentController

File: Api/Incidents/IncidentController.php
Purpose: serve incident API responsibilities.
Public methods: current(), formMeta(), history(IncidentListRequest $request), processed(IncidentListRequest $request), analysis(IncidentListRequest $request), studentsByGrade(int $gradeId), store(Request $request), updateState(IncidentStateRequest $request, int $incidentId), close(Request $request, int $incidentId), cancel(IncidentCancelRequest $request, int $incidentId) Detected dependencies: Services: CurrentIncidentService, IncidentAnalysisService, IncidentHistoryService | Requests: IncidentCancelRequest, IncidentCloseRequest, IncidentListRequest, IncidentStateRequest | Resources: IncidentAnalysisStudentResource, IncidentGradeResource, IncidentResource, IncidentStudentOptionResource | Models: Configuration

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Mutating endpoints need request validation, service-layer ownership, and database transactions where multiple rows change.
• Feature tests: create/submit validation, happy path, duplicate submission.

Inventory

InventoryCategoryController

File: Api/Inventory/InventoryCategoryController.php
Purpose: provide CRUD API endpoints for inventory category.
Public methods: index(InventoryCategoryIndexRequest $request), store(InventoryCategoryStoreRequest $request), update(InventoryCategoryUpdateRequest $request, int $id), destroy(int $id) Detected dependencies: Services: InventoryCategoryService | Requests: InventoryCategoryIndexRequest, InventoryCategoryStoreRequest, InventoryCategoryUpdateRequest | Resources: InventoryCategoryResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

InventoryController

File: Api/Inventory/InventoryController.php
Purpose: serve inventory API responsibilities.
Public methods: index(InventoryItemIndexRequest $request), show(int $id), store(InventoryItemStoreRequest $request), update(InventoryItemUpdateRequest $request, int $id), destroy(int $id), audit(InventoryAuditRequest $request, int $id), adjust(InventoryAdjustRequest $request, int $id), summary(string $type), summaryAll(), teacherDistribution(InventoryTeacherDistributionRequest $request), teacherDistributionStore(InventoryTeacherDistributionStoreRequest $request) Detected dependencies: Services: InventoryItemService, InventorySummaryService, InventoryTeacherDistributionService | Requests: InventoryAdjustRequest, InventoryAuditRequest, InventoryItemIndexRequest, InventoryItemStoreRequest, InventoryItemUpdateRequest, InventoryTeacherDistributionRequest, InventoryTeacherDistributionStoreRequest | Resources: InventoryItemResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Mutating endpoints need request validation, service-layer ownership, and database transactions where multiple rows change.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

InventoryMovementController

File: Api/Inventory/InventoryMovementController.php
Purpose: serve inventory movement API responsibilities.
Public methods: index(InventoryMovementIndexRequest $request), store(InventoryMovementStoreRequest $request), update(InventoryMovementUpdateRequest $request, int $id), destroy(int $id), bulkDelete(InventoryMovementBulkDeleteRequest $request) Detected dependencies: Services: InventoryMovementService | Requests: InventoryMovementBulkDeleteRequest, InventoryMovementIndexRequest, InventoryMovementStoreRequest, InventoryMovementUpdateRequest | Resources: InventoryMovementResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

SupplierController

File: Api/Inventory/SupplierController.php
Purpose: provide CRUD API endpoints for supplier.
Public methods: index(SupplierIndexRequest $request), store(SupplierStoreRequest $request), update(SupplierUpdateRequest $request, int $id), destroy(int $id) Detected dependencies: Services: SupplierService | Requests: SupplierIndexRequest, SupplierStoreRequest, SupplierUpdateRequest | Resources: SupplierResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

SupplyCategoryController

File: Api/Inventory/SupplyCategoryController.php
Purpose: provide CRUD API endpoints for supply category.
Public methods: index(), store(SupplyCategoryStoreRequest $request), update(SupplyCategoryUpdateRequest $request, int $id), destroy(int $id) Detected dependencies: Services: SupplyCategoryService | Requests: SupplyCategoryStoreRequest, SupplyCategoryUpdateRequest | Resources: SupplyCategoryResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

Messaging

MessagesController

File: Api/Messaging/MessagesController.php
Purpose: serve messages API responsibilities.
Public methods: index(MessageIndexRequest $request), inbox(MessageIndexRequest $request), sent(MessageIndexRequest $request), drafts(MessageIndexRequest $request), trash(MessageIndexRequest $request), show(int $id), store(MessageSendRequest $request), receive(), recipients(string $type), update(MessageUpdateRequest $request, int $id), destroy(int $id) Detected dependencies: Services: MessageCommandService, MessageQueryService, MessageRecipientService | Requests: MessageIndexRequest, MessageSendRequest, MessageUpdateRequest | Resources: MessageCollection, MessageResource, RecipientResource | Models: Message

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

WhatsappController

File: Api/Messaging/WhatsappController.php
Purpose: serve whatsapp API responsibilities.
Public methods: index(WhatsappLinkIndexRequest $request), show(int $linkId), store(WhatsappLinkStoreRequest $request), update(WhatsappLinkUpdateRequest $request, int $linkId), destroy(int $linkId), parentContacts(WhatsappParentContactsRequest $request), parentContactsByClass(WhatsappParentContactsByClassRequest $request), sendInvites(WhatsappInviteSendRequest $request), updateMembership(WhatsappMembershipUpdateRequest $request) Detected dependencies: Services: WhatsappContactService, WhatsappContextService, WhatsappInviteService, WhatsappLinkService, WhatsappMembershipService | Requests: WhatsappInviteSendRequest, WhatsappLinkIndexRequest, WhatsappLinkStoreRequest, WhatsappLinkUpdateRequest, WhatsappMembershipUpdateRequest, WhatsappParentContactsByClassRequest, WhatsappParentContactsRequest | Resources: WhatsappClassSectionContactResource, WhatsappGroupLinkCollection, WhatsappGroupLinkResource, WhatsappParentContactResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

Notifications

NotificationController

File: Api/Notifications/NotificationController.php
Purpose: serve notification API responsibilities.
Public methods: index(NotificationIndexRequest $request), show(int $notificationId), store(NotificationSendRequest $request), update(NotificationUpdateRequest $request, int $notificationId), destroy(int $notificationId), restore(int $notificationId), markRead(int $notificationId), active(NotificationActiveRequest $request), deleted(NotificationDeletedRequest $request) Detected dependencies: Services: NotificationActiveService, NotificationDeletedService, NotificationManagementService, NotificationReadService, NotificationSendService, NotificationShowService, NotificationUserListService | Requests: NotificationActiveRequest, NotificationDeletedRequest, NotificationIndexRequest, NotificationSendRequest, NotificationUpdateRequest | Resources: NotificationResource, UserNotificationResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

Parents

AuthorizedUserInviteController

File: Api/Parents/AuthorizedUserInviteController.php
Purpose: handle authentication/authorization workflow for authorized user invite.
Public methods: confirm(Request $request), setPasswordForm(Request $request, int $authorizedUserId), savePassword(Request $request, int $authorizedUserId) Detected dependencies: Services: AuthorizedUsersManagementService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception; role matrix: allowed, denied, expired session.

AuthorizedUsersController

File: Api/Parents/AuthorizedUsersController.php
Purpose: handle authentication/authorization workflow for authorized users.
Public methods: index(), show(int $id), store(StoreAuthorizedUserRequest $request), update(UpdateAuthorizedUserRequest $request, int $id), destroy(int $id) Detected dependencies: Services: AuthorizedUsersManagementService | Requests: StoreAuthorizedUserRequest, UpdateAuthorizedUserRequest | Models: AuthorizedUser

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record; role matrix: allowed, denied, expired session.

ParentAttendanceReportController

File: Api/Parents/ParentAttendanceReportController.php
Purpose: manage attendance workflow for parent attendance report.
Public methods: form(), submit(ParentAttendanceReportSubmitRequest $request), list(ParentAttendanceReportListRequest $request), checkExisting(ParentAttendanceReportCheckRequest $request), update(ParentAttendanceReportUpdateRequest $request, int $reportId) Detected dependencies: Services: ParentAttendanceReportService | Requests: ParentAttendanceReportSubmitRequest, ParentAttendanceReportListRequest, ParentAttendanceReportCheckRequest, ParentAttendanceReportUpdateRequest | Resources: ParentAttendanceReportResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback.

ParentController

File: Api/Parents/ParentController.php
Purpose: manage school identity and operations workflow for parent.
Public methods: attendance(ParentAttendanceRequest $request), invoices(ParentInvoiceRequest $request), enrollments(ParentEnrollmentRequest $request), updateEnrollments(ParentEnrollmentActionRequest $request), registration(), storeRegistration(ParentRegistrationRequest $request), updateStudent(ParentStudentUpdateRequest $request, int $studentId), deleteStudent(int $studentId), emergencyContacts(), storeEmergencyContact(ParentEmergencyContactRequest $request), updateEmergencyContact(ParentEmergencyContactRequest $request, int $contactId), profile(), updateProfile(ParentProfileUpdateRequest $request), events(), updateParticipation(ParentEventParticipationRequest $request) Detected dependencies: Services: ParentAttendanceService, ParentEmergencyContactService, ParentEnrollmentService, ParentEventParticipationService, ParentInvoiceService, ParentProfileService, ParentRegistrationService | Requests: ParentAttendanceRequest, ParentEnrollmentActionRequest, ParentEnrollmentRequest, ParentEmergencyContactRequest, ParentEventParticipationRequest, ParentInvoiceRequest, ParentProfileUpdateRequest, ParentRegistrationRequest… | Resources: ParentAttendanceResource, ParentEmergencyContactResource, ParentStudentResource, InvoiceResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

ParentPromotionController

File: Api/Parents/ParentPromotionController.php
Purpose: manage school identity and operations workflow for parent promotion.
Public methods: overview(ParentPromotionOverviewRequest $request), show(int $promotionId), start(int $promotionId), updateSteps(ParentEnrollmentStepRequest $request, int $promotionId), submit(int $promotionId) Detected dependencies: Services: PromotionEnrollmentService, PromotionQueryService | Requests: ParentEnrollmentStepRequest, ParentPromotionOverviewRequest | Resources: StudentPromotionResource | Models: Student, StudentPromotionRecord

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission.

PrintRequests

PrintRequestsController

File: Api/PrintRequests/PrintRequestsController.php
Purpose: serve print requests API responsibilities.
Public methods: teacher(), admin(), store(Request $request), teacherUpdate(Request $request, int $id), adminStatus(Request $request, int $id), destroy(int $id), copy(int $id), handCopy(Request $request), download(int $id) Detected dependencies: Services: PrintRequestsPortalService | Models: PrintRequest, User

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: create/submit validation, happy path, duplicate submission; delete success, already deleted, protected record.

Public

PublicWinnersController

File: Api/Public/PublicWinnersController.php
Purpose: serve public winners API responsibilities.
Public methods: competitionIndex(), competitionShow(int $id) Detected dependencies: Services: PublicWinnersPortalService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

Reports

FilesController

File: Api/Reports/FilesController.php
Purpose: serve files API responsibilities.
Public methods: receipt(FileNameRequest $request, string $name), reimb(FileNameRequest $request, string $name), earlyDismissalSignature(FileNameRequest $request, string $name), examDraftTeacher(FileNameRequest $request, string $name), examDraftFinal(FileNameRequest $request, string $name) Detected dependencies: Services: ExamDraftDownloadNameService, FileServeService | Requests: FileNameRequest | Resources: FileMetaResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

ReportCardsController

File: Api/Reports/ReportCardsController.php
Purpose: serve report cards API responsibilities.
Public methods: meta(ReportCardMetaRequest $request), completeness(ReportCardCompletenessRequest $request), acknowledgement(Request $request), studentReport(ReportCardPdfRequest $request, int $studentId), classReport(ReportCardPdfRequest $request, int $classSectionId) Detected dependencies: Services: ReportCardService | Requests: ReportCardCompletenessRequest, ReportCardMetaRequest, ReportCardPdfRequest | Resources: ReportCardAcknowledgementResource, ReportCardClassSectionResource, ReportCardCompletenessStudentResource, ReportCardStudentMetaResource | Models: Configuration

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Validate file type, size, storage path, and access ownership.
• Generated documents need reproducible inputs and predictable naming.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

SlipPrinterController

File: Api/Reports/SlipPrinterController.php
Purpose: serve slip printer API responsibilities.
Public methods: print(SlipPrintRequest $request), preview(SlipPreviewRequest $request), logs(SlipLogListRequest $request), reprint(SlipReprintRequest $request) Detected dependencies: Services: SlipPrinterService | Requests: SlipLogListRequest, SlipPreviewRequest, SlipPrintRequest, SlipReprintRequest | Resources: LateSlipLogResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

StickersController

File: Api/Reports/StickersController.php
Purpose: serve stickers API responsibilities.
Public methods: formData(StickerFormDataRequest $request), studentsByClass(StickerStudentsByClassRequest $request), print(StickerPrintRequest $request) Detected dependencies: Services: StickerPresetService, StickerPrintService, StickerQueryService | Requests: StickerFormDataRequest, StickerPrintRequest, StickerStudentsByClassRequest | Resources: StickerClassSectionResource, StickerPresetResource, StickerStudentResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Validate file type, size, storage path, and access ownership.
• Generated documents need reproducible inputs and predictable naming.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

Root

BaseApiController

File: Api/BaseApiController.php
Purpose: shared API response, validation, auth, and compatibility foundation.
Public methods: No public endpoint methods detected. Detected dependencies: Models: User

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Extract business logic into service/action classes if the controller currently queries models or mutates state directly.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• This controller is large enough to hide bugs. Split orchestration from business logic before it becomes archaeology.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

RolePermissionController

File: Api/RolePermissionController.php
Purpose: handle authentication/authorization workflow for role permission.
Public methods: roles(RoleListRequest $request), showRole(int $roleId), storeRole(RoleStoreRequest $request), updateRole(RoleUpdateRequest $request, int $roleId), deleteRole(int $roleId), users(UserRoleListRequest $request), assignRoles(AssignUserRolesRequest $request, int $userId), permissions(), showPermission(int $permissionId), storePermission(PermissionStoreRequest $request), updatePermission(PermissionUpdateRequest $request, int $permissionId), deletePermission(int $permissionId), rolePermissions(int $roleId), updateRolePermissions(RolePermissionUpdateRequest $request, int $roleId) Detected dependencies: Services: PermissionCrudService, RoleAssignmentService, RoleCrudService, RolePermissionService, RoleQueryService | Requests: AssignUserRolesRequest, PermissionStoreRequest, PermissionUpdateRequest, RoleListRequest, RolePermissionUpdateRequest, RoleStoreRequest, RoleUpdateRequest, UserRoleListRequest | Resources: PermissionResource, RolePermissionResource, RoleResource, UserWithRolesResource | Models: Permission, Role

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: update authorization, partial payload, concurrency/transaction rollback; role matrix: allowed, denied, expired session.

RoleSwitcherController

File: Api/RoleSwitcherController.php
Purpose: handle authentication/authorization workflow for role switcher.
Public methods: index(), switch(RoleSwitchRequest $request) Detected dependencies: Services: RoleSwitchService | Requests: RoleSwitchRequest

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; role matrix: allowed, denied, expired session.

ScannerController

File: Api/ScannerController.php
Purpose: serve scanner API responsibilities.
Public methods: process(Request $request) Detected dependencies: Models: AttendanceData, AttendanceDay, AttendanceRecord, Configuration, CurrentFlag, LateSlipLog, Payment, SemesterScore…

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Extract business logic into service/action classes if the controller currently queries models or mutates state directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Feature tests: create/submit validation, happy path, duplicate submission.

StatsController

File: Api/StatsController.php
Purpose: provide CRUD API endpoints for stats.
Public methods: index() Detected dependencies: Models: Stats

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Extract business logic into service/action classes if the controller currently queries models or mutates state directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping.

UserController

File: Api/UserController.php
Purpose: serve user API responsibilities.
Public methods: index(UserListRequest $request), store(UserStoreRequest $request), update(UserUpdateRequest $request, int $userId), destroy(int $userId), loginActivity(LoginActivityRequest $request) Detected dependencies: Services: LoginActivityService, UserListService, UserManagementService | Requests: LoginActivityRequest, UserListRequest, UserStoreRequest, UserUpdateRequest | Resources: LoginActivityResource, UserWithRolesResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

Scores

FinalController

File: Api/Scores/FinalController.php
Purpose: manage academic scoring/grading workflow for final.
Public methods: index(Request $request), update(ScoreUpdateRequest $request), bySchoolYear(Request $request) Detected dependencies: Services: ExamScoreService, SemesterScoreService | Requests: ScoreUpdateRequest | Resources: ScoreStudentResource | Models: Student

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; update authorization, partial payload, concurrency/transaction rollback.

HomeworkController

File: Api/Scores/HomeworkController.php
Purpose: manage academic scoring/grading workflow for homework.
Public methods: index(Request $request), update(ScoreUpdateRequest $request), addColumn(ScoreAddColumnRequest $request), bySchoolYear(Request $request) Detected dependencies: Services: HomeworkScoreService, SemesterScoreService | Requests: ScoreAddColumnRequest, ScoreUpdateRequest | Resources: ScoreStudentResource | Models: Student

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; update authorization, partial payload, concurrency/transaction rollback.

MidtermController

File: Api/Scores/MidtermController.php
Purpose: manage academic scoring/grading workflow for midterm.
Public methods: index(Request $request), update(ScoreUpdateRequest $request), bySchoolYear(Request $request) Detected dependencies: Services: ExamScoreService, SemesterScoreService | Requests: ScoreUpdateRequest | Resources: ScoreStudentResource | Models: Student

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; update authorization, partial payload, concurrency/transaction rollback.

ParticipationController

File: Api/Scores/ParticipationController.php
Purpose: manage academic scoring/grading workflow for participation.
Public methods: index(Request $request), update(ScoreUpdateRequest $request), bySchoolYear(Request $request) Detected dependencies: Services: ParticipationScoreService, SemesterScoreService | Requests: ScoreUpdateRequest | Resources: ScoreStudentResource | Models: Student

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; update authorization, partial payload, concurrency/transaction rollback.

ProjectController

File: Api/Scores/ProjectController.php
Purpose: manage academic scoring/grading workflow for project.
Public methods: index(Request $request), update(ScoreUpdateRequest $request), addColumn(ScoreAddColumnRequest $request), bySchoolYear(Request $request) Detected dependencies: Services: ProjectScoreService, SemesterScoreService | Requests: ScoreAddColumnRequest, ScoreUpdateRequest | Resources: ScoreStudentResource | Models: Student

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; update authorization, partial payload, concurrency/transaction rollback.

QuizController

File: Api/Scores/QuizController.php
Purpose: manage academic scoring/grading workflow for quiz.
Public methods: index(Request $request), update(ScoreUpdateRequest $request), addColumn(ScoreAddColumnRequest $request), bySchoolYear(Request $request) Detected dependencies: Services: QuizScoreService, SemesterScoreService | Requests: ScoreAddColumnRequest, ScoreUpdateRequest | Resources: ScoreStudentResource | Models: Student

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; update authorization, partial payload, concurrency/transaction rollback.

ScoreCommentController

File: Api/Scores/ScoreCommentController.php
Purpose: manage academic scoring/grading workflow for score comment.
Public methods: index(ScoreCommentListRequest $request), store(ScoreCommentSaveRequest $request), update(ScoreCommentUpdateRequest $request) Detected dependencies: Services: ScoreCommentService | Requests: ScoreCommentListRequest, ScoreCommentSaveRequest, ScoreCommentUpdateRequest | Resources: ScoreCommentResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Mutating endpoints need request validation, service-layer ownership, and database transactions where multiple rows change.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback.

ScoreController

File: Api/Scores/ScoreController.php
Purpose: manage academic scoring/grading workflow for score.
Public methods: overview(ScoreOverviewRequest $request), lock(ScoreLockRequest $request), studentScores(ScoreStudentRequest $request) Detected dependencies: Services: ScoreDashboardService | Requests: ScoreLockRequest, ScoreOverviewRequest, ScoreStudentRequest | Resources: ScoreStudentResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

ScorePredictorController

File: Api/Scores/ScorePredictorController.php
Purpose: manage academic scoring/grading workflow for score predictor.
Public methods: index(ScorePredictorRequest $request) Detected dependencies: Services: ScorePredictorService | Requests: ScorePredictorRequest | Resources: ScorePredictorStudentResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Validate file type, size, storage path, and access ownership.
• Generated documents need reproducible inputs and predictable naming.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping.

Settings

ConfigurationAdminController

File: Api/Settings/ConfigurationAdminController.php
Purpose: serve configuration admin API responsibilities.
Public methods: index(), store(ConfigurationStoreRequest $request), update(ConfigurationUpdateRequest $request, int $id), destroy(int $id), getByKey(string $configKey) Detected dependencies: Services: ConfigurationService | Requests: ConfigurationStoreRequest, ConfigurationUpdateRequest | Resources: ConfigurationResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

EventController

File: Api/Settings/EventController.php
Purpose: serve event API responsibilities.
Public methods: index(EventIndexRequest $request), show(int $eventId), store(EventStoreRequest $request), update(EventUpdateRequest $request, int $eventId), destroy(int $eventId), charges(EventChargeIndexRequest $request), updateCharges(EventChargeUpdateRequest $request, int $eventId), studentsWithCharges(EventStudentsWithChargesRequest $request) Detected dependencies: Services: EventCategoryService, EventChargeQueryService, EventChargeService, EventListService, EventManagementService, EventStudentChargeService | Requests: EventChargeIndexRequest, EventChargeUpdateRequest, EventIndexRequest, EventStoreRequest, EventStudentsWithChargesRequest, EventUpdateRequest | Resources: EventChargeResource, EventResource, EventStudentChargeResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Money operations must be idempotent, auditable, and transaction-safe.
• Never trust client-calculated totals; recompute server-side.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

PolicyController

File: Api/Settings/PolicyController.php
Purpose: serve policy API responsibilities.
Public methods: school(PolicyShowRequest $request), picture(PolicyShowRequest $request) Detected dependencies: Services: PolicyContentService | Requests: PolicyShowRequest | Resources: PolicyResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

PreferencesController

File: Api/Settings/PreferencesController.php
Purpose: serve preferences API responsibilities.
Public methods: index(PreferencesIndexRequest $request), show(), showForUser(int $userId), store(PreferencesUpsertRequest $request), updateForUser(PreferencesUpsertRequest $request, int $userId), destroy(int $userId) Detected dependencies: Services: PreferencesCommandService, PreferencesQueryService | Requests: PreferencesIndexRequest, PreferencesUpsertRequest | Resources: PreferencesCollection, PreferencesResource | Models: Preferences

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; delete success, already deleted, protected record.

SchoolCalendarController

File: Api/Settings/SchoolCalendarController.php
Purpose: serve school calendar API responsibilities.
Public methods: options(SchoolCalendarOptionsRequest $request), index(SchoolCalendarIndexRequest $request), teacherCalendarLegacy(SchoolCalendarIndexRequest $request), show(int $eventId), store(SchoolCalendarStoreRequest $request), update(SchoolCalendarUpdateRequest $request, int $eventId), destroy(int $eventId) Detected dependencies: Services: SchoolCalendarContextService, SchoolCalendarFormatterService, SchoolCalendarMeetingService, SchoolCalendarMutationService, SchoolCalendarQueryService | Requests: SchoolCalendarIndexRequest, SchoolCalendarOptionsRequest, SchoolCalendarStoreRequest, SchoolCalendarUpdateRequest | Resources: SchoolCalendarEventDetailResource, SchoolCalendarEventResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Mutating endpoints need request validation, service-layer ownership, and database transactions where multiple rows change.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

SettingsController

File: Api/Settings/SettingsController.php
Purpose: provide CRUD API endpoints for settings.
Public methods: index(), update(SettingsUpdateRequest $request) Detected dependencies: Services: SettingsService | Requests: SettingsUpdateRequest | Resources: SettingsResource | Models: Setting

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; update authorization, partial payload, concurrency/transaction rollback.

Staff

StaffController

File: Api/Staff/StaffController.php
Purpose: manage school identity and operations workflow for staff.
Public methods: index(StaffIndexRequest $request), show(int $id), store(StaffStoreRequest $request), update(StaffUpdateRequest $request, int $id), destroy(int $id) Detected dependencies: Services: StaffCommandService, StaffQueryService | Requests: StaffIndexRequest, StaffStoreRequest, StaffUpdateRequest | Resources: StaffCollection, StaffResource | Models: Staff

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

TeacherController

File: Api/Staff/TeacherController.php
Purpose: manage school identity and operations workflow for teacher.
Public methods: classes(TeacherClassViewRequest $request), switchClass(TeacherSwitchClassRequest $request), absenceForm(), submitAbsence(TeacherAbsenceSubmitRequest $request) Detected dependencies: Services: TeacherAbsenceService, TeacherDashboardService | Requests: TeacherAbsenceSubmitRequest, TeacherClassViewRequest, TeacherSwitchClassRequest | Resources: TeacherAbsenceResource, TeacherClassResource, TeacherStudentResource | Models: User

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

TimeOffNotificationController

File: Api/Staff/TimeOffNotificationController.php
Purpose: manage school identity and operations workflow for time off notification.
Public methods: notify(string $token) Detected dependencies: Services: EmailDispatchService, StaffTimeOffLinkService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

Students

StudentController

File: Api/Students/StudentController.php
Purpose: manage school identity and operations workflow for student.
Public methods: assignments(StudentAssignmentListRequest $request), index(Request $request), scoreCardSelectable(Request $request), show(int $studentId), store(Request $request), assignClass(StudentAssignClassRequest $request), removeClass(StudentRemoveClassRequest $request), removed(StudentAssignmentListRequest $request), setActive(StudentSetActiveRequest $request), autoDistribute(StudentAutoDistributeRequest $request), promotionTotals(StudentPromotionTotalsRequest $request), update(StudentUpdateRequest $request, int $studentId), destroy(int $studentId), classes(Request $request, int $studentId), assignClassForStudent(Request $request, int $studentId), removeClassForStudent(int $studentId, int $classSectionId), promote(Request $request, int $studentId), attendance(Request $request, int $studentId), incidents(Request $request, int $studentId), scores(Request $request, int $studentId), notes(int $studentId), parents(int $studentId), emergencyContacts(int $studentId), addEmergencyContact(Request $request, int $studentId), updateEmergencyContact(Request $request, int $studentId, int $contactId), updateBadgeScan(Request $request, int $studentId), uploadPhoto(Request $request, int $studentId), photo(int $studentId), scoreCard(int $studentId) Detected dependencies: Services: StudentAssignmentService, StudentAutoDistributionService, StudentDirectoryService, StudentProfileService, StudentScoreCardService, StudentStatusService | Requests: StudentAssignClassRequest, StudentAssignmentListRequest, StudentAutoDistributeRequest, StudentPromotionTotalsRequest, StudentRemoveClassRequest, StudentSetActiveRequest, StudentUpdateRequest | Resources: StudentAssignmentResource, StudentClassSectionResource, StudentRemovedResource, StudentScoreCardRowResource | Models: AttendanceRecord, ClassSection, EmergencyContact, Incident, SemesterScore, Student, StudentClass, User

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Attendance changes need actor, timestamp, school term, and edit history.
• Define conflict behavior for duplicate scans or same-day edits.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

Subjects

SubjectCurriculumController

File: Api/Subjects/SubjectCurriculumController.php
Purpose: provide CRUD API endpoints for subject curriculum.
Public methods: index(), show(int $id), store(SubjectCurriculumStoreRequest $request), update(SubjectCurriculumUpdateRequest $request, int $id), destroy(int $id) Detected dependencies: Services: SubjectCurriculumService | Requests: SubjectCurriculumStoreRequest, SubjectCurriculumUpdateRequest | Resources: SubjectClassResource, SubjectCurriculumResource | Models: SubjectCurriculum

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

Support

ContactController

File: Api/Support/ContactController.php
Purpose: serve contact API responsibilities.
Public methods: send(ContactSendRequest $request) Detected dependencies: Services: ContactMessageService | Requests: ContactSendRequest | Resources: ContactMessageResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

SupportController

File: Api/Support/SupportController.php
Purpose: serve support API responsibilities.
Public methods: index(SupportRequestIndexRequest $request), store(SupportRequestStoreRequest $request), teacher() Detected dependencies: Services: SupportRequestService | Requests: SupportRequestIndexRequest, SupportRequestStoreRequest | Resources: SupportRequestCollection, SupportRequestResource | Models: SupportRequest

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; create/submit validation, happy path, duplicate submission.

System

AccessDeniedController

File: Api/System/AccessDeniedController.php
Purpose: serve access denied API responsibilities.
Public methods: accessDenied()

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Extract business logic into service/action classes if the controller currently queries models or mutates state directly.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

DashboardController

File: Api/System/DashboardController.php
Purpose: serve dashboard API responsibilities.
Public methods: route() Detected dependencies: Services: DashboardRouteService | Resources: DashboardRouteResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

DashboardRedirectController

File: Api/System/DashboardRedirectController.php
Purpose: serve dashboard redirect API responsibilities.
Public methods: dashboard() Detected dependencies: Services: ApplicationUrlService, DashboardRouteService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

DatabaseHealthController

File: Api/System/DatabaseHealthController.php
Purpose: provide CRUD API endpoints for database health.
Public methods: index() Detected dependencies: Services: DatabaseHealthService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping.

HealthController

File: Api/System/HealthController.php
Purpose: provide CRUD API endpoints for health.
Public methods: index() Detected dependencies: Services: HealthCheckService

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping.

NavBuilderController

File: Api/System/NavBuilderController.php
Purpose: serve nav builder API responsibilities.
Public methods: menu(), data(), store(NavItemStoreRequest $request), destroy(int $id), reorder(NavItemReorderRequest $request) Detected dependencies: Services: NavBuilderService, NavbarService | Requests: NavItemReorderRequest, NavItemStoreRequest | Resources: NavBuilderDataResource, NavItemResource | Models: NavItem

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: create/submit validation, happy path, duplicate submission; delete success, already deleted, protected record.

SchoolIdController

File: Api/System/SchoolIdController.php
Purpose: serve school id API responsibilities.
Public methods: assign(SchoolIdAssignRequest $request), generateStudent(), generateUser() Detected dependencies: Services: SchoolIdAssignmentService, SchoolIdGenerationService | Requests: SchoolIdAssignRequest | Resources: SchoolIdResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

SemesterRangeController

File: Api/System/SemesterRangeController.php
Purpose: serve semester range API responsibilities.
Public methods: schoolYearRange(SchoolYearRangeRequest $request), semesterRange(SemesterRangeRequest $request), normalize(SemesterNormalizeRequest $request), resolve(SemesterResolveRequest $request) Detected dependencies: Services: SemesterRangeService | Requests: SchoolYearRangeRequest, SemesterNormalizeRequest, SemesterRangeRequest, SemesterResolveRequest | Resources: SemesterRangeResource, SemesterResolveResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

StatsController

File: Api/System/StatsController.php
Purpose: provide CRUD API endpoints for stats.
Public methods: index() Detected dependencies: Models: Stats

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Extract business logic into service/action classes if the controller currently queries models or mutates state directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Rate-limit sends and record delivery state; retries must not spam families into oblivion.
• Sanitize templates and recipient selection.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping.

Ui

UiController

File: Api/Ui/UiController.php
Purpose: serve ui API responsibilities.
Public methods: style(UiStyleRequest $request) Detected dependencies: Services: UiStyleService | Requests: UiStyleRequest | Resources: UiStyleResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

Users

UserController

File: Api/Users/UserController.php
Purpose: serve user API responsibilities.
Public methods: index(UserListRequest $request), store(UserStoreRequest $request), show(int $userId), update(UserUpdateRequest $request, int $userId), destroy(int $userId), loginActivity(LoginActivityRequest $request) Detected dependencies: Services: LoginActivityService, UserListService, UserManagementService | Requests: LoginActivityRequest, UserListRequest, UserStoreRequest, UserUpdateRequest | Resources: LoginActivityResource, UserWithRolesResource | Models: User

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Authorization boundaries are the product, not decoration. Test forbidden paths first.
• Avoid leaking whether accounts, roles, or sessions exist unless intended.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: list/filter pagination, empty result, invalid filter, tenant scoping; show success, missing record, unauthorized record; create/submit validation, happy path, duplicate submission; update authorization, partial payload, concurrency/transaction rollback; delete success, already deleted, protected record.

Utilities

PhoneFormatterController

File: Api/Utilities/PhoneFormatterController.php
Purpose: serve phone formatter API responsibilities.
Public methods: format(PhoneFormatRequest $request) Detected dependencies: Services: PhoneFormatterService | Requests: PhoneFormatRequest | Resources: PhoneFormatResource

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Keep validation in existing FormRequest classes; check required fields, enum values, date ranges, IDs, file constraints, and cross-field rules.
• Keep controller as orchestration only; move rules/calculation/query composition into the detected service layer and unit-test those services directly.
• Scope every query by school/tenant and role. Humans love accidental data leaks.
• Protect PII in logs, exports, and error payloads.
• Feature tests: happy path, unauthorized path, invalid input, service exception.

ProofreadController

File: Api/Utilities/ProofreadController.php
Purpose: serve proofread API responsibilities.
Public methods: check(Request $request)

Plan

• Define endpoint contract for each public method: request fields, response resource, status codes, and failure shape.
• Add dedicated FormRequest classes where this still uses raw Request; inline validation is a trap wearing a tiny fake mustache.
• Extract business logic into service/action classes if the controller currently queries models or mutates state directly.
• Feature tests: happy path, unauthorized path, invalid input, service exception.