# API Controllers

This document lists every API controller alphabetically with any inline route comments we can gather.

## AdministratorController
**File:** `app/Http/Controllers/Api/AdministratorController.php`  
**Purpose:** Surface administrator-portal analytics, student and parent search tools, and the enrollment workflow.

**Endpoints**
- `GET /api/v1/administrator/dashboard` (`dashboard`)
  - Returns counts for students, staff roles, and parents plus the four most recent login activities. Always reflects the configured school year/semester.
- `GET /api/v1/administrator/absence` (`absenceInfo`)
  - Requires auth. Responds with semester/year metadata, existing absence submissions for the current admin, and the list of valid Sunday dates (computed via `allowedAbsenceDates()`).
- `POST /api/v1/administrator/absence` (`submitAbsence`)
  - Body: `{"dates":["YYYY-MM-DD",...], "reason_type":"optional", "reason":"required"}`.
  - Validates each date against the allowed list, creates/upserts staff attendance rows, and emails the principal. Response lists `saved`, `invalid`, and the saved date values; validation errors return `401/422`.
- `GET /api/v1/administrator/search` (`search`)
  - Query param `q` is required. Tokenizes the search string and looks across users, students, parents, staff, and emergency contacts (including phone-number heuristics). Returns bucketed arrays and a total hit count.
- `GET /api/v1/administrator/enrollment-withdrawal` (`enrollmentWithdrawal`)
  - Paginated list of enrollment rows filtered by `school_year` (defaults to configured year).
- `GET /api/v1/administrator/enrollment-withdrawal/data` (`enrollmentWithdrawalData`)
  - Supplies UI metadata: available school years, each student with parent context, and class-section options for the chosen year.
- `POST /api/v1/administrator/enrollment-withdrawal/update` (`updateEnrollmentStatuses`)
  - Body: `{"enrollment_status":{"student_id":"status", ...}}` where status must be one of `admission under review`, `payment pending`, `enrolled`, `withdraw under review`, `refund pending`, `withdrawn`, `denied`, or `waitlist`.
  - Wraps updates in a transaction, adjusts admission flags, and when a status moves into `refund pending` runs `FeeCalculationService` + `RefundModel` bookkeeping. Responds with summary + any per-student errors.
- `GET /api/v1/administrator/students` (`studentProfiles`)
  - Returns every student ordered alphabetically, enriched with parent contact info, emergency contacts, allergy/medical summaries, and current class section name.
- `GET /api/v1/administrator/parents` (`parentProfiles`)
  - Iterates all users, filters by `parent` role, and augments each record with their latest invoice `paid_amount`/`balance`.
- `GET /api/v1/administrator/enrollment/new-students` (`newStudents`)
  - Lists all students marked as new for the active school year, including parent/emergency contacts, enrollment status, class assignment, and formatted registration dates.

## AssignmentController
**File:** `app/Http/Controllers/Api/AssignmentController.php`  
**Purpose:** CRUD interface around the `assignments` table plus APIs for the class-assignment management screen.

- `GET /api/v1/assignments` (`index`) – Optional `class_id`, `teacher_id`, `student_id`, `page`, and `per_page` filters; returns paginated assignments.
- `GET /api/v1/assignments/{id}` (`show`) – Returns a single assignment or `404`.
- `POST /api/v1/assignments` (`store`) – Requires `title`, `due_date (Y-m-d)`, `class_id`, and `teacher_id`; creates an assignment row.
- `PATCH /api/v1/assignments/{id}` (`update`) – Partial update for the same fields as `store`.
- `DELETE /api/v1/assignments/{id}` (`delete`) – Removes the assignment.
- `GET /api/v1/assignments/student/{id}` (`student`) – Lists assignments attached to a specific student.
- `GET /api/v1/assignments/class-sections` (`classAssignments`) – Mirrors the legacy admin Class Assignment screen; groups teacher + student rosters by class section, with optional `school_year` filter, and returns the list of available school years.
- `GET /api/v1/assignments/class-sections/data` (`classAssignmentData`) – Lightweight JSON payload of all class sections/teachers/students used by the SPA.
- `POST /api/v1/assignments/class-sections` (`saveClassAssignment`) – Creates a `student_class` record for a student/section pairing, capturing term metadata and editor.

## AttendanceController
**File:** `app/Http/Controllers/Api/AttendanceController.php`  
**Purpose:** Manage per-student attendance plus provide roster tools for class-wide check-in.

- `index()` – Query params: `page`, `per_page`, `student_id`, `date`. Responds with paginated attendance rows and pager metadata.
- `show($id)` – Returns a single attendance record or `404`.
- `store()` – Body requires `student_id`, `date (Y-m-d)`, `status (present|absent|late)`, optional `notes`. Prevents duplicates per (student,date) and returns `201` with inserted payload.
- `update($id)` – Allows patching `status` and/or `notes`, re-validates, and echoes the updated entity.
- `delete($id)` – Removes the record if it exists.
- `student($id)` – Returns all attendance rows for the given student sorted newest-first.
- `classRoster($class_section_id)` – `GET /api/v1/attendance/class/{class_section_id}` accepts optional `date` query param (default today) and returns each student in the section with their attendance status/reason for that date.
- `recordClass($class_section_id)` – `POST /api/v1/attendance/class/{class_section_id}/record` body: `{"date":"YYYY-MM-DD","records":[{"student_id":1,"status":"present|absent|late","reason":"optional"},...]}`. Validates rows, ensures roster membership, and records each entry atomically, returning per-student success/error arrays.
- `GET /api/v1/attendance/teacher/grid` (`teacherSectionGrid`) – Returns the section dropdown, current staff grid, and lock state for the teacher attendance landing page; accepts `class_section_id`, `date`, `semester`, and `school_year`.
- `GET /api/v1/attendance/teacher/update-data` (`teacherUpdateData`) – Supplies the detailed payload used by the teacher update form: teacher metadata, the most recent dates (today plus the last three sessions), student attendance history, staff statuses, and any no-school days for the selected section/term.

## AttendanceTrackingController
**File:** `app/Http/Controllers/Api/AttendanceTrackingController.php`  
**Purpose:** Surface pending attendance violations, automate/track parent notifications, and expose helpers for the manual email workflow.

- `GET /api/v1/attendance-tracking/pending` (`pendingViolations`) – Filters unreported/unnotified absences & lates in the last five active weeks and returns the computed violation list, including parent contact info and recommended actions.
- `GET /api/v1/attendance-tracking/notified` (`notifiedViolations`) – Lists previously notified violations enriched with student, class, and parent metadata.
- `POST /api/v1/attendance-tracking/notify` (`recordNotification`) – Manually mark a violation as notified (and dispatch the corresponding Laravel event). Body must include `student_id` and `date`; optional term overrides and parent contact info may be supplied.
- `POST /api/v1/attendance-tracking/send-auto-emails` (`sendAutoEmails`) – Scans for auto-email violations and sends templated emails (with CC to secondary parents when available); responds with `{sent, skipped, errors, details}`.
- `GET /api/v1/attendance-tracking/compose` (`composeEmail`) – Returns the rendered subject/body preview plus parent addresses for a given `student_id`, `code`, and optional `variant`/`incident_date`.
- `POST /api/v1/attendance-tracking/send-email` (`sendEmailManual`) – Sends a manual attendance email using the body/subject from the compose UI, logs the notification, and flips the tracking/attendance rows to notified.
- `GET /api/v1/attendance-tracking/parents-info` (`parentsInfo`) – Convenience endpoint that returns the primary and secondary parent contacts for a student.
- `POST /api/v1/attendance-tracking/notes` (`saveNotificationNote`) – Persists the admin’s follow-up note against the relevant tracking row (or creates one if missing) after a notification is sent.

## AuthController
**File:** `app/Http/Controllers/Api/Auth/AuthController.php`  
**Purpose:** JWT-backed authentication endpoints.

- `POST /api/v1/auth/login` (`login`) – Validates `email` and `password`, looks up the user case-insensitively, uses `ci_password_verify`, and returns `{access_token, token_type, expires_in}` or `401`.
- `GET /api/v1/auth/me` (`me`) – Requires a valid bearer token, returns the decoded `User` JSON via `JWTAuth::parseToken()->authenticate()`.
- `POST /api/v1/auth/logout` (`logout`) – Invalidates the caller’s JWT token (best-effort) and returns `{message: "Logged out"}` even if the token was already invalid.

## AuthorizedUsersController
**File:** `app/Http/Controllers/Api/AuthorizedUsersController.php`  
**Purpose:** Allow primary users to manage their authorized delegates and guide those delegates through the confirmation/password flow.

- `GET /api/v1/authorized-users` (`index`) – Auth required; returns every authorized user tied to the signed-in primary account.
- `GET /api/v1/authorized-users/{id}` (`show`) – Auth required; fetches a single authorized user (scoped to the current owner).
- `POST /api/v1/authorized-users` (`store`) – Auth required; accepts `email`, verifies that user exists, creates a pending authorized-user row, and sends a confirmation email with a tokenized link.
- `PATCH /api/v1/authorized-users/{id}` (`update`) – Auth required; currently allows updating the email address for the authorized user.
- `DELETE /api/v1/authorized-users/{id}` (`destroy`) – Auth required; removes the authorized user entry for the current owner.
- `POST /api/v1/authorized-users/confirm` (`confirm`) – Public endpoint hit from email links; validates the token, activates the record, and returns the delegate’s `authorized_user_id` for the password setup UI.
- `GET /api/v1/authorized-users/{id}/set-password` (`setPassword`) – Public; returns the delegate’s basic info so the frontend can render the password form.
- `POST /api/v1/authorized-users/{id}/password` (`savePassword`) – Public; accepts `password`/`password_confirm`, hashes it with PBKDF2, and updates the delegate’s user record.

## BaseApiController
**File:** `app/Http/Controllers/Api/BaseApiController.php`  
**Purpose:** Shared foundation for every API controller. Wraps the Laravel request in a `CiRequestAdapter`, standardizes JSON responses, bridges CodeIgniter-style validation rules, and exposes helper utilities.

- **Response helpers:** `success`, `error`, and the `respond*` variants keep payloads consistent (`{status, message, data}`) and map to the right HTTP codes (`200`, `201`, `204`, `400`, `422`, etc.).
- **Validation bridge:** `validateRequest`, `validate`, `payloadData`, and `normalizeRules` accept CodeIgniter rule strings (e.g., `max_length[255]`, `permit_empty`) and translate them to Laravel validator syntax before running `Validator::make`.
- **Pagination:** `paginate($source, $page, $perPage)` works with Eloquent builders, query builders, or arrays, returning `{data, pagination:{current_page, per_page, total, total_pages}}`.
- **Session context:** `getCurrentUserId()` reads the `user_id` from the session, and `getCurrentUser()` fetches the hydrated `UserModel` record, falling back to querying `user_roles` if roles are missing from the session cache.
- **Constructor:** captures the Laravel `Request` and exposes it as `$this->request` via `CiRequestAdapter` so consuming controllers can continue to use familiar CI-style helpers (`getGet`, `getJSON`, etc.).

## BroadcastEmailController
**File:** `app/Http/Controllers/Api/BroadcastEmailController.php`  
**Purpose:** Simple bulk-email helper for administrators plus a convenience list of eligible parent recipients.

- `GET /api/v1/broadcast-email` (`metadata`) – Provides the parent roster (using `UserModel::getParents`) and the sender dropdown derived from `MAIL_SENDERS` so the UI can render the compose screen.
- `POST /api/v1/broadcast-email/send` (`send`) – Supports both test mode (`send_test_only`, `test_email`) and broadcast mode. Accepts layout options (`wrap_layout`, `preheader`, CTA text/URL) plus personalization toggle. Sends via `EmailService`, reports `{attempted, sent, failed}`.
- `POST /api/v1/broadcast-email/upload-image` (`uploadImage`) – Validates and stores rich-text editor image uploads (JPEG/PNG/GIF/WebP ≤ 5 MB) under `public/uploads/email` and returns the public URL.

## CalendarController
**File:** `app/Http/Controllers/Api/CalendarController.php`  
**Purpose:** CRUD for the school calendar, including month/year filters and validation for event creation.

- `GET /api/v1/calendar` (`index`) – Supports `page`, `per_page`, `month`, and `year` query params. Filters by `start_date`, orders ascending, and returns paginated events.
- `GET /api/v1/calendar/{id}` (`show`) – Returns the event by ID or `404`.
- `POST /api/v1/calendar` (`store`) – Body must include `title`, `start_date (Y-m-d)` and optional `description`, `end_date`, `location`. Responds with `201` and the created record.
- `PATCH /api/v1/calendar/{id}` (`update`) – Allows partial updates to the same fields; returns the refreshed record.
- `DELETE /api/v1/calendar/{id}` (`delete`) – Removes the event and returns the standard success envelope.

## CiRequestAdapter
**File:** `app/Http/Controllers/Api/CiRequestAdapter.php`  
**Purpose:** Lightweight shim that lets the Laravel request behave like CodeIgniter’s `$this->request`.

- `getGet()` / `getPost()` – Mirror CI helpers by returning either all query/form params or a single key with a default.
- `getJSON($assoc = false)` – Parses the raw body once and returns decoded JSON (array/object).
- `getVar()` – Unified accessor that checks body/query for a key.
- `getHeader()` / `getHeaderLine()` – Pull HTTP headers using familiar CI naming.
- `getFile()` – Returns the uploaded file object (if any) for the key.
- `getRawInput()` – Gives the unparsed request body string.
- `all()` – Aggregates query, form, and JSON payloads into a single array—handy when migrating legacy controllers.

## ClassController
**File:** `app/Http/Controllers/Api/ClassController.php`  
**Purpose:** Provide read endpoints for classes and their rosters.

- `GET /api/v1/classes` (`index`) – Supports pagination plus optional `grade` and `teacher_id` filters; returns ordered list of class records.
- `GET /api/v1/classes/{id}` (`show`) – Retrieves a single class or `404`.
- `GET /api/v1/classes/{id}/students` (`students`) – Joins `student_class` and `students` to return each enrolled student (`id`, `firstname`, `lastname`, `school_id`) sorted alphabetically.

## ClassPreparationController
**File:** `app/Http/Controllers/Api/ClassPreparationController.php`  
**Purpose:** Track supplies needed for each class and provide a lightweight "requirements" calculator.

- `GET /api/v1/class-prep/list` (`index`) – Returns class preparation data filtered by optional `school_year` and `semester` query params. Calculates per-section prep items, available inventory, shortages, and change flags. Returns:
  - `results` – Array of class sections with prep items, student counts, adjustments, and print status
  - `totals` – Required totals for each prep category
  - `shortages` – Items where available inventory is less than required
  - `available` – Current inventory map
- `POST /api/v1/class-prep/adjustments` (`saveAdjustment`) – Body requires `class_section_id`, `school_year`, and `adjustments` object. Persists manual adjustments for large/small tables and returns `{updated: count}`.
- `POST /api/v1/class-prep/mark-printed` (`markPrinted`) – Body requires `school_year` and `class_section_ids` array. Stores printed snapshots for the supplied section IDs to reset `needs_print` flag. Returns `{updated: count}`.

## CommunicationController
**File:** `app/Http/Controllers/Api/CommunicationController.php`  
**Purpose:** Internal messaging between users (parents ↔ staff, etc.).

- `GET /api/v1/communications` (`index`) – Paginated feed filtered by optional `sender_id` and/or `receiver_id`, ordered newest-first.
- `POST /api/v1/communications` (`send`) – Body must include `sender_id`, `receiver_id`, `subject`, `message`. Returns `201` with stored record.
- `GET /api/v1/communications/conversation` (`conversation`) – Requires both `sender_id` and `receiver_id` query params. Returns the chronological conversation (both directions) between the two users.
- `DELETE /api/v1/communications/{id}` (`delete`) – Removes a message by ID.
- `GET /api/v1/communications/metadata` (`metadata`) – Returns the active students list (id, firstname, lastname, grade) plus all active email templates for building a mailing UI.
- `GET /api/v1/communications/students/{student_id}/families` (`families`) – Returns the active families for the supplied student along with the `is_primary_home` flag so the front-end can preselect the right household.
- `GET /api/v1/communications/families/{family_id}/guardians` (`guardians`) – Joins `family_guardians` with `users` to return each guardian’s name, email, relation, and preferred delivery flags.
- `POST /api/v1/communications/preview` (`preview`) – Body requires `template_key`, `student_id`, and `family_id`; optional `vars`. Renders the Twig-like placeholders in the chosen template and returns a sanitized subject/body preview.
- `POST /api/v1/communications/send-email` (`sendEmail`) – Body requires `student_id`, `family_id`, `template_key`, `subject`, `body`, and `recipients` (JSON array or string). Accepts optional `cc`/`bcc`, sends the HTML email through `Mail::send`, and logs the result in `communication_logs`.

## ConfigurationController
**File:** `app/Http/Controllers/Api/ConfigurationController.php`  
**Purpose:** Manage key/value pairs stored in the `configuration` table.

- `GET /api/v1/configuration` (`index`) – Paginated list ordered by ID with optional fuzzy `key` search.
- `GET /api/v1/configuration/{id}` (`show`) – Fetch a config row by numeric ID.
- `GET /api/v1/configuration/key/{config_key}` (`getByKey`) – Convenience lookup using the string key.
- `POST /api/v1/configuration` (`create`) – Requires unique `config_key` and `config_value`; wraps persistence in try/catch and returns `201`.
- `PATCH /api/v1/configuration/{id}` (`update`) – Allows updating `config_key` and/or `config_value`, ensuring the payload isn’t empty.
- `DELETE /api/v1/configuration/{id}` (`delete`) – Removes the row after existence check.
- `GET /api/v1/configuration/list` (`listData`) – Returns all configs as `{id, config_key, config_value}` for settings UIs.

## ContactController
**File:** `app/Http/Controllers/Api/ContactController.php`  
**Purpose:** Public “Contact Us” submission endpoint that relays a message via the shared `EmailService`.

- `POST /api/v1/contact` (`submit`) – Body requires `name`, `email`, `subject`, and `message`. Validates lengths + email format, then composes HTML and sends it to `SUPPORT_EMAIL` (default `support@alrahmaisgl.org`). Returns a friendly success message or `500` if delivery fails.

## DiscountController
**File:** `app/Http/Controllers/Api/DiscountController.php`  
**Purpose:** Validate and apply voucher codes against invoices, enforcing date windows and usage limits.

- `GET /api/v1/discounts` (`index`) – Returns all vouchers ordered newest-first. Optional `?active=true` filters down to vouchers that are enabled, within the valid-from/until window.
- `GET /api/v1/discounts/{code}` (`getByCode`) – Looks up the code (case-sensitive in the DB). Responds `404` if inactive/expired and `400` if the max usage has already been hit.
- `POST /api/v1/discounts/apply` (`apply`) – Requires authentication plus a JSON body with `code` and `invoice_id`. Validates the voucher, ensures it hasn’t been applied to that invoice, records the usage (`discount_usage`), increments `times_used`, and returns the refreshed voucher payload. Errors return `400/401/500` with descriptive messages.

## EmailController
**File:** `app/Http/Controllers/Api/EmailController.php`  
**Purpose:** Send HTML emails using PHPMailer with support for multiple email profiles, DKIM signing, and attachments.

- `POST /api/v1/email/send` (`send`) – Body requires `recipient`, `subject`, and `html_message`. Optional parameters include:
  - `profile` – Email profile name (e.g., 'communication', 'payment', 'default'). Uses `MAIL_PROFILE_DEFAULT` or 'default' if not specified.
  - `reply_to_email` – Override reply-to email address
  - `reply_to_name` – Override reply-to name
  - `attachments` – Array of attachment objects: `[{'path': '...', 'name': '...'}, ...]`
  
  Supports multiple SMTP profiles via environment variables (`MAIL_{PROFILE}_*` or `MAIL_DEFAULT_*`). Features include:
  - DKIM signing (if configured)
  - Socket preflight checks
  - Debug mode (via `MAIL_DEBUG` env)
  - TLS/SSL encryption with auto-correction
  - Returns `{recipient, subject, sent: true}` or error response on failure.

## EmailExtractorController
**File:** `app/Http/Controllers/Api/EmailExtractorController.php`  
**Purpose:** Admin utility to export user/parent emails and compare them against a CSV list or uploaded file.

- `GET /api/v1/email-extractor/emails` (`getEmails`) – Returns all normalized emails from `users.email` and `parents.secondparent_email` as `{users: string[], parents: string[]}`. Emails are validated, lowercased, and de-duplicated.
- `POST /api/v1/email-extractor/compare` (`compare`) – Accepts either:
  - Multipart/form-data with a CSV file named `file` (emails extracted via regex)
  - JSON body with `csvEmails` array
  
  Compares CSV emails against database emails and returns:
  - `existed` – Emails present in both CSV and database
  - `needToAdd` – Emails in database but not in CSV
  - `counts` – Object with `csv`, `db`, `users`, and `parents` counts

## EmergencyContactController
**File:** `app/Http/Controllers/Api/EmergencyContactController.php`  
**Purpose:** Maintain emergency contacts scoped to the configured school year/semester.

- `GET /api/v1/emergency-contacts` (`index`) – Optional `parent_id` filter; automatically filters by current year/semester. Returns paginated list of emergency contacts.
- `GET /api/v1/emergency-contacts/data` (`data`) – Returns emergency contacts grouped by parent with enriched data:
  - `groups` – Array of parent groups, each containing:
    - `parent_id` – Parent user ID
    - `parent_name` – Full name of the parent
    - `students` – Array of students associated with this parent (id, firstname, lastname, school_id)
    - `contacts` – Array of emergency contacts for this parent
    - `parent_phones` – Array of phone numbers (primary and secondary parent phones, filtered to non-empty values)
- `GET /api/v1/emergency-contacts/{id}` (`show`) – Fetch a single emergency contact or `404`.
- `GET /api/v1/emergency-contacts/parent/{parent_id}` (`getByParent`) – Returns all emergency contacts for a specific parent, filtered by current year/semester.
- `POST /api/v1/emergency-contacts` (`create`) – Requires `parent_id`, `emergency_contact_name`, `cellphone`, `relation`; optional `email`. Attaches the current year/semester before inserting.
- `PATCH /api/v1/emergency-contacts/{id}` (`update`) – Allows updating `emergency_contact_name`, `cellphone`, `email`, and `relation`.
- `DELETE /api/v1/emergency-contacts/{id}` (`delete`) – Removes the contact.

## EventController
**File:** `app/Http/Controllers/Api/EventController.php`  
**Purpose:** CRUD operations for events and event charges management.

- `GET /api/v1/events` (`index`) – Returns all events filtered by optional `school_year` query param. When `?upcoming=true`, filters by `expiration_date >= today`. Returns `{events: array, active_event_count: number}`.
- `GET /api/v1/events/{id}` (`show`) – Fetch an event by ID or `404`.
- `POST /api/v1/events` (`create`) – Creates a new event. Body requires `event_name`, `amount`, `expiration_date`. Optional: `description`, `semester`, `school_year`, `flyer` (file upload). Automatically sets `created_by` from session.
- `PATCH /api/v1/events/{id}` (`update`) – Updates an event. Allows updating `event_name`, `description`, `amount`, `expiration_date`, `semester`, `school_year`, and `flyer` (file upload). Old flyer is deleted when a new one is uploaded.
- `DELETE /api/v1/events/{id}` (`delete`) – Deletes an event and all associated event charges. Collects affected parent IDs for invoice regeneration (note: `generateInvoice` method may need implementation).
- `GET /api/v1/events/charges` (`charges`) – Returns event charges with parent and student information. Optional query params: `school_year`, `semester`. Returns `{charges: array, parents: array, events: array, school_year: string, semester: string}`.
- `POST /api/v1/events/charges/update` (`updateCharges`) – Updates event charges for a parent and students. Body requires `parent_id`, `event_id`, `participation` (object mapping student_id to 'yes'/'no'). Optional: `school_year`, `semester`. Creates or updates charges, deletes when participation is 'no'. Regenerates invoice for parent (note: `generateInvoice` may need implementation).
- `GET /api/v1/events/students-with-charges` (`getStudentsWithCharges`) – Returns students for a parent with their charge status. Query params: `parent_id` (required), `semester`, `school_year`. Returns array of `{id, name, charged: boolean}`.

## ExpenseController
**File:** `app/Http/Controllers/Api/ExpenseController.php`  
**Purpose:** CRUD for expense reimbursement records with school year/semester scoping.

- `GET /api/v1/expenses` (`index`) – Paginated list filtered by `status` and/or `category`, always constrained to the active year/semester.
- `GET /api/v1/expenses/{id}` (`show`) – Retrieve a single expense.
- `POST /api/v1/expenses` (`create`) – Body needs `category`, `amount`, `description`, `date_of_purchase`; fills metadata like `school_year`, `semester`, `purchased_by`, and `status`.
- `PATCH /api/v1/expenses/{id}` (`update`) – Allows selective updates (category/amount/description/retailor/date/status/status_reason) and stamps `updated_by`.
- `DELETE /api/v1/expenses/{id}` (`delete`) – Deletes the record.

## ExtraChargesController
**File:** `app/Http/Controllers/Api/ExtraChargesController.php`  
**Purpose:** Manage "additional charges" tacked onto parent invoices with full transaction support and invoice adjustment.

- `GET /api/v1/extra-charges` (`index`) – Paginated list filtered by `school_year`, `semester`, `status`, and optional search query `q`. Returns charges with parent names and invoice numbers. Defaults to configured year/semester.
- `GET /api/v1/extra-charges/{id}` (`show`) – Retrieve a single charge or `404`.
- `POST /api/v1/extra-charges` (`store`) – Creates a new charge. Body requires:
  - `parent_id` (integer, required) – The user ID of the parent
  - `title` (string, required, min 2 chars)
  - `amount` (numeric, required)
  - `charge_type` (required, `add` or `deduct`)
  - `due_date` (nullable, date format)
  - `invoice_id` (nullable, integer) – If provided, charge is immediately applied to invoice
  - `description` (optional string)
  - `school_year` (optional, defaults to configured year)
  - `semester` (optional, defaults to configured semester)
  
  When `invoice_id` is provided, the charge is automatically applied to the invoice (adjusting `total_amount` and `balance`). Dispatches `extraCharge` event with full context including pre/post balance snapshots.
- `PATCH /api/v1/extra-charges/{id}` (`update`) – Updates charge fields (`title`, `description`, `amount`, `due_date`, `charge_type`). If the charge is already applied to an invoice and the amount changes, the invoice is automatically adjusted to reflect the delta.
- `POST /api/v1/extra-charges/{id}/void` (`void`) – Marks a charge as void. If the charge was applied to an invoice, the invoice impact is rolled back (reversed for additions, re-added for deductions). Uses database transactions.
- `POST /api/v1/extra-charges/{id}/reverse` (`reverse`) – Reverses an applied charge back to pending status. Undoes the invoice impact and clears the `invoice_id`. Only works on charges with status `applied`.
- `DELETE /api/v1/extra-charges/{id}` (`delete`) – Permanently deletes the charge record.
- `GET /api/v1/extra-charges/parent-options` (`parentOptions`) – Returns Select2-compatible `{results: [{id, text}]}` array for parent users. Optional query param `q` filters by firstname, lastname, or email. Format: "Lastname, Firstname — email (ID: x)".
- `GET /api/v1/extra-charges/invoices-for-parent` (`invoicesForParent`) – Returns Select2-compatible invoice list for a parent. Query params: `parent_id` (required), `school_year` (optional). Format: "INV-123 — status (Bal: $X.XX)".

## FamilyAdminController
**File:** `app/Http/Controllers/Api/FamilyAdminController.php`  
**Purpose:** Admin-only aggregate view of students, families, guardians, and financial data.

- `GET /api/v1/family-admin` (`index`) – Returns comprehensive family administration data. Query params:
  - `student_id` (optional) – Filters to that student's family memberships
  - `guardian_id` (optional) – If provided without `student_id`, resolves to one of the guardian's students
  
  Returns:
  - `students` – Simple list of all students (id, name) for dropdowns
  - `search_students` – Student search dataset (id, firstname, lastname)
  - `search_guardians` – Guardian search dataset (id, firstname, lastname, email, cellphone)
  - `student` – Selected student info (if `student_id` provided)
  - `families` – Array of families for the student, each containing:
    - Family details (family_code, household_name, address, etc.)
    - `guardians` – Array of guardians with contact info and preferences
    - `students` – Array of students in the family with grade information
    - `invoices` – All invoices for guardians in this family
    - `payments` – Recent payments (limit 10) for guardians
    - `finance_summary` – Aggregated totals (invoices_count, total_amount, paid_amount, balance)
    - `invoice_map` – Mapping of invoice IDs to invoice numbers
  - `guardians` – Guardians of the first family (back-compat)

- `GET /api/v1/family-admin/search` (`search`) – Search for students and guardians. Query param `q` (required) searches by:
  - Students: firstname, lastname
  - Guardians: firstname, lastname, email, cellphone
  
  Returns `{items: []}` array where each item has:
  - `type` – "student" or "guardian"
  - `id` – ID of the student/guardian
  - `label` – Full name
  - `sub` – Additional info (email/phone for guardians, "Student" for students)
  
  Limited to 8 results per type.

- `GET /api/v1/family-admin/card` (`card`) – Returns detailed family card data. Query params:
  - `family_id` (optional) – Direct family ID
  - `student_id` (optional) – Resolves to primary family for that student
  - `guardian_id` (optional) – Resolves to a family via guardian link or student parent_id
  
  Returns a single `family` object with:
  - Family details (all fields from families table)
  - `guardians` – All guardians with full contact info
  - `students` – All students with grade information
  - `invoices` – All invoices for guardians
  - `payments` – Recent payments (limit 10)
  - `finance_summary` – Aggregated financial totals
  - `invoice_map` – Invoice ID to number mapping
  - `emergency_contacts` – Emergency contacts for all guardians, enriched with parent labels

## FamilyController
**File:** `app/Http/Controllers/Api/FamilyController.php`  
**Purpose:** CRUD and management endpoints for families, linking families to guardians (users) and students, including bootstrap from existing schema.

**Read Endpoints:**
- `GET /api/v1/families` (`index`) – Paginated families with eager-loaded `students` and `guardians`.
- `GET /api/v1/families/{id}` (`show`) – Fetch a family with its relations.
- `GET /api/v1/families/by-student/{student_id}` (`getByStudent`) – Returns every family associated with the student, including nested members.
- `GET /api/v1/families/{id}/guardians` (`getGuardians`) – Convenience list of guardians for a family.
- `GET /api/v1/families/students/{student_id}/families` (`familiesByStudent`) – Returns all active families for a student with `is_primary_home` flag, ordered by primary home first.
- `GET /api/v1/families/{family_id}/guardians-list` (`guardiansByFamily`) – Returns guardians for a family with user details (firstname, lastname, email) and guardian flags (relation, is_primary, receive_emails, receive_sms).

**Bootstrap & Linking:**
- `POST /api/v1/families/bootstrap` (`bootstrap`) – Creates/ensures families for every student with `parent_id`, links students to families, and links primary parents as guardians. Returns counts of families created, students linked, and guardians linked. Uses database transactions.
- `POST /api/v1/families/attach-second-by-user` (`attachSecondByUser`) – Attaches a second parent/guardian to a student's primary family. Body requires `student_id`, `user_id`, and optional `relation` (defaults to 'secondary').
- `POST /api/v1/families/attach-second-by-email` (`attachSecondByEmail`) – Attaches a second parent by email, creating a stub user if the email doesn't exist. Body requires `student_id`, `email`, and optional `firstname`, `lastname`, `relation` (defaults to 'secondary').

**Maintenance Actions:**
- `POST /api/v1/families/set-primary-home` (`setPrimaryHome`) – Sets the `is_primary_home` flag for a student-family relationship. Body requires `family_id`, `student_id`, and `is_primary_home` (0/1).
- `POST /api/v1/families/set-guardian-flags` (`setGuardianFlags`) – Updates guardian flags. Body requires `family_id`, `user_id`, and any of: `receive_emails` (0/1), `is_primary` (0/1), `receive_sms` (0/1), `relation` (string).
- `POST /api/v1/families/unlink-guardian` (`unlinkGuardian`) – Removes a guardian from a family. Body requires `family_id` and `user_id`.
- `POST /api/v1/families/unlink-student` (`unlinkStudent`) – Removes a student from a family. Body requires `family_id` and `student_id`.
- `POST /api/v1/families/import-second-parents` (`importSecondParentsFromLegacy`) – Imports second parents from legacy `parents` table. Creates users for email-only entries, links them as guardians, and ensures all students are linked to families. Returns counts of users created, guardians linked, skipped, and total source rows.

## FilesController
**File:** `app/Http/Controllers/Api/FilesController.php`  
**Purpose:** Serve uploaded receipts and reimbursements from storage with security validation, MIME detection, and HTTP caching support.

**Endpoints:**
- `GET /api/v1/files/receipt/{name}` (`receipt`) – Streams a receipt file with path traversal protection, extension allow-list validation, MIME type detection, ETag/Last-Modified headers, and 304 Not Modified support. Returns `400` for invalid filenames, `404` for missing files or disallowed extensions.
- `GET /api/v1/files/reimb/{name}` (`reimb`) – Streams a reimbursement file with the same security and caching features as `receipt()`.
- `GET /api/v1/files/reimbursement/{name}` (`reimbursement`) – Alias for `reimb()` for backward compatibility.
- `GET /api/v1/files` (`index`) – Requires auth. Query param `type` must be one of `receipts|reimbursements|checks` (defaults to `receipts`). Returns paginated list of files with name, size, and modified timestamp.

**Security Features:**
- Path traversal protection via `basename()` validation
- Extension allow-list: `jpg`, `jpeg`, `png`, `webp`, `gif`, `pdf`
- MIME type detection using `finfo_open()` (with fallback to `mime_content_type()`)
- `X-Content-Type-Options: nosniff` header

**Caching:**
- ETag generation based on filename, modification time, and file size
- Last-Modified header support
- 304 Not Modified responses when `If-None-Match` or `If-Modified-Since` conditions are met
- `Cache-Control: public, max-age=86400` header for browser caching

## FinalController
**File:** `app/Http/Controllers/Api/FinalController.php`  
**Purpose:** Manage final exam scores per student/class-section for the active term.

**Endpoints:**
- `GET /api/v1/finals/student/{student_id}` (`getByStudent`) – Returns the final exam entry for the student scoped by school year/semester.
- `GET /api/v1/finals/class-section/{class_section_id}` (`getByClassSection`) – Returns all students in a class section with their final exam scores. Accepts `class_section_id` as route parameter, query param, or POST body. Uses a subquery to select the latest final exam per student (by MAX(id)) and joins it with the student roster. Returns an array of students with `student_id`, `school_id`, `firstname`, `lastname`, and `score`, along with `semester`, `schoolYear`, and `class_section_id` metadata. Students are ordered by lastname, then firstname.
- `POST /api/v1/finals` (`create`) – Upserts by (`student_id`, `class_section_id`) after validating input; fills metadata and returns `201`.
- `PATCH /api/v1/finals/{id}` (`update`) – Allows changing `score` and `comment`.

## MidtermController
**File:** `app/Http/Controllers/Api/MidtermController.php`  
**Purpose:** Manage midterm exam scores for students in class sections.

**Endpoints:**
- `GET /api/v1/midterm` (`index`) – Returns midterm exam data for a class section. Query parameters:
  - `class_section_id` (integer, optional) – Class section ID (can also be provided via POST or session). If not provided, falls back to session value.
  - Returns array of students with their midterm scores, semester, school year, and class section ID. Uses a subquery to select the latest midterm exam per student (by MAX(id)) and joins it with the student roster. Students are ordered by lastname, then firstname.
- `POST /api/v1/midterm` (`update`) – Updates midterm exam scores (teacher endpoint). Body requires:
  - `final_score` (object, required) – Object mapping student IDs to score objects: `{"student_id": {"score": float}}`
  - `class_section_id` (integer, optional) – Class section ID (can also be provided via session)
  - Automatically uses current authenticated user as `updated_by`. Updates or creates midterm exam records and triggers semester score recalculation via `SemesterScoreService::updateScoresForStudents()`.
- `GET /api/v1/midterm/management` (`showManagement`) – Returns midterm exam data for management view. Same as `index` but intended for administrative use. Query parameters:
  - `class_section_id` (integer, optional) – Class section ID (can also be provided via POST or session)
- `POST /api/v1/midterm/management` (`updateManagement`) – Updates midterm exam scores (management endpoint). Body requires:
  - `final_score` (object, required) – Object mapping student IDs to score objects: `{"student_id": {"score": float}}`
  - `teacher_id` (integer, optional) – Teacher ID to record as updater (defaults to current user)
  - `class_section_id` (integer, optional) – Class section ID (can also be provided via session)
  - Returns updated student roster with scores after successful update. Triggers semester score recalculation.

**Notes:**
- All endpoints require authentication (`auth:api` middleware).
- Class section ID can be provided via query parameter, POST body, or session (checked in that order).
- Scores are automatically scoped to the configured semester and school year.
- Updates trigger `SemesterScoreService::updateScoresForStudents()` to recalculate semester scores.
- The system ensures one score record per student per class section per term (updates existing or creates new).

## FinancialController
**File:** `app/Http/Controllers/Api/FinancialController.php`  
**Purpose:** Generate comprehensive financial reports, summaries, and identify parents with outstanding balances.

**Endpoints:**
- `GET /api/v1/financial/report` (`report`) – Detailed financial report with invoices, payments, payment breakdown by method (cash/credit/check), refunds, expenses, reimbursements, and discounts. Supports `date_from`, `date_to`, and `school_year` query parameters. Returns invoices with parent names, payment breakdown per invoice, overall payment totals by method, grouped refunds/discounts, expenses by category, and reimbursements by status. Also includes available school years list.
- `GET /api/v1/financial/report-summary` (`reportSummary`) – Aggregated financial summary. Supports `date_from`, `date_to`, and `school_year` query parameters. Returns totals for charges (including extra charges), discounts, refunds, expenses, reimbursements (excluding donations), donations to school, paid amounts, unpaid amounts, and net amount calculations. Includes available school years list.
- `GET /api/v1/financial/unpaid-parents` (`unpaidParents`) – Lists parents with outstanding balances (> 0) for a school year. Supports `school_year` query parameter (defaults to configured year). Computes balances dynamically by subtracting payments, discounts, and refunds from invoice totals. Returns parent details, total invoiced, total balance, remaining installments, suggested installment amount, payment type (installment vs no_payment), total paid, and next installment date. Results ordered by balance descending.
- `GET /api/v1/financial/download-csv` (`downloadCsv`) – Downloads financial report as CSV file. Supports `date_from`, `date_to`, and `school_year` query parameters. CSV includes invoices section (with parent names, totals, paid, balance, refund), expenses summary by category, and reimbursements summary by status. Filename format: `financial_report_YYYYMMDD_HHMMSS.csv`.

## FlagController
**File:** `app/Http/Controllers/Api/FlagController.php`  
**Purpose:** Track behavioral/academic flags assigned to students and manage their lifecycle.

**Endpoints:**
- `GET /api/v1/flags` (`index`) – Paginates `current_flags` with optional `student_id`, `flag_type` (or `flag`), `state` (or `flag_state`) filters. Also returns class sections (grades) array for UI dropdowns.
- `GET /api/v1/flags/{id}` (`show`) – Returns a single flag from `current_flag` table.
- `GET /api/v1/flags/students/{grade_id}` (`getStudentsByGrade`) – Returns students in the class section (grade), helpful for flag assignment UIs. Returns array of `{id, name}` objects.
- `POST /api/v1/flags` (`create`) – Alias for `addFlag()`. Creates or updates a flag for a student.
- `POST /api/v1/flags/add` (`addFlag`) – Add or update a flag for a student. If a flag of the same type already exists for the student, it updates it (appends description based on state); otherwise creates a new one. Requires `student_id` (or `student`), `flag` (or `flag_type`), `description` (or `open_description`). Optional: `flag_state`, `state_description`, `grade`. Automatically sets semester and school_year from configuration. New flags default to `Open` state.
- `PATCH /api/v1/flags/{id}/state` (`updateState`) – Updates `flag_state` and/or `state_description`. Updates appropriate description field (`open_description`, `close_description`, or `cancel_description`) based on the new state.
- `POST /api/v1/flags/{id}/close` (`close`) – Alias for `closeFlag()`. Closes a flag and moves it to history.
- `POST /api/v1/flags/{id}/close-flag` (`closeFlag`) – Closes a flag and moves it to history. Requires `state_description` (or `close_description`) in request body. Updates flag state to `Closed`, sets `updated_by_closed`, then moves the flag from `current_flag` to `flag` table and deletes from `current_flag`.
- `POST /api/v1/flags/{id}/cancel` (`cancel`) – Alias for `cancelFlag()`. Cancels a flag and moves it to history.
- `POST /api/v1/flags/{id}/cancel-flag` (`cancelFlag`) – Cancels a flag and moves it to history. Requires `state_description` (or `cancel_description`) in request body. Updates flag state to `Canceled`, sets `updated_by_canceled`, then moves the flag from `current_flag` to `flag` table and deletes from `current_flag`.

**Flag States:** `Open`, `Closed`, `Canceled` (capitalized)

**Flag Lifecycle:** Flags start in `current_flag` table. When closed or canceled, they are moved to `flag` (history) table via `moveToHistory()` method.

## FrontendController
**File:** `app/Http/Controllers/Api/FrontendController.php`  
**Purpose:** Provide lightweight data to the public frontend SPA.

- `GET /api/v1/frontend/user` (`getUser`) – Requires auth; returns first/last name, full name, and initials for the current session.
- `GET /api/v1/frontend/pages` (`getPages`) – Returns the static mapping of page keys to URLs that the frontend expects.

## InfoIconController
**File:** `app/Http/Controllers/Api/InfoIconController.php`  
**Purpose:** Provide user profile icon information (name and initials) for UI display.

- `GET /api/v1/info-icon/profile` (`profileIcon`) – Requires auth; returns user name and initials for the current logged-in user. Returns:
  - `user_name` (string) – Full name of the user (firstname + lastname), or email if name is empty, or "User #ID" as fallback
  - `user_initials` (string) – Uppercase initials derived from firstname and lastname (first letter of each), or first 2 characters of firstname/lastname/email as fallback, or "??" if no data available
  
  Returns `401 Unauthorized` if user is not logged in. Returns `200 OK` with fallback values if user is not found.

## LandingPageController
**File:** `app/Http/Controllers/Api/LandingPageController.php`  
**Purpose:** Deliver role-based dashboard data including school year, deadlines, notifications, students, attendance, grades, and enrollments.

**Endpoints:**
- `GET /api/v1/landing` (`index`) – Requires auth; returns role-specific dashboard data based on user's role. Routes to:
  - `administrator` – Returns basic admin metadata (school year, semester, deadlines)
  - `admin` – Returns basic admin metadata
  - `teacher` – Returns teacher metadata including `class_section_id`
  - `student` – Returns student metadata
  - `parent` / `authorized_user` – Returns comprehensive parent dashboard data (see below)
  - `guest` – Returns basic guest metadata
- `GET /api/v1/landing/data` (`getData`) – Requires auth; returns basic landing page bootstrap data:
  - `school_year`, `semester`
  - `enrollment_deadline`, `refund_deadline`
  - `class_section_id` (for teachers)
  - `user_role`

**Parent Dashboard Data** (returned when role is `parent` or `authorized_user`):
- `notifications` – Array of active, non-expired notifications (personal and broadcast) for parents
- `students` – Array of students associated with the parent, including class section/grade information
- `attendance` – Attendance records for students filtered by current school year/semester
- `grades` – Final scores for students filtered by current school year/semester
- `enrollments` – Enrollment records for students filtered by current school year/semester
- `paymentBalance` – Latest invoice total amount for the parent
- `lastDayOfRegistration` – Enrollment deadline from configuration
- `withdrawalDeadline` – Refund deadline from configuration
- `school_year`, `semester` – Current term information

**User Type Handling:**
- Supports `primary`, `secondary`, and `tertiary` user types
- Automatically resolves parent ID for secondary/tertiary users from `parents` and `authorized_users` tables

## LateSlipLogsController
**File:** `app/Http/Controllers/Api/LateSlipLogsController.php`  
**Purpose:** Paginated search and retrieval of late slip submission logs.

**Endpoints:**
- `GET /api/v1/late-slip-logs` (`index`) – Paginated list of late slip logs with optional filters. Query parameters:
  - `school_year` (string, optional) – Filter by school year (defaults to configured year)
  - `semester` (string, optional) – Filter by semester (defaults to configured semester)
  - `q` (string, optional) – Search term to filter by student name (LIKE search)
  - `date_from` (date, optional) – Filter logs from this date (inclusive, format: Y-m-d or any parseable date)
  - `date_to` (date, optional) – Filter logs until this date (inclusive, format: Y-m-d or any parseable date)
  - `page` (integer, optional) – Page number for pagination (default: 1)
  - `per_page` (integer, optional) – Items per page (default: 20, max: 200)
  - Returns paginated results with logs array, pagination metadata, and applied filters
- `GET /api/v1/late-slip-logs/{id}` (`show`) – Fetch a single late slip log by ID or `404` if not found.

**Log Fields:**
- `id`, `school_year`, `semester`
- `student_name`, `slip_date`, `time_in`
- `grade`, `reason`, `admin_name`
- `printed_by`, `printed_at`

## MessageController
**File:** `app/Http/Controllers/Api/MessageController.php`  
**Purpose:** Inbox/sent endpoints with read receipts for the legacy messaging UI.

- `GET /api/v1/messages` – Query params `type=sent|inbox` and `read=true|false`.
- `GET /api/v1/messages/{id}` – Ensures the caller is sender/recipient, marks as read.
- `POST /api/v1/messages` – Validates `to`, `subject`, `body`, auto-increments `message_number`.

## MessagesController
**File:** `app/Http/Controllers/Api/MessagesController.php`  
**Purpose:** Full-featured messaging module with folder management, attachments, and recipient lookup.

**Endpoints:**
- `GET /api/v1/messages` (`index`) – Returns role and received messages overview. Includes user role and all received messages with sender information.
- `GET /api/v1/messages/inbox` (`inbox`) – Returns all inbox messages (status='received') for the authenticated user, ordered by sent_datetime DESC.
- `GET /api/v1/messages/sent` (`sent`) – Returns all sent messages (status='sent') for the authenticated user, ordered by sent_datetime DESC.
- `GET /api/v1/messages/drafts` (`drafts`) – Returns all draft messages (status='draft') for the authenticated user, ordered by sent_datetime DESC.
- `GET /api/v1/messages/trash` (`trash`) – Returns all trashed messages (status='trashed') for the authenticated user (both sent and received), ordered by sent_datetime DESC.
- `POST /api/v1/messages` (`send`) – Sends a new message. Body requires:
  - `recipient_id` (integer) – Recipient user ID, or
  - `recipient_role` (string) – Role name to resolve recipient (uses hardcoded mapping: teacher=1, parent=2, admin=3, student=4, guest=5, administrator=6)
  - `subject` (string, required) – Message subject
  - `message` (string, required) – Message body
  - Optional: `priority` (string, default: 'normal'), `status` (string, default: 'sent'), `semester`, `school_year`
  - Optional: `attachment` (file upload) – Attachment file
  - Automatically generates `message_number` in format 'MSG-YYYYMMDDHHMMSS'
  - Returns created message
- `POST /api/v1/messages/receive` (`receive`) – Fetches all received messages for the authenticated user and automatically marks them as read. Returns messages with sender information.
- `GET /api/v1/messages/recipients/{type}` (`getRecipients`) – Lists recipients for message composition. Path parameter `type` must be 'teacher' or 'parent':
  - `teacher` – Returns all teachers from teacher_class assignments with their names
  - `parent` – Returns all parents (first and second parents) from students in teacher classes, with their names
  - Returns array of `{id, name}` objects, deduplicated by ID

**Message Fields:**
- `id`, `sender_id`, `recipient_id`
- `subject`, `message`
- `sent_datetime`, `read_status`, `read_datetime`
- `message_number`, `priority` (normal/high/low)
- `attachment` (file path), `status` (sent/received/draft/trashed)
- `semester`, `school_year`

## MessagingController
**File:** `app/Http/Controllers/Api/MessagingController.php`  
**Purpose:** Chat-style messaging (“subjectless” chats) with unread counts.

- `GET /api/v1/messaging/conversations` – Lists conversation previews.
- `GET /api/v1/messaging/conversations/{user}` – Paginated thread with another user; marks inbound as read.
- `POST /api/v1/messaging/messages` – Validates `recipient_id` and body, enforces no self-messaging, records term metadata.
- Additional helpers (mark read, unread count, search users, delete) support the chat client.

## NavBuilderController
**File:** `app/Http/Controllers/Api/NavBuilderController.php`  
**Purpose:** Manage navigation menu items and their role-based access assignments.

**Endpoints:**
- `GET /api/v1/nav-builder/data` (`data`) – Returns navigation builder data including:
  - `items` – Flattened array of all navigation items with hierarchical structure, role assignments, parent relationships, and metadata (label, url, icon_class, target, order, enabled status, depth)
  - `roles` – Array of all available roles (id, name) for assignment
  - `parentOptions` – Alphabetically sorted list of navigation items that can be used as parents (id, label)
  - Items are sorted alphabetically (case-insensitive, ignoring leading articles and punctuation)
  - Requires authentication and admin access (user must have a role that has access to the 'nav-builder' navigation item)
- `POST /api/v1/nav-builder` (`save`) – Creates or updates a navigation item. Body requires:
  - `id` (integer, optional) – If provided, updates existing item; otherwise creates new
  - `label` (string, required) – Display label for the menu item
  - `url` (string, optional) – URL path for the menu item
  - `icon_class` (string, optional) – CSS class for icon
  - `target` (string, optional) – Link target (e.g., '_blank')
  - `menu_parent_id` or `parent_id` (integer, optional) – Parent navigation item ID (null for top-level)
  - `sort_order` (integer, optional) – Sort order (default: 0)
  - `is_enabled` (boolean, optional) – Whether the item is enabled (default: false)
  - `roles` (array, optional) – Array of role IDs to assign to this navigation item
  - Prevents items from being their own parent. Validates parent exists if provided. Clears navigation cache after save.
- `DELETE /api/v1/nav-builder/{id}` (`delete`) – Deletes a navigation item by ID. Children are handled by foreign key constraints (SET NULL on parent). Clears navigation cache after deletion.
- `POST /api/v1/nav-builder/reorder` (`reorder`) – Reorders navigation items. Body requires:
  - `orders` (object, required) – Object mapping item IDs to sort orders: `{"item_id": sort_order, ...}`
  - Clears navigation cache after reordering.

**Access Control:**
- All endpoints require authentication (`auth:api` middleware)
- All endpoints require admin access via `ensureAdmin()` method which:
  - Checks that user has at least one role
  - Verifies that at least one of the user's roles has access to the 'nav-builder' navigation item (checked via `role_nav_items` table)
  - Returns `403 Forbidden` if access is denied

**Notes:**
- Navigation items are organized hierarchically using `menu_parent_id`
- Items are sorted alphabetically using natural case-insensitive sorting, ignoring leading articles ("a", "an", "the") and punctuation
- Role assignments are stored in the `role_nav_items` table linking roles to navigation items
- The `clearCache()` method is called after save/delete/reorder operations (currently a no-op, placeholder for future caching)

## NotificationController
**File:** `app/Http/Controllers/Api/NotificationController.php`  
**Purpose:** Retrieve and mark notifications read for the signed-in user.

- `GET /api/v1/notifications` – Paginated feed with optional `read=true|false`.
- `GET /api/v1/notifications/{id}` – Ensures the caller owns the record.
- `POST /api/v1/notifications/{id}/read` – Sets `is_read` + `read_at`.

## NotificationsController
**File:** `app/Http/Controllers/Api/NotificationsController.php`  
**Purpose:** Placeholder for legacy notifications (no public API methods today).

## NotificationManagementController
**File:** `app/Http/Controllers/Api/NotificationManagementController.php`  
**Purpose:** Admin/management endpoints for creating, sending, and managing notifications to user groups.

**Endpoints:**
- `GET /api/v1/notifications/active` (`activeNotificationsData`) – Returns active (non-deleted, non-expired) notifications. Query parameters:
  - `target_group` (string, optional) – Filter by target group (e.g., 'parent', 'teacher', 'admin')
  - Returns array of notifications with metadata including `id`, `title`, `message`, `priority`, `scheduled_at`, `expires_at`, `created_at`, `target_group`, and `isExpired` flag
- `GET /api/v1/notifications/deleted` (`deletedNotificationsData`) – Returns soft-deleted notifications. Returns array of deleted notifications with `id`, `title`, `message`, `priority`, `scheduled_at`, `expires_at`, and `deleted_at` fields.
- `POST /api/v1/notifications/send` (`send`) – Creates and sends notifications to a target group. Body requires:
  - `title` (string, required) – Notification title
  - `message` (string, required) – Notification message content
  - `target_group` (string, required) – Target role/group (e.g., 'parent', 'teacher', 'admin')
  - `channels` (array, required) – Array of delivery channels: `['in_app', 'email', 'sms']`
  - Creates notification record, creates user notification records for all users in the target group, and sends via specified channels (email/SMS). Returns summary with `notification_id`, `users_notified`, `emails_sent`, and `sms_sent` counts.
- `POST /api/v1/notifications/{id}/restore` (`restore`) – Restores a soft-deleted notification by ID. Returns success message with notification ID.

**Notes:**
- All endpoints require authentication (`auth:api` middleware)
- The `send` endpoint uses `UserModel::getUsersByRole()` to find users in the target group
- Email sending uses `EmailService` for delivery
- SMS sending is currently logged only (placeholder for future SMS service integration)
- Active notifications are filtered by `scheduled_at <= NOW()` and `(expires_at IS NULL OR expires_at > NOW())`
- Notifications support soft deletes and can be restored

## PageController
**File:** `app/Http/Controllers/Api/PageController.php`  
**Purpose:** Handle marketing-site contact submissions and serve static policy/help content.

**Endpoints:**
- `GET /api/v1/pages/privacy` (`privacyPolicy`) – Returns privacy policy HTML content from `public/html/privacy_policy.html`. Returns JSON response with `content` (HTML string) and `type` fields. Returns error if file is not readable or cannot be loaded.
- `GET /api/v1/pages/terms` (`termsOfService`) – Returns terms of service HTML content from `public/html/terms_of_service.html`. Returns JSON response with `content` (HTML string) and `type` fields. Returns error if file is not readable or cannot be loaded.
- `GET /api/v1/pages/help` (`helpCenter`) – Returns help center HTML content from `public/html/help_center.html`. Returns JSON response with `content` (HTML string) and `type` fields. Returns error if file is not readable or cannot be loaded.
- `POST /api/v1/pages/contact` (`submitContact`) – Submits contact form. Body requires:
  - `email` (string, required, valid email) – Contact email address
  - `message` (string, required, min 10 characters) – Contact message content
  - Saves message to `contactus` table (uses `ContactUsModel` if supported, otherwise falls back to direct DB insert)
  - Sends email notification to `alrahma.isgl@gmail.com` using `EmailService`
  - Returns success response with `email` and `email_sent` (boolean) fields
  - Does not fail the request if email sending fails (logs error instead)

**Notes:**
- All endpoints are public (no authentication required)
- Static HTML files are read from `public/html/` directory
- Contact form attempts to use `ContactUsModel` but falls back to direct DB insert if model structure differs
- Email sending failures are logged but don't cause the request to fail

## ParentAttendanceReportController
**File:** `app/Http/Controllers/Api/ParentAttendanceReportController.php`  
**Purpose:** Allow parents to report lateness/absences for their children.

- `POST /api/v1/parent-attendance-reports` – Body includes `student_ids`, `date`, `type`, optional arrival/dismiss times/reason.
- `GET /api/v1/parent-attendance-reports` – Paginated list filtered by school year.
- `PATCH /api/v1/parent-attendance-reports/{id}` – Parents can edit their own submission fields.

## ParentController
**File:** `app/Http/Controllers/Api/ParentController.php`  
**Purpose:** Backbone for the parent portal (enrollment, emergency contacts, authorized pickups, student CRUD, dashboard metrics, payments view, etc.).

- Examples:
  - `GET /api/v1/parent` – Dashboard snapshot (students, balances, notifications).
  - `GET /api/v1/parent/enrollment-classes` + `POST /api/v1/parent/enrollments` – Manage enrollment/withdrawal requests.
  - Emergency contact + authorized user endpoints for CRUD operations.
  - `POST /api/v1/parent/students` / `PATCH /api/v1/parent/students/{id}` – Mirror the flows covered in `ParentFlowsTest`.
  - Additional helpers (`attendance`, `payments`, `events`, `profile`) expose data to the SPA; authorization checks ensure parents only touch their own records.

## ParticipationController
**File:** `app/Http/Controllers/Api/ParticipationController.php`  
**Purpose:** Manage participation scores for students in class sections.

**Endpoints:**
- `GET /api/v1/participation` (`index`) – Returns participation exam data for a class section. Query parameters:
  - `class_section_id` (integer, optional) – Class section ID (can also be provided via POST or session). If not provided, falls back to session value.
  - Returns array of students with their participation scores, semester, school year, and class section ID. Uses a join with the student roster and participation table. Students are ordered by lastname, then firstname.
- `POST /api/v1/participation` (`update`) – Updates participation scores (teacher endpoint). Body requires:
  - `final_score` (object, required) – Object mapping student IDs to score objects: `{"student_id": {"score": float}}`
  - `class_section_id` (integer, optional) – Class section ID (can also be provided via session)
  - Automatically uses current authenticated user as `updated_by`. Updates or creates participation records and triggers semester score recalculation via `SemesterScoreService::updateScoresForStudents()`.
- `GET /api/v1/participation/management` (`showManagement`) – Returns participation data for management view. Same as `index` but intended for administrative use. Query parameters:
  - `class_section_id` (integer, optional) – Class section ID (can also be provided via POST or session)
- `POST /api/v1/participation/management` (`updateManagement`) – Updates participation scores (management endpoint). Body requires:
  - `final_score` (object, required) – Object mapping student IDs to score objects: `{"student_id": {"score": float}}`
  - `teacher_id` (integer, optional) – Teacher ID to record as updater (defaults to current user)
  - `class_section_id` (integer, optional) – Class section ID (can also be provided via session)
  - Returns updated student roster with scores after successful update. Triggers semester score recalculation.
- `GET /api/v1/participation/student/{id}` (`getByStudent`) – Returns the student's participation entry for the current term.

**Notes:**
- All endpoints require authentication (`auth:api` middleware).
- Class section ID can be provided via query parameter, POST body, or session (checked in that order).
- Scores are automatically scoped to the configured semester and school year.
- Updates trigger `SemesterScoreService::updateScoresForStudents()` to recalculate semester scores.
- The system ensures one score record per student per class section per term (updates existing or creates new).

## PaymentController
**File:** `app/Http/Controllers/Api/PaymentController.php`  
**Purpose:** Comprehensive payment management including CRUD operations, manual payment processing, event charges, and invoice balance management.

**Endpoints:**
- `GET /api/v1/payments` (`index`) – Paginated list of payments with optional filters: `parent_id`, `status`, `page`, `per_page`.
- `GET /api/v1/payments/{id}` (`show`) – Returns a single payment by ID or `404` if not found.
- `GET /api/v1/payments/parent/{id}` (`getByParent`) – Returns all payments for a specific parent with invoice numbers. Includes parent name in response.
- `POST /api/v1/payments` (`store`) – Creates a new payment plan. Body requires:
  - `parent_id` (integer, required)
  - `total_amount` (numeric, required)
  - `payment_date` (date, required)
  - Optional: `number_of_installments`, `payment_type`, `semester`, `school_year`
  - Automatically sets `paid_amount` to 0, `balance_amount` to `total_amount`, and `status` to 'Pending'.
- `PATCH /api/v1/payments/{id}` (`update`) – Updates payment fields. Allowed fields: `paid_amount`, `balance`, `status`, `payment_method`, `payment_date`, `check_number`. Requires authentication.
- `DELETE /api/v1/payments/{id}` (`destroy`) – Removes a payment record.
- `POST /api/v1/payments/{id}/update-balance` (`updateBalance`) – Updates balance after payment. Body requires `paid_amount` (numeric, required).
- `GET /api/v1/payments/enrolled-students/{parentId}` (`getEnrolledStudents`) – Returns enrolled students for a parent with their grades.
- `GET /api/v1/payments/manual-pay-search` (`manualPaySearch`) – Search for parent by email or phone and retrieve payment data. Query param `search_term` (required). Returns:
  - `parent` – Parent user data (excluding password)
  - `students` – Students associated with the parent
  - `payments` – Paginated payment history
  - `invoices` – Invoices with calculated balances (total - paid - discounts - refunds)
  - `today_ymd` – Current date
  - `installment_end_ymd` – Installment deadline from configuration
- `POST /api/v1/payments/manual-pay-update` (`manualPayUpdate`) – Records a manual payment. Body requires:
  - `invoice_id` (integer, required)
  - `amount` (numeric, required, must be > 0)
  - `payment_method` (string, required, one of: `cash`, `check`, `card`)
  - Optional: `check_number` (required if method is `check`), `payment_date`, `payment_file` (file upload for receipt)
  - Card payments must equal the full remaining balance
  - Automatically calculates installment sequence, generates transaction ID, updates invoice balance, and triggers enrollment status update if payment is made
  - Dispatches `paymentReceived` event with payment and student data
- `POST /api/v1/payments/manual-pay-edit` (`manualPayEdit`) – Edits an existing manual payment. Body requires:
  - `payment_id` (integer, required)
  - `paid_amount` (numeric, required, must be > 0)
  - `payment_method` (string, required)
  - Optional: `check_number` (required if method is `check`), `payment_file` (file upload)
  - Validates amount doesn't exceed remaining balance (excluding current payment)
  - Recalculates invoice after update
- `GET /api/v1/payments/event-charges` (`eventChargesShow`) – Returns event charges filtered by `school_year` and `semester` query params. Includes parent and student names. Also returns list of all parents.
- `POST /api/v1/payments/event-charges` (`eventChargesUpdate`) – Creates event charges for students. Body requires:
  - `parent_id` (integer, required)
  - `event_name` (string, required)
  - `amount` (numeric, required)
  - `student_ids` (array, required) OR `student_id` (integer, required)
  - Optional: `description`, `semester`, `school_year`
- `GET /api/v1/payments/redirect-page` (`redirectPage`) – Returns payment redirect page data for authenticated parent. Includes parent name, total amount from latest invoice, school ID, and PayPal mode.
- `GET /api/v1/payments/check-file/{filename}` (`serveCheckFile`) – Serves payment receipt files (checks, cards, misc). Searches in multiple upload directories. Returns file download or inline view.
- `GET /api/v1/payments/check-file/{filename}/inline` – Serves payment file inline (same as above with `mode=inline`).

**Payment Processing Features:**
- Automatic invoice balance recalculation after payments
- Installment sequence tracking
- Transaction ID generation
- Enrollment status auto-update when payment is received
- Event dispatching for `paymentReceived` and `studentEnrolled` events
- Support for cash, check, and card payment methods
- File upload support for payment receipts (JPG, PNG, PDF, max 5MB)
- Discount and refund calculation in balance computation
- Grade-based tuition calculation (regular vs youth students)

**Invoice Balance Calculation:**
- Balance = `total_amount` - `paid_amount` - `discounts` - `refund_paid_amount`
- Automatically recalculates when payments are added/edited
- Considers voided/failed payments
- Handles partial payments and full payments

**Notes:**
- All endpoints require authentication (`auth:api` middleware) except file serving endpoints.
- Payments are automatically scoped to configured school year and semester.
- Manual payment updates trigger invoice recalculation and enrollment status updates.
- Event charges can be created for multiple students at once.
- Payment files are stored in `storage/app/public/uploads/payments/{checks|cards|misc}/`.

## PaymentNotificationController
**File:** `app/Http/Controllers/Api/PaymentNotificationController.php`  
**Purpose:** Manage payment reminder notifications - view logs and send monthly tuition reminders to parents.

**Endpoints:**
- `GET /api/v1/payments/notifications` (`index`) – Returns paginated payment notification logs with optional filters. Query parameters:
  - `page` (integer, optional, default: 1) – Page number for pagination
  - `per_page` (integer, optional, default: 20, max: 100) – Number of records per page
  - `from` (string, optional) – Filter logs sent on or after this date
  - `to` (string, optional) – Filter logs sent on or before this date
  - `type` (string, optional) – Filter by notification type: `no_payment` or `installment`
  - Returns paginated list of notification logs with parent names included
- `POST /api/v1/payments/notifications/send` (`send`) – Sends payment reminder notifications. Body parameters:
  - `parent_id` (integer, optional) – If provided, sends notification to this parent only. If omitted, sends to all parents with positive balance
  - `type` (string, optional) – Notification type: `no_payment` or `installment`. If not provided, automatically detected based on payment history
  - `school_year` (string, optional) – School year to process (defaults to configured school year)
  - `force` (integer, optional, default: 0) – Set to `1` to bypass idempotency check and send even if already sent this month
  - Returns summary with `sent`, `skipped`, `failed` counts and detailed results array

**Notification Behavior:**
- **Single Parent Mode:** When `parent_id` is provided:
  - Sends notification only to that parent (if balance > 0 or `force=1`)
  - Skips if already sent this month/type (unless `force=1`)
  - Skips if balance is 0 (unless `force=1`)
- **Bulk Mode:** When `parent_id` is omitted:
  - Processes all parents with invoices in the selected school year
  - Sends to parents with positive balance (or all if `force=1`)
  - Respects idempotency (1 email per month/type per parent) unless `force=1`
  - Optionally notifies head of finance users in-app

**Email Content:**
- Subject: "Monthly Tuition Reminder — {school_year}"
- Includes:
  - Personalized greeting with parent name
  - Current outstanding balance
  - Remaining installments count
  - Suggested installment amount for current month
  - Maximum installments available
  - Reminder period (month and year)
- Email is sent to primary parent email and CC'd to secondary guardian (if configured and `receive_emails=1`)

**Balance Calculation:**
- Computes total balance across all invoices for parent/school year
- Formula: `total_amount - discounts - paid_amount - refunds`
- Excludes voided, failed, or cancelled payments
- Rounds to 2 decimal places

**Idempotency:**
- Prevents duplicate notifications by checking `payment_notification_logs` table
- One notification per parent per month per type (unless `force=1`)
- Checks `period_year`, `period_month`, `type`, and `parent_id`

**Notification Types:**
- `no_payment` – Parent has no payment history for the school year
- `installment` – Parent has made at least one payment for the school year

**Notes:**
- All endpoints require authentication (`auth:api` middleware)
- Email sending uses `EmailService` with 'finance' profile
- Notifications are logged in `payment_notification_logs` table with full details
- Secondary guardian emails are automatically included if they have `receive_emails=1`
- Head of finance users are optionally notified in bulk mode (logged for now, can be extended to in-app notifications)

## PaymentTransactionController
**File:** `app/Http/Controllers/Api/PaymentTransactionController.php`  
**Purpose:** Manage payment-processor transactions linked to payments. Handles creation, retrieval, and status updates for payment transactions (installments).

**Endpoints:**
- `GET /api/v1/payment-transactions` (`index`) – Returns paginated list of payment transactions with optional filters. Query parameters:
  - `page` (integer, optional, default: 1) – Page number for pagination
  - `per_page` (integer, optional, default: 20, max: 100) – Number of records per page
  - `payment_id` (integer, optional) – Filter transactions by payment ID
  - `status` (string, optional) – Filter transactions by payment status
  - Returns paginated list of transactions
- `GET /api/v1/payment-transactions/{id}` (`show`) – Returns a single payment transaction by ID. Returns `404` if not found.
- `GET /api/v1/payment-transactions/payment/{paymentId}` (`getByPayment`) – Returns all transactions for a specific payment, ordered by transaction date (newest first). Returns `404` if no transactions found for the payment.
- `POST /api/v1/payment-transactions` (`store`) – Creates a new payment transaction (installment). Body parameters:
  - `transaction_id` (string, required, unique) – Unique transaction identifier
  - `payment_id` (integer, required) – Reference to the payment record
  - `amount` (numeric, required, min: 0) – Transaction amount
  - `payment_method` (string, required, max: 50) – Payment method (e.g., 'cash', 'check', 'card')
  - `transaction_date` (string, optional) – Transaction date in `Y-m-d H:i:s` format (defaults to current date/time)
  - `transaction_fee` (numeric, optional, min: 0) – Transaction fee (defaults to 0)
  - `payment_reference` (string, optional, max: 255) – Payment reference number
  - `is_full_payment` (integer, optional) – Flag indicating full payment: `0` for installment, `1` for full payment (defaults to 0)
  - Automatically sets `payment_status` to 'Pending' and includes current `school_year` and `semester` from configuration
  - Returns `201` with created transaction data
- `PATCH /api/v1/payment-transactions/{transactionId}/status` (`updateStatus`) – Updates the payment status of a transaction. Body parameters:
  - `status` (string, required, max: 50) – New payment status (e.g., 'Pending', 'Completed', 'Failed', 'Refunded')
  - The `transactionId` can be either the numeric `id` or the string `transaction_id`
  - Returns updated transaction data on success, `404` if transaction not found

**Transaction Data:**
- Each transaction is linked to a payment record via `payment_id`
- Transactions track installment payments and full payments via `is_full_payment` flag
- Default status is 'Pending' when created
- Automatically includes `school_year` and `semester` from system configuration
- Supports transaction fees and payment references

**Notes:**
- All endpoints require authentication (`auth:api` middleware)
- Transaction IDs must be unique across all transactions
- Status updates can be performed using either the numeric ID or the transaction_id string
- Transactions are ordered by `transaction_date` descending when retrieved by payment ID
- The controller uses `PaymentTransactionModel` which provides helper methods like `getTransactionsByPaymentId()` and `updateTransactionStatus()`

## PaypalTransactionsController
**File:** `app/Http/Controllers/Api/PaypalTransactionsController.php`  
**Purpose:** Inspect and export PayPal webhook transaction data stored locally. Provides search, retrieval, and CSV export functionality for PayPal payment transactions.

**Endpoints:**
- `GET /api/v1/paypal-transactions` (`index`) – Returns paginated list of PayPal transactions with optional search. Query parameters:
  - `page` (integer, optional, default: 1) – Page number for pagination
  - `per_page` (integer, optional, default: 20, max: 100) – Number of records per page
  - `q` (string, optional) – Search keyword that searches across multiple fields:
    - `transaction_id` – PayPal transaction identifier
    - `payer_email` – Payer's email address
    - `event_type` – PayPal webhook event type
    - `order_id` – Order identifier
    - `parent_school_id` – Parent school ID
  - Returns paginated list of transactions ordered by creation date (newest first)
- `GET /api/v1/paypal-transactions/{id}` (`show`) – Returns a single PayPal transaction by numeric ID. Returns `404` if not found.
- `GET /api/v1/paypal-transactions/transaction/{transactionId}` (`getByTransactionId`) – Returns a transaction by PayPal transaction ID (string). Returns `404` if not found.
- `GET /api/v1/paypal-transactions/export-csv` (`exportCsv`) – Exports PayPal transactions to CSV file. Query parameters:
  - `q` (string, optional) – Search keyword (same search logic as `index` endpoint)
  - Returns a downloadable CSV file with filename format: `paypal_transactions_YYYYMMDD_HHMMSS.csv`
  - CSV columns: ID, Transaction ID, Order ID, Parent School ID, Email, Amount, Net Amount, Currency, Status, Event Type, Created At
  - Includes all matching transactions (no pagination limit for export)

**Search Functionality:**
- The search keyword (`q` parameter) performs a case-insensitive LIKE search across multiple fields
- Uses OR logic - matches if any field contains the keyword
- Searches in: `transaction_id`, `payer_email`, `event_type`, `order_id`, `parent_school_id`

**CSV Export:**
- Generates CSV file with all matching transactions
- File is streamed directly to the browser for download
- Filename includes timestamp for uniqueness
- Includes all transaction fields relevant for reporting/analysis
- Respects the same search filters as the index endpoint

**Transaction Data:**
- Transactions are stored from PayPal webhook events
- Includes payment details: amount, currency, fees, net amount
- Tracks payer information: email address
- Contains event metadata: event type, status, order ID
- Linked to parent/school via `parent_school_id`
- Includes raw webhook payload for reference

**Notes:**
- All endpoints require authentication (`auth:api` middleware)
- Transactions are ordered by `created_at` descending (newest first)
- CSV export returns all matching records without pagination
- The controller uses `PayPalPaymentModel` which stores webhook data from PayPal
- Search is case-insensitive and uses SQL LIKE pattern matching

## PaypalWebhook
**File:** `app/Http/Controllers/Api/PaypalWebhook.php`  
**Purpose:** Validate and process PayPal webhook notifications.

- `POST /api/v1/paypal/webhook` – Verifies headers + signature, requests an OAuth token, and persists the webhook payload when verification succeeds.

## PolicyController
**File:** `app/Http/Controllers/Api/PolicyController.php`  
**Purpose:** Serve school and picture policy documents as JSON API responses. Loads policy content from PHP partial files and renders them using Blade views.

**Endpoints:**
- `GET /api/v1/policy` (`index`) – Placeholder endpoint that returns a success response. Can be used to check if the policy API is available.
- `GET /api/v1/policy/picture` (`schoolPicturePolicy`) – Returns the school picture policy content. 
  - Loads content from `resources/views/policy/picture_policy_partial.php` (PHP file that may return data array or output HTML)
  - If the partial returns an array, attempts to render `resources/views/policy/picture_policy.blade.php` view with that data
  - If the partial returns HTML string, uses it directly
  - Returns JSON response with `html` field containing the rendered policy content
  - Returns `404` if the partial file is not found
- `GET /api/v1/policy/school` (`schoolPolicy`) – Returns the main school policy content.
  - Loads metadata from `resources/views/policy/school_policy_partial.php` (PHP file that returns data array)
  - Renders `resources/views/policy/school_policy.blade.php` Blade view with the metadata
  - Returns JSON response with both `meta` (data array) and `html` (rendered content) fields
  - Returns `404` if the partial file is not found
  - Falls back to JSON-encoded meta if the Blade view doesn't exist

**Policy File Structure:**
- Partial files (`.php`) are included and expected to return data arrays or HTML strings
- Blade views (`.blade.php`) are rendered with the data from partial files
- Partial files are located in `resources/views/policy/` directory

**Response Format:**
- All endpoints return JSON with standard API response format: `{status: true, message: "...", data: {...}}`
- Picture policy returns: `{html: "<rendered HTML>"}`
- School policy returns: `{meta: {...}, html: "<rendered HTML>"}`

**Notes:**
- All endpoints are **public** (no authentication required)
- Policy files are read from the filesystem at runtime
- Errors are logged and return appropriate HTTP status codes (404 for not found, 500 for server errors)
- The controller handles both array and string returns from PHP partial files for flexibility

## PreferencesController
**File:** `app/Http/Controllers/Api/PreferencesController.php`  
**Purpose:** Let users adjust notification + UI preferences.

- `GET /api/v1/preferences` – Retrieves or falls back to defaults; includes current `style_color`/`menu_color`.
- `PATCH /api/v1/preferences` – Validates toggles and theme selections, persists them, updates session colors.

## PrintablesReportsController
**File:** `app/Http/Controllers/Api/PrintablesReportsController.php`  
**Purpose:** Provide report-card metadata, badge printing, sticker generation, and student data for printable reports. Handles metadata retrieval, badge print logging, and sticker count calculations.

**Endpoints:**
- `GET /api/v1/printables/report-card-meta` (`reportCardMeta`) – Returns available school years, students, and class sections for report generation. Query parameters:
  - `school_year` (string, optional) – Filter by school year (defaults to configured school year)
  - `semester` (string, optional) – Filter by semester (defaults to configured semester)
  - Returns:
    - `schoolYears` – Array of available school years
    - `selectedYear` – Currently selected school year
    - `semesters` – Array of available semesters for selected year
    - `selectedSemester` – Currently selected semester
    - `students` – Array of students with scores in selected year/semester (or all students if none found)
    - `classSections` – Array of class sections for selected year
- `GET /api/v1/printables/badge-status` (`badgePrintStatus`) – Returns badge print status for given users. Query parameters:
  - `user_ids` (array|string, required) – User IDs (can be comma-separated string or array)
  - `school_year` (string, optional) – Filter by school year
  - Returns object mapping user IDs to print status: `{count, last_printed_at, last_printed_by}`
- `POST /api/v1/printables/badge-status` (`logBadgePrint`) – Logs badge prints for users. Body parameters:
  - `user_ids` (array, required) – Array of user IDs
  - `roles` (array, optional) – Map of user_id => role label
  - `classes` (array, optional) – Map of user_id => class name
  - `school_year` (string, optional) – School year for the prints
  - Returns count of inserted log records
- `GET /api/v1/printables/students-by-class/{classSectionId}` (`getByClass`) – Returns students in a class section. Returns array of students with id, firstname, lastname, registration_grade, and gender.
- `GET /api/v1/printables/students-by-class/{classSectionId}/alt` (`studentsByClass`) – Alternative endpoint for students by class with additional class section name in response.
- `GET /api/v1/printables/preview-sticker-counts` (`previewStickerCounts`) – Returns sticker counts per student. Query parameters:
  - `class_id` (integer, optional) – If provided, returns counts for that class only; otherwise returns for entire school year
  - Returns:
    - `students` – Array of students with `primary_count` and `secondary_count` sticker requirements
    - `totals` – Summary totals for primary, secondary, and student counts
- `POST /api/v1/printables/badge` (`badge`) – Generates staff badge PDF. **Note:** Requires FPDF library integration (not yet implemented).
- `POST /api/v1/printables/generate-stickers` (`generateStickers`) – Generates student name sticker PDF. **Note:** Requires FPDF library integration (not yet implemented).
- `GET /api/v1/printables/report-card/{studentId}` (`generateSingleReport`) – Generates single student report card PDF. **Note:** Requires FPDF library integration (not yet implemented).
- `GET /api/v1/printables/report-card/class/{classSectionId}` (`generateClassReport`) – Generates report cards for all students in a class. **Note:** Requires FPDF library integration (not yet implemented).

**Sticker Count Rules:**
- Special grades: KG (1), 1-A (3), 1-B (4), 2-A (5), 2-B (5), 9 (2)
- Upper block (3-8): New students (4), Grade 5 returning (3), Other returning (2)
- Other grades: Default (4)
- Youth and KG classes are excluded from sticker calculations

**Badge Print Logging:**
- Tracks which users had badges printed, when, and by whom
- Supports role and class metadata for each print
- Can filter by school year
- Used for audit and tracking purposes

**Notes:**
- All endpoints require authentication (`auth:api` middleware)
- PDF generation endpoints (`badge`, `generateStickers`, `generateSingleReport`, `generateClassReport`) require FPDF library integration and are currently placeholders
- Sticker counts follow specific rules based on grade level and student status (new vs returning)
- Report card metadata automatically falls back to all students if none found for selected year/semester
- School years are collected from both `classSection` and `semester_scores` tables

## ProjectController
**File:** `app/Http/Controllers/Api/ProjectController.php`  
**Purpose:** Manage project scores for students, similar to homework and participation. Provides endpoints for teachers to add project columns, update scores, and view project data for their class sections.

**Endpoints:**
- `GET /api/v1/projects` (`index`) – List projects with optional filters. Query parameters:
  - `page` (integer, optional) – Page number for pagination (default: 1)
  - `per_page` (integer, optional) – Items per page (default: 20, max: 100)
  - `student_id` (integer, optional) – Filter by student ID
  - `class_section_id` (integer, optional) – Filter by class section ID
  - Returns paginated list of projects for the current semester and school year
- `GET /api/v1/projects/{id}` (`show`) – Get a single project by ID. Returns project details or 404 if not found.
- `GET /api/v1/projects/student/{id}` (`getByStudent`) – Get all projects for a specific student. Returns array of projects ordered by `project_index` for the current semester and school year.
- `POST /api/v1/projects` (`store`) – Create a new project entry. Body parameters:
  - `student_id` (integer, required) – Student ID
  - `class_section_id` (integer, required) – Class section ID
  - `project_index` (integer, required) – Project index/column number
  - `score` (float, optional) – Project score
  - `comment` (string, optional) – Project comment
  - Returns created project with 201 status
- `PATCH /api/v1/projects/{id}` (`update`) – Update an existing project. Body parameters (all optional):
  - `score` (float) – Project score
  - `comment` (string) – Project comment
  - `project_index` (integer) – Project index/column number
  - Returns updated project
- `GET /api/v1/projects/add-project` (`addProject`) – Get project data for teacher's class section. Automatically determines class section from teacher's `teacher_class` record. Returns:
  - `students` – Array of students with their project scores organized by project index
  - `project_headers` – Array of project index values (column headers)
  - `semester` – Current semester
  - `school_year` – Current school year
  - `class_section_id` – Class section ID
- `POST /api/v1/projects/update-scores` (`updateProjectScores`) – Update project scores for multiple students. Body parameters:
  - `scores` (array, required) – Nested array: `{student_id: {project_index: score}}`
  - `class_section_id` (integer, optional) – Class section ID (falls back to session)
  - Automatically updates semester scores via `SemesterScoreService` after saving
  - Returns success message
- `POST /api/v1/projects/add-column` (`addNextProjectColumn`) – Add a new project column for all students in a class section. Body parameters:
  - `class_section_id` (integer, optional) – Class section ID (falls back to session)
  - Creates a new project index (highest existing + 1) and inserts empty project records for all students
  - Returns:
    - `status` – "success"
    - `project_index` – The new project index that was created
    - `students_processed` – Number of students for whom records were created
- `GET /api/v1/projects/management` (`showProjectMngt`) – Get project management data for a class section. Query/body parameters:
  - `class_section_id` (integer, optional) – Can be provided via POST body, GET query, or session
  - Returns:
    - `project_scores` – Project scores organized by student ID
    - `students` – Array of students in the class section
    - `project_headers` – Array of project index values
    - `semester` – Current semester
    - `school_year` – Current school year
    - `class_section_id` – Class section ID
- `POST /api/v1/projects/update` (`updateProject`) – Update project scores (management endpoint). Body parameters:
  - `scores` (array, required) – Nested array: `{student_id: {project_index: score}}`
  - `student_ids` (array, required) – Array of student IDs
  - `semester` (string, optional) – Semester (defaults to current)
  - `school_year` (string, optional) – School year (defaults to current)
  - `teacher_id` (integer, optional) – Teacher ID (defaults to current user)
  - `class_section_id` (integer, optional) – Class section ID (falls back to session)
  - Automatically updates semester scores via `SemesterScoreService` after saving
  - Returns success message

**Notes:**
- All endpoints require authentication (`auth:api` middleware)
- Project scores are automatically scoped to the current semester and school year from configuration
- When updating scores, the system automatically recalculates semester scores using `SemesterScoreService`
- Project indices are numeric and represent column numbers in the grading interface
- The `add-project` endpoint automatically determines the teacher's class section from the `teacher_class` table
- Session is used to persist `class_section_id` for subsequent requests

## PurchaseOrderController
**File:** `app/Http/Controllers/Api/PurchaseOrderController.php`  
**Purpose:** Create and track purchase orders plus their line items. Handles PO creation, receiving items, and cancellation.

**Endpoints:**
- `GET /api/v1/purchase-orders` (`index`) – Paginated list of purchase orders with keyword search. Query parameters:
  - `page` (integer, optional) – Page number for pagination (default: 1)
  - `per_page` (integer, optional) – Items per page (default: 20, max: 100)
  - `q` (string, optional) – Keyword search for PO number or supplier name
  - Returns paginated list with supplier names joined
- `GET /api/v1/purchase-orders/{id}` (`show`) – Get a single purchase order with all line items. Returns:
  - Purchase order header with supplier name
  - Array of line items with supply names and units (if supply_id maps to inventory_items)
  - Returns 404 if not found
- `POST /api/v1/purchase-orders` (`store`) – Create a new purchase order with line items. Supports both CodeIgniter-style form arrays and modern JSON format. Body parameters:
  - `po_number` (string, required) – Purchase order number
  - `supplier_id` (integer, required) – Supplier ID
  - `order_date` (date, required) – Order date (Y-m-d format)
  - `expected_date` (date, optional) – Expected delivery date
  - `status` (string, optional) – Status: 'draft' or 'ordered' (default: 'ordered')
  - `notes` (string, optional) – Notes
  - `tax` (float, optional) – Tax amount (default: 0.00)
  - **Modern JSON format:**
    - `items` (array, required) – Array of item objects:
      - `supply_id` (integer, required) – Supply/inventory item ID
      - `description` (string, optional) – Item description
      - `quantity` (integer, required) – Quantity ordered
      - `unit_cost` (float, required) – Unit cost
  - **CodeIgniter-style form arrays:**
    - `item_supply_id[]` (array, required) – Array of supply IDs
    - `item_description[]` (array, optional) – Array of descriptions
    - `item_quantity[]` (array, required) – Array of quantities
    - `item_unit_cost[]` (array, required) – Array of unit costs
  - Automatically calculates subtotal, total, and creates all line items in a transaction
  - Returns created purchase order with 201 status
- `PATCH /api/v1/purchase-orders/{id}` (`update`) – Update purchase order fields. Body parameters (all optional):
  - `status` (string) – New status
  - `expected_date` (date) – Expected delivery date
  - `notes` (string) – Notes
  - Returns updated purchase order
- `POST /api/v1/purchase-orders/{id}/receive` (`receive`) – Receive items (partial or full) from a purchase order. Body parameters:
  - `received` (array, required) – Object mapping item IDs to quantities: `{item_id: quantity}`
  - Updates `received_qty` on purchase order items
  - Updates inventory item quantities (if `supply_id` maps to `inventory_items`)
  - Creates inventory movement records for tracking
  - Automatically sets PO status to 'received' if all items are fully received, otherwise keeps 'ordered'
  - Cannot receive items if PO status is 'canceled' or 'received'
  - Returns success message indicating full or partial receipt
- `POST /api/v1/purchase-orders/{id}/cancel` (`cancel`) – Cancel a purchase order. Body parameters: none
  - Sets PO status to 'canceled'
  - Cannot cancel a PO with status 'received'
  - Returns updated purchase order

**Notes:**
- All endpoints require authentication (`auth:api` middleware)
- Purchase orders support statuses: 'draft', 'ordered', 'received', 'canceled'
- When receiving items, the system automatically updates inventory quantities and creates movement records
- The `store` method supports both legacy CodeIgniter form array format and modern JSON format for backward compatibility
- Line items are validated to ensure at least one valid item with quantity > 0
- All financial calculations (subtotal, tax, total) are performed automatically
- Database transactions ensure data consistency when creating POs or receiving items

## QuizController
**File:** `app/Http/Controllers/Api/QuizController.php`  
**Purpose:** Manage quiz scores for students, similar to homework and projects. Provides endpoints for teachers to add quiz columns, update scores, and view quiz data for their class sections.

**Endpoints:**
- `GET /api/v1/quizzes` (`index`) – List quizzes with optional filters. Query parameters:
  - `page` (integer, optional) – Page number for pagination (default: 1)
  - `per_page` (integer, optional) – Items per page (default: 20, max: 100)
  - `student_id` (integer, optional) – Filter by student ID
  - `class_section_id` (integer, optional) – Filter by class section ID
  - Returns paginated list of quizzes for the current semester and school year
- `GET /api/v1/quizzes/{id}` (`show`) – Get a single quiz by ID. Returns quiz details or 404 if not found.
- `GET /api/v1/quizzes/student/{id}` (`getByStudent`) – Get all quizzes for a specific student. Returns array of quizzes ordered by `quiz_index` for the current semester and school year.
- `POST /api/v1/quizzes` (`store`) – Create a new quiz entry. Body parameters:
  - `student_id` (integer, required) – Student ID
  - `class_section_id` (integer, required) – Class section ID
  - `quiz_index` (integer, required) – Quiz index/column number
  - `score` (float, optional) – Quiz score
  - `comment` (string, optional) – Quiz comment
  - Returns created quiz with 201 status
- `PATCH /api/v1/quizzes/{id}` (`update`) – Update an existing quiz. Body parameters (all optional):
  - `score` (float) – Quiz score
  - `comment` (string) – Quiz comment
  - `quiz_index` (integer) – Quiz index/column number
  - Returns updated quiz
- `GET /api/v1/quizzes/add-quiz` (`addQuiz`) – Get quiz data for teacher's class section. Query/body parameters:
  - `class_section_id` (integer, optional) – Can be provided via POST body, GET query, or session
  - Returns:
    - `students` – Array of students with their quiz scores organized by quiz index
    - `quiz_headers` – Array of quiz index values (column headers)
    - `semester` – Current semester
    - `school_year` – Current school year
    - `class_section_id` – Class section ID
- `POST /api/v1/quizzes/update-scores` (`updateQuizScores`) – Update quiz scores for multiple students. Body parameters:
  - `scores` (array, required) – Nested array: `{student_id: {quiz_index: score}}` or `{student_id: score}` (normalized to quiz_index 1)
  - `class_section_id` (integer, optional) – Class section ID (falls back to session)
  - Automatically updates semester scores via `SemesterScoreService` after saving
  - Returns success message
- `POST /api/v1/quizzes/add-column` (`addNextQuizColumn`) – Add a new quiz column for all students in a class section. Body parameters:
  - `class_section_id` (integer, optional) – Class section ID (falls back to session)
  - Creates a new quiz index (highest existing + 1) and inserts empty quiz records for all students
  - Returns:
    - `status` – "success"
    - `quiz_index` – The new quiz index that was created
    - `new_quiz_id` – ID of the first inserted quiz record
    - `students_processed` – Number of students for whom records were created
- `GET /api/v1/quizzes/management` (`showQuizMngt`) – Get quiz management data for a class section. Query/body parameters:
  - `class_section_id` (integer, optional) – Can be provided via POST body, GET query, or session
  - Returns:
    - `quiz_scores` – Quiz scores organized by student ID
    - `students` – Array of students in the class section
    - `quiz_headers` – Array of quiz index values
    - `semester` – Current semester
    - `school_year` – Current school year
    - `class_section_id` – Class section ID
- `POST /api/v1/quizzes/update` (`updateQuiz`) – Update quiz scores (management endpoint). Body parameters:
  - `scores` (array, required) – Nested array: `{student_id: {quiz_index: score}}`
  - `student_ids` (array, required) – Array of student IDs
  - `semester` (string, optional) – Semester (defaults to current)
  - `school_year` (string, optional) – School year (defaults to current)
  - `teacher_id` (integer, optional) – Teacher ID (defaults to current user)
  - `class_section_id` (integer, optional) – Class section ID (falls back to session)
  - Automatically updates semester scores via `SemesterScoreService` after saving
  - Returns success message

**Notes:**
- All endpoints require authentication (`auth:api` middleware)
- Quiz scores are automatically scoped to the current semester and school year from configuration
- When updating scores, the system automatically recalculates semester scores using `SemesterScoreService`
- Quiz indices are numeric and represent column numbers in the grading interface
- The `update-scores` endpoint normalizes single score inputs to quiz_index 1 for backward compatibility
- Session is used to persist `class_section_id` for subsequent requests
- Quiz data is organized by student with scores mapped to quiz indices for easy grid display

## RefundController
**File:** `app/Http/Controllers/Api/RefundController.php`  
**Purpose:** Collect and manage refund requests tied to invoices.

- `GET /api/v1/refunds` / `GET /api/v1/refunds/{id}` – Filter by `parent_id` or `status` when reviewing requests.
- `POST /api/v1/refunds` – Auth-required; body must include `parent_id`, `invoice_id`, `refund_amount`, `reason`.
- `PATCH /api/v1/refunds/{id}` – Update status, payout amounts/methods, or notes; stamps approval/refunded timestamps when applicable.

## RegisterController
**File:** `app/Http/Controllers/Api/RegisterController.php`  
**Purpose:** Public registration portal for parents/guests, including CAPTCHA and confirmation email handling. Handles user registration with validation, role assignment, optional second parent information, and email confirmation.

**Endpoints:**
- `GET /api/v1/register` (`index`) – Generate or retrieve CAPTCHA challenge for registration form. Returns:
  - `captcha_question` – Random CAPTCHA string (4-8 characters) stored in session
  - If CAPTCHA already exists in session, returns existing value
  - Used to prevent automated registrations
- `GET /api/v1/register/success` (`registrationSuccess`) – Get registration success data. Returns:
  - `email` – Email address from registration session
  - Returns 400 error if no registration session exists
  - Used to display confirmation screen after successful registration
- `POST /api/v1/register` (`register`) – Submit registration form. Body parameters:
  - **Required fields:**
    - `firstname` (string, required) – First name (2-30 chars, letters/spaces/hyphens only)
    - `lastname` (string, required) – Last name (2-30 chars, letters/spaces/hyphens only)
    - `gender` (string, required) – Gender: 'Male' or 'Female'
    - `email` (string, required) – Email address (max 50 chars, valid email format)
    - `confirm_email` (string, required) – Must match `email`
    - `cellphone` (string, required) – Phone number (10-20 chars, digits/spaces/hyphens/parentheses/dots)
    - `city` (string, required) – City name (2-30 chars, letters/spaces only)
    - `state` (string, required) – State code: 'CT', 'ME', 'MA', 'NH', 'NY', 'RI', or 'VT'
    - `zip` (string, required) – ZIP code (exactly 5 digits)
    - `accept_school_policy` (boolean/string, required) – Must be accepted/checked
    - `captcha` (string, required) – CAPTCHA answer (4-10 alphanumeric chars, must match session)
  - **Optional fields:**
    - `address_street` (string, optional) – Street address (max 150 chars)
    - `apt` (string, optional) – Apartment/unit number (max 10 chars)
    - `is_parent` (boolean/string, optional) – If '1' or true, registers as parent; otherwise registers as guest
    - `no_second_parent_info` (boolean/string, optional) – If '1' or true, skips second parent information
  - **Second parent fields (required if `is_parent` is true and `no_second_parent_info` is false):**
    - `second_firstname` (string, required) – Second parent first name
    - `second_lastname` (string, required) – Second parent last name
    - `second_gender` (string, required) – Second parent gender: 'Male' or 'Female'
    - `second_email` (string, required) – Second parent email address
    - `second_cellphone` (string, required) – Second parent phone number
  - **Process:**
    1. Validates all input fields
    2. Checks CAPTCHA answer against session
    3. Verifies email is not already registered (checks for pending activation)
    4. Determines role ('parent' or 'guest') based on `is_parent` flag
    5. Generates unique token for email confirmation
    6. Creates user record with formatted data
    7. Assigns role to user
    8. Optionally creates second parent record if applicable
    9. Sends confirmation email with activation link
    10. Stores email in session and clears CAPTCHA
  - **Returns:**
    - Success: `{email: "user@example.com"}` with 200 status
    - Validation errors: 422 with error details
    - Duplicate email: 409 with appropriate message
    - Server errors: 500 with error message

**Notes:**
- All endpoints are **public** (no authentication required)
- CAPTCHA is stored in session and must be answered correctly
- Email addresses are normalized to lowercase
- Phone numbers are formatted using `PhoneFormatterService`
- Names and addresses are formatted (proper case)
- School ID is auto-generated using `SchoolIdService`
- Users are created with `is_verified = 0` and `status = 'Inactive'` until email confirmation
- Activation link format: `/user/confirm/{token}`
- Second parent information is optional for parent registrations
- All database operations are wrapped in transactions for data integrity
- Email confirmation is sent using `EmailService` with different templates for parents vs. guests

## ReimbursementController
**File:** `app/Http/Controllers/Api/ReimbursementController.php`  
**Purpose:** Track reimbursements for staff expenses.

- `GET /api/v1/reimbursements` / `{id}` – Scoped to the active school year/semester; filter by `status` or `reimbursed_to`.
- `POST /api/v1/reimbursements` – Requires `amount`, `reimbursed_to`, `description`, and `expense_id`.
- `PATCH /api/v1/reimbursements/{id}` – Update status/method/check information, stamping approver metadata.

## RFIDController
**File:** `app/Http/Controllers/Api/RFIDController.php`  
**Purpose:** Process RFID scans and expose scan history.

- `POST /api/v1/rfid/process` – Validates the incoming `rfid`, finds the matching user or student, logs to `scan_log`, and returns the resolved entity.
- `GET /api/v1/rfid/logs` – Paginated log with associated user/student names and timestamps.

## RolePermissionController
**File:** `app/Http/Controllers/Api/RolePermissionController.php`  
**Purpose:** Admin tooling for roles, permissions, and assignments. Provides CRUD operations for roles and permissions, role-permission mapping, and user role assignment.

**Endpoints:**
- **Roles:**
  - `GET /api/v1/rolepermission/roles` (`roles`) – List all roles with user counts. Returns array of roles with:
    - `id` – Role ID
    - `name` – Role name
    - `description` – Role description
    - `user_count` – Number of users with this role
  - `GET /api/v1/rolepermission/roles/{id}` (`showRole`) – Get a single role by ID. Returns role details or 404 if not found.
  - `POST /api/v1/rolepermission/roles` (`storeRole`) – Create a new role. Body parameters:
    - `name` (string, required) – Role name (3-255 chars, lowercase stored)
    - `slug` (string, optional) – URL-friendly slug (max 64 chars, auto-generated from name if not provided)
    - `description` (string, optional) – Role description (max 500 chars, lowercase stored)
    - `dashboard_route` (string, required) – Dashboard route path (lowercase, alphanumeric/underscores/slashes/hyphens only)
    - `priority` (integer, required) – Priority value (0-100000)
    - `is_active` (integer, required) – Active status: 0 or 1
    - Returns created role with 201 status
  - `PATCH /api/v1/rolepermission/roles/{id}` (`updateRole`) – Update an existing role. Body parameters (all optional):
    - `name` (string) – Role name
    - `slug` (string) – Role slug
    - `description` (string) – Role description
    - `dashboard_route` (string) – Dashboard route
    - `priority` (integer) – Priority value
    - `is_active` (integer) – Active status
    - Returns updated role
  - `DELETE /api/v1/rolepermission/roles/{id}` (`deleteRole`) – Delete a role. Returns success message or 404 if not found.
- **Permissions:**
  - `GET /api/v1/rolepermission/permissions` (`permissions`) – List all permissions. Returns array of permissions with:
    - `id` – Permission ID
    - `name` – Permission name
    - `description` – Permission description
    - `created_at` – Creation timestamp
    - `updated_at` – Update timestamp
  - `POST /api/v1/rolepermission/permissions` (`storePermission`) – Create a new permission. Body parameters:
    - `name` (string, required) – Permission name
    - `description` (string, optional) – Permission description
    - Returns created permission with 201 status, or existing permission if name already exists
  - `PATCH /api/v1/rolepermission/permissions/{id}` (`updatePermission`) – Update a permission. Body parameters (all optional):
    - `name` (string) – Permission name
    - `description` (string) – Permission description
    - Returns updated permission
  - `DELETE /api/v1/rolepermission/permissions/{id}` (`deletePermission`) – Delete a permission. Returns success message or 404 if not found.
- **Role Permissions:**
  - `GET /api/v1/rolepermission/roles/{roleId}/permissions` (`rolePermissions`) – Get permissions for a specific role. Returns:
    - `role` – Role details
    - `permissions` – All available permissions
    - `role_permissions` – Object mapping permission IDs to CRUD flags: `{permission_id: {can_create, can_read, can_update, can_delete}}`
  - `POST /api/v1/rolepermission/roles/{roleId}/permissions` (`saveRolePermissions`) – Save role permissions. Body parameters:
    - `permissions` (object, required) – Object mapping permission IDs to CRUD flags: `{permission_id: {create: boolean, read: boolean, update: boolean, delete: boolean}}`
    - Updates existing permissions, creates new ones, and removes permissions not in the payload
    - Returns success message
- **User Role Assignment:**
  - `GET /api/v1/rolepermission/users` (`users`) – Get all users with their assigned roles. Returns:
    - `users` – Array of users, each with:
      - `id` – User ID
      - `firstname` – First name
      - `lastname` – Last name
      - `email` – Email address
      - `account_id` – Account ID
      - `roles` – Array of role names assigned to the user
  - `POST /api/v1/rolepermission/users/{userId}/roles` (`assignRole`) – Assign roles to a user. Body parameters:
    - `role_ids` (array, required) – Array of role IDs to assign
    - Replaces all existing roles for the user with the provided roles
    - Automatically updates staff record if user has staff roles
    - Generates unique staff email if needed
    - Returns success message
  - `GET /api/v1/rolepermission/admins` (`admins`) – Get all admin users. Returns array of users with admin role.

**Notes:**
- All endpoints require authentication (`auth:api` middleware)
- Role names and descriptions are stored in lowercase for consistency
- Slugs are auto-generated from role names if not provided, normalized to lowercase with underscores
- Slug uniqueness is enforced (appends `_2`, `_3`, etc. if duplicates exist)
- When assigning roles to users, the system automatically updates the `staff` table if the user has staff roles (excluding parent/student/guest)
- Staff email addresses are auto-generated using firstname + lastname pattern with uniqueness checks
- Role permissions use CRUD flags (can_create, can_read, can_update, can_delete) for fine-grained access control
- All role/permission assignments are wrapped in database transactions for data integrity
- User role assignments completely replace existing roles (not additive)

## RoleSwitcherController
**File:** `app/Http/Controllers/Api/RoleSwitcherController.php`  
**Purpose:** Allow users with multiple roles to view available roles and switch between them. Provides endpoints to retrieve user roles and switch the active role in the session.

**Endpoints:**
- `GET /api/v1/role-switcher` (`index`) – Get available roles for the current authenticated user. Returns:
  - `roles` – Array of role names assigned to the user
  - `auto_redirect` – Boolean flag indicating if user has only one role (true) or multiple roles (false)
  - `route` – Dashboard route for the role (only present when `auto_redirect` is true)
  - `role` – Role name (only present when `auto_redirect` is true)
  - `current_role` – Currently active role from session (only present when `auto_redirect` is false)
  - If user has only one role, returns `auto_redirect: true` with the route to automatically redirect
  - If user has multiple roles, returns `auto_redirect: false` with all available roles
  - Returns 404 if no roles are assigned to the user
- `POST /api/v1/role-switcher/switch` (`switchRole`) – Switch to a specific role using role name/slug in request body. Body parameters:
  - `role` (string, required) – Role name or slug to switch to
  - Validates that the user has the requested role
  - Sets `active_role` in session
  - Returns:
    - `role` – The role name that was switched to
    - `route` – Dashboard route for the role (from `RoleModel::getRouteByNameOrSlug`)
    - `message` – Success message
  - Returns 403 if user does not have the requested role
- `POST /api/v1/role-switcher/switch/{role}` (`switchTo`) – Switch to a specific role using role name/slug in URL parameter. Same behavior as `switchRole` but accepts role as URL parameter instead of request body.

**Notes:**
- All endpoints require authentication (`auth:api` middleware)
- Role matching is case-insensitive and works with both role names and slugs
- Dashboard routes are retrieved from the `roles` table using `RoleModel::getRouteByNameOrSlug()`
- Default route is `/landing_page/guest_dashboard` if no route is found for the role
- Session stores the active role as `active_role` for use by other parts of the application
- The controller loads semester and school year from configuration but doesn't use them in the current implementation (available for future use)

## SchoolCalendarController
**File:** `app/Http/Controllers/Api/SchoolCalendarController.php`  
**Purpose:** Manage school calendar events with CRUD operations and audience-specific views. Supports filtering by school year and semester, and provides formatted calendar views for parents, teachers, and administrators.

**Endpoints:**
- `GET /api/v1/school-calendar` (`index`) – Get calendar events filtered by school year and optional semester. Query parameters:
  - `school_year` (optional) – Filter by school year (defaults to configured school year)
  - `semester` (optional) – Filter by semester
  - Returns array of events with `school_year` and `semester` metadata
- `GET /api/v1/school-calendar/{id}` (`show`) – Get a single calendar event by ID. Returns 404 if not found.
- `POST /api/v1/school-calendar` (`store`) – Create a new calendar event. Body parameters:
  - `title` (string, required) – Event title (minimum 3 characters)
  - `start` (string, required) – Event date in Y-m-d format
  - `description` (string, optional) – Event description
  - `notify_parent` (boolean, optional) – Whether to notify parents (default: false)
  - `notify_teacher` (boolean, optional) – Whether to notify teachers (default: false)
  - `notify_admin` (boolean, optional) – Whether to notify admins (default: false)
  - `no_school` (boolean, optional) – Whether this is a no-school day (default: false)
  - `school_year` (string, optional) – School year (defaults to configured school year)
  - `semester` (string, optional) – Semester (defaults to configured semester)
  - Returns created event with 201 status
- `PATCH /api/v1/school-calendar/{id}` (`update`) – Update an existing calendar event. Body parameters (all optional):
  - `title` (string) – Event title (minimum 3 characters if provided)
  - `start` (string) – Event date in Y-m-d format
  - `description` (string) – Event description
  - `notify_parent` (boolean) – Whether to notify parents
  - `notify_teacher` (boolean) – Whether to notify teachers
  - `notify_admin` (boolean) – Whether to notify admins
  - `no_school` (boolean) – Whether this is a no-school day
  - `school_year` (string) – School year
  - `semester` (string) – Semester
  - Returns updated event
- `DELETE /api/v1/school-calendar/{id}` (`delete`) – Delete a calendar event. Returns success message or 404 if not found.
- `GET /api/v1/school-calendar/view/parent` (`calendarParentView`) – Get calendar events formatted for parent view. Returns FullCalendar-compatible format with:
  - Events filtered by audience visibility rules
  - No-school events highlighted in yellow (#ffc107)
  - Extended properties including notification flags and metadata
- `GET /api/v1/school-calendar/view/teacher` (`calendarTeacherView`) – Get calendar events formatted for teacher view. Returns FullCalendar-compatible format with:
  - Events filtered by audience visibility rules
  - No-school events highlighted in yellow (#ffc107)
  - Staff-only events (visible to teachers/admins but not parents) highlighted in green (#28a745)
  - Extended properties including notification flags and metadata
- `GET /api/v1/school-calendar/view/admin` (`calendarAdminView`) – Get calendar events formatted for admin view. Returns FullCalendar-compatible format with:
  - Events filtered by audience visibility rules
  - Staff-only events highlighted in green (#28a745)
  - Extended properties including notification flags and metadata

**Notes:**
- All endpoints require authentication (`auth:api` middleware)
- Events are filtered by the configured school year by default
- Audience visibility rules:
  - If no notification checkboxes are selected (all `notify_*` = 0), events are visible to everyone
  - If notification checkboxes are selected, events are only visible to the selected audience
  - Events marked as `no_school` are always visible to all audiences
- FullCalendar view endpoints format events with:
  - `id` – Event ID
  - `title` – Event title (with "no school" phrase title-cased if applicable)
  - `start` – Event date (FullCalendar expects 'start' field)
  - `description` – Event description
  - `extendedProps` – Object containing semester, school_year, notification flags, no_school flag, and backgroundColor
- The controller uses the `date` field in the database (not `start_date`)
- School year and semester are loaded from configuration on controller construction

## ScoreCommentController
**File:** `app/Http/Controllers/Api/ScoreCommentController.php`  
**Purpose:** Manage score comments for students across different score types (PTAP, midterm, final). Supports saving comments, updating comments and reviews, and retrieving comments for students or class sections.

**Endpoints:**
- `POST /api/v1/score-comments` (`save`) – Save comments for multiple students. Body parameters:
  - `comments` (object, required) – Object mapping student IDs to score types to comments: `{student_id: {score_type: "comment text"}}`
  - `subject_id` (integer, required) – Subject ID
  - `semester` (string, optional) – Semester (defaults to session semester or configured semester)
  - Score types are normalized to lowercase (ptap, midterm, final)
  - Uses upsert logic: updates existing comments or creates new ones
  - Returns array of saved comments
  - Returns 207 (Partial Content) if some comments failed to save, with `saved` and `errors` arrays
- `POST /api/v1/score-comments/update` (`updateComments`) – Update comments and reviews for multiple students. Body parameters:
  - `comments` (object, required) – Object mapping student IDs to score types to comment text
  - `reviews` (object, optional) – Object mapping student IDs to score types to review text (only processed if user is a reviewer)
  - `semester` (string, optional) – Semester (defaults to configured semester)
  - `school_year` (string, optional) – School year (defaults to configured school year)
  - `teacher_id` (integer, optional) – Teacher ID (defaults to current user ID)
  - Only users with reviewer roles (from `comment_reviewer` config) can update reviews
  - Returns array of updated comments
  - Returns 207 (Partial Content) if some comments failed to update
- `GET /api/v1/score-comments/management` (`viewCommentsMngt`) – Get comments management view data for a class section. Query/body parameters:
  - `class_section_id` (integer, required) – Class section ID (can be in query string, request body, or session)
  - Returns:
    - `students` – Array of students in the class section (id, firstname, lastname, school_id)
    - `comments` – Object mapping student IDs to score types to comment data: `{student_id: {score_type: {comment, comment_review, commented_by, reviewed_by}}}`
    - `semester` – Current semester
    - `school_year` – Current school year
    - `class_section_id` – Class section ID
  - Only loads comments for score types: ptap, midterm, final
  - Stores `class_section_id` in session for future requests
- `GET /api/v1/score-comments/student/{studentId}` (`getByStudent`) – Get comments for a specific student. Query parameters:
  - `subject_id` (integer, optional) – Filter by subject ID
  - `score_type` (string, optional) – Filter by score type
  - Returns comments filtered by current school year and semester
- `PATCH /api/v1/score-comments/{id}` (`update`) – Update a single comment by ID. Body parameters:
  - `comment` (string, required) – Updated comment text
  - Returns updated comment

**Notes:**
- All endpoints require authentication (`auth:api` middleware)
- Comments are scoped to school year and semester
- Score types are normalized to lowercase: 'ptap', 'midterm', 'final'
- Reviewer functionality:
  - Reviewer roles are configured in the `configuration` table with key `comment_reviewer`
  - Value should be a comma-separated list of role names (e.g., "administrator,head_of_department")
  - Only reviewers can update `comment_review` and `reviewed_by` fields
  - Reviewer check is case-insensitive
- The `save()` method uses semester from session if available, otherwise falls back to configured semester
- Comments use upsert logic: if a comment exists for the same student/subject/score_type/semester/school_year combination, it's updated; otherwise, a new record is created
- Empty comment strings are skipped during save operations
- The management endpoint returns students ordered by lastname, then firstname

## ScoreController
**File:** `app/Http/Controllers/Api/ScoreController.php`  
**Purpose:** Manage student scores for teachers and parents. Provides comprehensive score calculation, retrieval, and update functionality for homework, quizzes, projects, midterm exams, final exams, attendance, and semester scores.

**Endpoints:**
- `GET /api/v1/scores` (`index`) – Get student scores for teacher's class section. Returns:
  - `students` – Array of students with all their scores (homework, quiz, project, midterm, final_exam, attendance, ptap, semester_score)
  - `teacher_name` – Name of the teacher
  - `class_section_id` – Class section ID
  - `class_section_name` – Name of the class section
  - `mains_text` – Main teachers assigned to the section
  - `tas_text` – Teaching assistants assigned to the section
  - `active_semester` – Active semester (fall/spring)
  - Automatically refreshes semester scores via SemesterScoreService
  - Students are sorted by lastname, then firstname
  - Returns 404 if teacher has no assigned class
- `GET /api/v1/scores/student/{studentId}` (`getByStudent`) – Get scores for a specific student. Returns semester scores filtered by current school year and semester.
- `GET /api/v1/scores/parent-view` (`viewStudentScore`) – Get student scores for parent view. Query parameters:
  - `school_year` (optional) – Filter by school year (defaults to configured school year)
  - Returns:
    - `organized_scores` – Scores organized by school year, semester, and student ID
    - `school_years` – Available school years from semester_scores
    - `selected_year` – Selected school year
    - `selected_semester` – Selected semester
  - Handles primary, secondary, and tertiary parent user types
  - Returns scores for all students linked to the parent
- `POST /api/v1/scores/update` (`updateScores`) – Generic method to update scores for various types. Body parameters:
  - `table` (string, required) – Table type: 'final_exam', 'midterm_exam', 'quiz', etc.
  - `final_score` (object, required) – Object mapping student IDs to score data: `{student_id: {score: float, quiz_index?: int}}`
  - `class_section_id` (integer, optional) – Class section ID (defaults to session value)
  - Uses upsert logic: updates existing records or creates new ones
  - Automatically triggers semester score recalculation for Spring final exams
  - Returns count of updated students
- `POST /api/v1/scores/update-final-exam` (`updateFinalExamScores`) – Update final exam scores. Same as `updateScores` with table='final_exam'.
- `POST /api/v1/scores/update-midterm` (`updateMidtermScores`) – Update midterm exam scores. Same as `updateScores` with table='midterm_exam'.
- `POST /api/v1/scores/recalculate` (`recalculate`) – Recalculate scores for students. Body parameters:
  - `class_section_id` (integer, optional) – Class section ID (if provided, fetches all students in that section)
  - `students` (array, optional) – Array of student data with student_id, school_id, class_section_id
  - `semester` (string, optional) – Semester (defaults to configured semester)
  - `school_year` (string, optional) – School year (defaults to configured school year)
  - Uses SemesterScoreService to recalculate scores
  - Returns count of processed students

**Notes:**
- All endpoints require authentication (`auth:api` middleware)
- Score calculation formula:
  - PTAP = (homework_avg + quiz_avg + project_avg) / 3
  - Attendance = min((total_days - absences + 1) / total_days * 100, 100)
  - Fall semester: semester_score = 0.2 * PTAP + 0.2 * attendance + 0.6 * midterm
  - Spring semester: semester_score = 0.2 * PTAP + 0.2 * attendance + 0.6 * final_exam
- The controller automatically refreshes semester scores when loading teacher view
- Class section resolution:
  - First tries to find class section for active semester/school year
  - Falls back to any class section assigned to the teacher if not found
- Parent view handles three user types:
  - Primary: uses user_id directly
  - Secondary: looks up parent_id from parents table
  - Tertiary: looks up parent_id from authorized_users table
- Score types supported: homework, quiz, project, midterm, final_exam
- Comments are loaded separately for ptap, midterm, and final score types
- Semester scores are loaded from `semester_scores` table and override calculated values if present
- Total semester days are retrieved from configuration: `total_semester1_days` (Fall) or `total_semester2_days` (Spring)

## ScorePredictorController
**File:** `app/Http/Controllers/Api/ScorePredictorController.php`  
**Purpose:** Generate combined score prediction reports with statistical analysis, trophy winner determination, and risk assessment for students based on fall and spring semester scores.

**Endpoints:**
- `GET /api/v1/score-predictor/combined-report` (`combinedReport`) – Generate combined score prediction report. Query parameters:
  - `school_year` (optional) – Filter by school year (defaults to configured school year)
  - `class_section_id` (optional) – Filter by class section ID
  - Returns:
    - `students` – Array of students with predictions, each containing:
      - `student_id` – Student ID
      - `school_id` – School ID
      - `firstname` – First name
      - `lastname` – Last name
      - `class_section_id` – Class section ID
      - `fall_score` – Fall semester score or 'N/A'
      - `spring_score` – Spring semester score or 'N/A'
      - `final_average` – Final average (fall + spring) / 2, rounded to 1 decimal, or 'N/A'
      - `required_spring_score` – Required spring score to achieve trophy threshold, or 'N/A'
      - `winning_risk` – Trophy winning risk: 'Achieved Trophy', 'Unreachable', 'New student', 'Low', 'Medium', 'High'
      - `required_spring_to_pass` – Required spring score to pass, or 'N/A'
      - `failure_risk` – Failure risk: 'Unlikely to pass', 'New student', 'High', 'Medium', 'Low'
      - `status` – Overall status: 'Passed', 'Failed', 'Undetermined'
    - `school_year` – Selected school year
    - `class_sections` – All available class sections
    - `selected_class_section_id` – Selected class section ID (if filtered)
    - `semester` – Current semester
    - `stats` – Statistical data:
      - `mean` – Mean of spring semester scores
      - `std` – Standard deviation of spring semester scores
      - `target_trophy` – Trophy threshold from configuration
      - `target_pass` – Pass threshold from configuration
  - Students are sorted by final average (descending)
  - Trophy winners are determined per class section using:
    1. All students at/above trophy threshold (minimum 94.0 or configured value)
    2. Minimum trophies: max(ceil(class_size / 4), 3), capped at class size
    3. Tolerance tie-break: students within 0.2 points of last included winner

**Notes:**
- All endpoints require authentication (`auth:api` middleware)
- Trophy threshold: minimum 94.0, or higher if configured in `trophy_score`
- Pass threshold: from `pass_score` configuration (default 60.0)
- Statistical calculations:
  - Uses normal cumulative distribution function (normalCDF) for probability calculations
  - Calculates z-scores based on mean and standard deviation of spring scores
  - Probability thresholds for risk assessment:
    - High risk: probability < 0.33
    - Medium risk: 0.33 <= probability < 0.66
    - Low risk: probability >= 0.66
- Trophy winner determination:
  - Per-class section basis
  - Minimum 3 trophies per class (or 25% of class size, whichever is higher)
  - Tolerance of 0.2 points for tie-breaking
  - Students with final average >= trophy threshold are automatically included
- New students (no fall score) have 'N/A' for calculated values and 'New student' risk labels
- Final average calculation: (fall_score + spring_score) / 2, rounded to 1 decimal
- Required spring scores: calculated to achieve trophy threshold or pass threshold
- The report uses spring semester statistics for probability calculations

## SendSMSController
**File:** `app/Http/Controllers/Api/SendSMSController.php`  
**Purpose:** Trigger SMS blasts.

- `POST /api/v1/sms/send` – Validates `message` and recipients (phone numbers or parent IDs), queues the SMS, and returns the send summary.

## SessionTimeoutController
**File:** `app/Http/Controllers/Api/SessionTimeoutController.php`  
**Purpose:** Manage session timeout tracking and provide keep-alive functionality for the SPA to prevent unexpected logouts due to inactivity.

**Endpoints:**
- `GET /api/v1/session/timeout-config` (`getTimeoutConfig`) – Public endpoint that returns session timeout configuration including timeout duration, warning threshold, check interval, and related URLs (logout, keep-alive, check). Response includes `success`, `timeout`, `warning_time`, `check_interval`, `logout_url`, `keep_alive_url`, and `check_url`.
- `GET /api/v1/session/checkTimeout` (`checkTimeout`) – Requires auth. Checks the current session's last activity timestamp against the configured timeout duration. Returns `status` (`active`, `warning`, or `expired`) and `time_remaining` in seconds. If session has expired, returns `status: 'expired'` with `redirect` URL and `message`.
- `POST /api/v1/session/pingActivity` (`pingActivity`) – Requires auth. Updates the session's `last_activity` timestamp to keep the session alive. Only updates if the session is still valid (not already expired). Returns `status: 'active'` and `time_remaining` set to the full timeout duration. If session has already expired, returns the same expired response as `checkTimeout`.

**Session Management:**
- Tracks user activity via `last_activity` session key
- Automatically expires sessions that exceed `SessionTimeout::TIMEOUT_DURATION` (default: 1200 seconds / 20 minutes)
- Warns users when activity exceeds `SessionTimeout::WARNING_THRESHOLD` (default: 900 seconds / 15 minutes)
- Frontend should check session status at intervals defined by `SessionTimeout::CHECK_INTERVAL` (default: 60 seconds / 1 minute)


## SettingsController
**File:** `app/Http/Controllers/Api/SettingsController.php`  
**Purpose:** Read/update global settings.

- `GET /api/v1/settings` – Returns grouped configuration values.
- `PATCH /api/v1/settings` – Accepts a key/value object and persists changes after validation.

## SlipPrinterController
**File:** `app/Http/Controllers/Api/SlipPrinterController.php`  
**Purpose:** Generate printable late slips as PDFs, manage slip previews, and handle reprinting of previously logged slips.

**Endpoints:**
- `POST /api/v1/slips/print` (`print`) – Requires auth. Generates and returns a PDF late slip. Accepts POST data with fields: `school_year` (optional, defaults to configured year), `student_name` (required), `date` (optional, defaults to current date in m/d/Y format), `time_in` (optional, defaults to current time in h:i A format), `grade`, `reason`, `admin_name` (optional, auto-filled from logged-in user). Automatically logs the slip print to the database before generating the PDF. Returns PDF binary with appropriate headers for inline display or download. Supports optional query parameters: `paper` (card, card-portrait, receipt80, receipt58), `font_pt`, `line_h`, `rows`, `height_mm` for PDF customization.
- `GET /api/v1/slips/preview` (`preview`) – Requires auth. Returns a list of recent late slip logs with optional filtering by `school_year` and `semester` query parameters. Returns paginated list (up to 50 records) with formatted date/time fields. Each record includes: `id`, `school_year`, `semester`, `student_name`, `date`, `time_in`, `grade`, `reason`, `admin_name`.
- `POST /api/v1/slips/preview` (`preview`) – Requires auth. Returns a JSON preview of slip text formatted for printer output. Accepts the same fields as the print endpoint. Returns `ok`, `text` (formatted slip text), and `width` (characters per line) for preview purposes.
- `POST /api/v1/slips/reprint/{id}` (`reprint`) – Requires auth. Reprints a previously logged late slip by its log ID. Retrieves the slip data from the database, updates the admin name to the current logged-in user, generates a new PDF, and logs the reprint for audit purposes. Returns PDF binary response.

**Features:**
- PDF generation using DomPDF with customizable paper sizes (card, receipt formats)
- Automatic logging of all slip prints and reprints for audit trail
- ESC/POS printer support (network, USB, Windows) via Mike42\Escpos library (configured via environment variables)
- Automatic admin name resolution from logged-in user's database record
- Flexible date/time parsing and formatting
- Configurable printer settings via environment: `PRINTER_MODE`, `PRINTER_HOST`, `PRINTER_PORT`, `PRINTER_USB_VID`, `PRINTER_USB_PID`, `PRINTER_WINDOWS_NAME`, `PRINTER_CHARS_PER_LINE`, `PRINTER_FEED_LINES`

## StaffController
**File:** `app/Http/Controllers/Api/StaffController.php`  
**Purpose:** CRUD for staff/teacher records with class assignment verification and issue tracking.

**Endpoints:**
- `GET /api/v1/staff` (`index`) – Requires auth. Returns paginated list of staff members excluding roles: student, parent, guest, inactive. Optional query parameters: `page`, `per_page`, `role` (filter by role). Each staff member includes: `school_id`, `class_section` (for teachers/TAs), `verification_issue` (boolean flag for teachers/TAs without class assignments). Response includes `issues_count` (total count of teachers/TAs without class assignments), `semester`, and `school_year` metadata.
- `GET /api/v1/staff/{id}` (`show`) – Requires auth. Returns a single staff member by ID with `school_id` attached.
- `POST /api/v1/staff` (`store`) – Requires auth. Creates a new staff member. Accepts fields: `firstname`, `lastname`, `email`, `phone`, `role_name` (automatically sets `active_role` to lowercase version), `school_year` (optional, defaults to configured year), `status` (optional, defaults to 'Active'). Automatically sets `created_at` and `updated_at` timestamps.
- `PATCH /api/v1/staff/{id}` (`update`) – Requires auth. Updates a staff member. Accepts any of: `firstname`, `lastname`, `email`, `phone`, `role_name` (updates `active_role` if provided), `school_year`, `status`. Only updates fields that are provided and non-empty. Automatically updates `updated_at` timestamp.
- `DELETE /api/v1/staff/{id}` (`destroy`) – Requires auth. Deletes a staff member by ID.

**Features:**
- Automatic class assignment verification for teachers and teacher assistants
- Issue tracking for teachers/TAs without class assignments
- School ID resolution from user records
- Role-based filtering and exclusion

## StatsController
**File:** `app/Http/Controllers/Api/StatsController.php`  
**Purpose:** Aggregate metrics for dashboards (attendance, enrollment, finances).

- Endpoints like `GET /api/v1/stats/attendance|students|financial` query reporting tables and return summary numbers + breakdowns for the admin UI.

## StudentController
**File:** `app/Http/Controllers/Api/StudentController.php`  
**Purpose:** Full REST API for managing students, class assignments, health information, and automated distribution.

**Endpoints:**
- `GET /api/v1/students` (`index`) – Requires auth. Supports pagination and filters (`parent_id`, `class_id`). Augments each record with the student's current class info. Returns paginated list of students.
- `GET /api/v1/students/{id}` (`show`) – Requires auth. Returns detailed student profile plus current class section information.
- `POST /api/v1/students` (`store`) – Requires auth. Creates a new student. Validates demographic fields (firstname, lastname, dob, gender, parent_id) and automatically stamps school year, semester, and registration date.
- `PATCH /api/v1/students/{id}` (`update`) – Requires auth. Updates student information. Accepts fields: `school_id`, `firstname`, `lastname`, `dob` (automatically calculates age), `gender`, `registration_grade`, `photo_consent`, `parent_id`, `registration_date`, `tuition_paid`, `year_of_registration`, `school_year`, `rfid_tag`, `semester`, `is_new`. Also supports health information: `medical_conditions` (comma/semicolon/newline separated list), `allergies` (comma/semicolon/newline separated list), `medical_touched`, `allergies_touched` (flags to indicate user interaction). Health lists are normalized, deduplicated, and synced with related tables. Only updates fields that are provided and non-empty.
- `DELETE /api/v1/students/{id}` (`destroy`) – Requires auth. Removes the student record.
- `POST /api/v1/students/assign-class` (`assignClassStudent`) – Requires auth. Assigns a student to a class section. Accepts `student_id` and `class_section_id`. Updates `student_class` table, enrollment records, attendance data/records, and all score-related tables (homework, quiz, project, participation, midterm_exam, final_exam, final_score, semester_scores) for the current semester/year. Returns assignment details including attendance and score update statistics.
- `POST /api/v1/students/auto-distribute` (`autoDistributeSections`) – Requires auth. Automatically distributes students from promotion queue into lettered sections for a class. Accepts `class_id` (or `class_section_id` to derive class_id), `students_per_section`, and optional `school_year`. Balances male/female distribution across sections. Only considers students with enrollment status 'payment pending' or 'enrolled'. Updates promotion queue and student_class records. Returns summary with distribution details per section (total, male, female counts).
- `GET /api/v1/students/promotion-totals` (`promotionTotalsApi`) – Requires auth. Returns promotion totals per base class (KG, 1-9, Youth) for the selected school year. Optional query parameter: `school_year` (defaults to configured year). Only counts students with enrollment status 'payment pending' or 'enrolled'. Returns array with class_id, class_section_id, class_section_name, and total count per class.

**Features:**
- Comprehensive student data management with health information (allergies, medical conditions)
- Automatic class assignment with cascading updates to attendance and score tables
- Gender-balanced automated section distribution
- Promotion queue integration
- Health list normalization (removes duplicates, filters placeholders like "none", "n/a")
- Transaction-safe operations with rollback on errors

## SupplierController
**File:** `app/Http/Controllers/Api/SupplierController.php`  
**Purpose:** CRUD for supplier/vendor records used by purchase orders and inventory management.

**Endpoints:**
- `GET /api/v1/suppliers` (`index`) – Requires auth. Returns paginated list of suppliers. Optional query parameters: `page`, `per_page`, `q` (search keyword). Search filters by name, email, or phone. Results ordered by name ascending.
- `GET /api/v1/suppliers/{id}` (`show`) – Requires auth. Returns a single supplier by ID.
- `POST /api/v1/suppliers` (`store`) – Requires auth. Creates a new supplier. Accepts fields: `name` (required), `email` (optional, validated as email), `phone` (optional), `address` (optional), `notes` (optional). Returns created supplier record.
- `PATCH /api/v1/suppliers/{id}` (`update`) – Requires auth. Updates a supplier. Accepts any of: `name`, `email`, `phone`, `address`, `notes`. Only updates fields that are provided. Returns updated supplier record.
- `DELETE /api/v1/suppliers/{id}` (`destroy`) – Requires auth. Deletes a supplier by ID.

**Features:**
- Search functionality across name, email, and phone fields
- Standard RESTful CRUD operations
- Validation for required fields and email format


## SupportController
**File:** `app/Http/Controllers/Api/SupportController.php`  
**Purpose:** Ticket management for internal support.

- `GET /api/v1/support/tickets` / `{id}` – List or fetch support tickets.
- `POST /api/v1/support/tickets` / `PATCH /api/v1/support/tickets/{id}` – Create/update ticket records with status notes.

## TeacherController
**File:** `app/Http/Controllers/Api/TeacherController.php`  
**Purpose:** Manage teacher records, class assignments, class view data, and absence/vacation requests.

**Endpoints:**
- `GET /api/v1/teachers` (`index`) – Requires auth. Returns paginated list of teachers and teacher assistants. Optional query parameters: `page`, `per_page`. Results include class assignments for the current school year and semester.
- `GET /api/v1/teachers/{id}` (`show`) – Requires auth. Returns detailed information about a specific teacher including their class assignments for the current term.
- `GET /api/v1/teachers/{id}/classes` (`getClasses`) – Requires auth. Returns the class sections currently assigned to the teacher for the current school year and semester.
- `GET /api/v1/teachers/class-view` (`getClassView`) – Requires auth. Returns comprehensive class view data for the logged-in teacher including:
  - Teacher name and role
  - All assigned classes (as main teacher or TA)
  - Students grouped by class section with medical conditions and allergies
  - Assigned staff names (main teachers and TAs) per class section
- `GET /api/v1/teachers/class-assignments` (`getTeacherClassAssignments`) – Requires auth. Returns teacher class assignment data for administration. Optional query parameter: `schoolYear` or `school_year` to filter by specific year. Returns:
  - List of all teachers and TAs
  - Their main and TA assignments
  - Available class sections
- `POST /api/v1/teachers/class-assignments/assign` (`assignClassTeacher`) – Requires auth. Assigns a teacher to a class. Body requires:
  - `teacher_id` (required) – ID of the teacher to assign
  - `class_section_id` (required) – ID of the class section
  - `teacher_role` (optional) – Role of the teacher (if not provided, will be determined from user roles)
  - Optional: `semester`, `school_year` (defaults to configured values)
  - Returns success/error status with message
- `DELETE /api/v1/teachers/class-assignments` (`deleteAssignment`) – Requires auth. Removes a teacher class assignment. Body requires:
  - `teacher_id` (required)
  - `class_section_id` (required)
  - `position` (required) – Either "main" or "ta"
  - Optional: `semester`, `school_year` (defaults to configured values)
- `GET /api/v1/teachers/absence-form` (`getAbsenceForm`) – Requires auth. Returns absence form data for the logged-in teacher including:
  - Teacher name
  - Current semester and school year
  - Existing absence records for the current term
  - Available dates (future Sundays within the school year range)
- `POST /api/v1/teachers/absence` (`submitAbsence`) – Requires auth. Submits an absence/vacation request. Body requires:
  - `dates` (required) – Array of date strings in Y-m-d format (must be valid Sundays)
  - `reason` (required) – Text description of the absence reason
  - `reason_type` (optional) – Category of the reason
  - Validates dates against allowed Sundays list, creates/updates staff attendance records, and sends notification email to principal. Returns count of saved dates.

## TestDBController
**File:** `app/Http/Controllers/Api/TestDBController.php`  
**Purpose:** Simple health endpoint for confirming DB connectivity/migrations.

- `GET /api/v1/test-db` – Returns the status of DB checks used in diagnostics.

## TimeController
**File:** `app/Http/Controllers/Api/TimeController.php`  
**Purpose:** Share the server’s current timestamp/timezone for client sync logic.

- `GET /api/v1/time` – Responds with ISO timestamp and timezone metadata.

## UiController
**File:** `app/Http/Controllers/Api/UiController.php`  
**Purpose:** Store and return UI palette preferences that drive the SPA theme.

**Endpoints:**
- `GET /api/v1/ui/style` (`style`) – Requires auth. Returns the user's current accent/menu colors plus the available palettes defined in config. Can also accept query parameters to update style preferences:
  - `accent` (optional) – Accent color palette name from available palettes
  - `menu` (optional) – Menu color palette name from available palettes, or `custom` for custom colors
  - `menu_bg` (optional) – Custom menu background color in hex format (e.g., `#0f172a` or `0f172a`)
  - `menu_text` (optional) – Custom menu text color in hex format (e.g., `#ffffff` or `ffffff`)
  - `menu_mode` (optional) – Menu mode: `light`, `dark`, or `auto` (defaults to auto-detect based on background luminance)
  - When query parameters are provided, updates the style preferences and returns the updated values. When no parameters are provided, returns current preferences.
- `POST /api/v1/ui/style` (`updateStyle`) – Requires auth. Accepts JSON body with style preferences:
  - `accent` (optional) – Accent color palette name
  - `menu` (optional) – Menu color palette name or `custom`
  - `menu_bg` (optional) – Custom menu background color in hex format
  - `menu_text` (optional) – Custom menu text color in hex format
  - `menu_mode` (optional) – Menu mode: `light`, `dark`, or `auto`
  - Persists the preferences in the session and returns the updated values.

**Features:**
- Supports both predefined palettes and custom hex colors
- Automatically detects light/dark mode based on background color luminance when `menu_mode` is `auto`
- Normalizes hex color formats (supports both 3-digit and 6-digit hex codes)
- All preferences are stored in session and persist across requests

## UserController
**File:** `app/Http/Controllers/Api/UserController.php`  
**Purpose:** Manage user accounts, profile data, login activity, password reset/activation flows, and role management.

**Endpoints:**
- `GET /api/v1/users` (`index`) – Auth required. Returns users with optional `sort=id|firstname|lastname|email|role` and `order` query params plus the role catalog for dropdowns.
- `GET /api/v1/users/with-roles` (`listWithRoles`) – Auth required. Expands every user with their roles, guardian type, and whether they exist as a secondary parent in legacy tables.
- `POST /api/v1/users` (`store`) – Auth required. Creates a user with PBKDF2 password hashing and immediately assigns the provided `role_id`. Body requires: `firstname`, `lastname`, `email`, `password`, `cellphone`, `address_street`, `city`, `state`, `zip`, `accept_school_policy`, `role_id`.
- `PATCH /api/v1/users/{id}` (`updateUser`) – Auth required. Updates the account/profile metadata fields used by the admin UI (status flags, address, contact info, tokens, etc.). Accepts partial updates for any user field.
- `DELETE /api/v1/users/{id}` (`destroy`) – Auth required. Removes the user and associated `user_roles` rows.
- `GET /api/v1/users/login-activity` (`loginActivity`) – Auth required. Paginated login history with metadata and pager info. Query params: `per_page` (default 25), `page` (default 1).
- `POST /api/v1/users/select-role` (`selectRole`) – Auth required. Selects and updates the logged-in user's role in the database. Body requires: `role` (role name or slug). Returns the role and dashboard route.
- `DELETE /api/v1/users/roles/{roleId}` (`deleteRole`) – Auth required. Deletes a role and reassigns all users with that role to the "Guest" role. Users are set to Inactive status.
- `POST /api/v1/users/password/forgot` (`requestPasswordReset`) – Public. Throttles by IP (max 3 attempts per 24 hours), verifies account status, creates a one-hour reset token, and emails the link. Body requires: `email`.
- `GET /api/v1/users/password/reset/{token}` (`validateResetToken`) – Public. Validates whether the token is still usable and returns the associated email.
- `POST /api/v1/users/password/reset` (`completePasswordReset`) – Public. Consumes the token, hashes the new password, clears lockouts, and deletes the reset entry. Body requires: `token`, `password`, `password_confirmation`. Password must meet complexity requirements.
- `GET /api/v1/user/confirm/{token}` (`confirm`) – Public. Validates the registration token so the UI can prompt for an initial password. Returns user_id and email if valid.
- `POST /api/v1/user/set-password` (`setPassword`) – Public. Finalizes onboarding by setting the password, activating the user, and clearing the token. Body requires: `user_id`, `token`, `password`, `password_confirm`. Generates account_id if not present.
- `GET /api/v1/user/profile` (`profile`) – Auth required. Returns the signed-in user's details with any attached roles.
- `POST /api/v1/user/profile-auth` (`profileAuth`) – Public. PBKDF2 credential check for legacy clients that need a session+JWT payload. Body requires: `email`, `password`.
- `PATCH /api/v1/user/profile` (`updateProfile`) – Auth required. Updates contact info and optionally email/password after verifying the current password. Body can include: `firstname`, `lastname`, `cellphone`, `address_street`, `apt`, `city`, `state`, `zip`, `gender`, `email` (requires `current_password`), `password` (requires `current_password`).

## WhatsappController
**File:** `app/Http/Controllers/Api/WhatsappController.php`  
**Purpose:** Manage WhatsApp invite links per class section, send invites to parents, and track parent participation.

### Endpoints:

- `GET /api/v1/whatsapp/` (`index`) – Get initial data for WhatsApp management page. Returns sections, parents, links by section, school year, and semester.

- `GET /api/v1/whatsapp/links` (`links`) – Lists links for the active school year/semester sorted by class section.

- `POST /api/v1/whatsapp/links` (`saveLink`) – Upserts the invite link for a class section. Body requires:
  - `class_section_id` (integer, required)
  - `invite_link` (string, required)
  - `active` (integer, optional: 0 or 1)
  - `class_section_name` (string, optional)

- `POST /api/v1/whatsapp/send-invites` (`sendInvites`) – Send WhatsApp invites in three modes. Body requires:
  - `mode` (string, required: 'parents' | 'class' | 'all')
  - `parent_ids` (array of integers, required if mode='parents')
  - `class_section_id` (integer, required if mode='class')
  
  Modes:
  - `parents`: Send invites to selected parents (requires `parent_ids` array)
  - `class`: Send invites to all parents in a specific class (requires `class_section_id`)
  - `all`: Send invites to all parents across all classes
  
  Triggers `whatsapp_invites.send` event for each recipient group with parent info, sections, links, teachers, and email addresses (TO and CC).

- `GET /api/v1/whatsapp/parent-contacts` (`parentContacts`) – Get a flat list of all parent contacts (primary and secondary parents) for the current term. Optional query parameters:
  - `school_year` (string)
  - `semester` (string)
  
  Returns contacts sorted by last name, first name, and type (Primary before Second).

- `GET /api/v1/whatsapp/parent-contacts-by-class` (`parentContactsByClass`) – Get parent contacts grouped by class section. Optional query parameters:
  - `school_year` (string)
  - `semester` (string)
  
  Returns class sections with associated parents (primary and secondary), teachers (main and assistants), and membership flags indicating if parents have joined the WhatsApp groups.

- `POST /api/v1/whatsapp/memberships` (`updateMembership`) – Update WhatsApp group membership flags for a class/parent(s). Body requires:
  - `class_section_id` (integer, required)
  - `primary_id` (integer, optional)
  - `second_id` (integer, optional)
  - `primary_member` (string/integer, optional: '1' or 'on' if checked)
  - `second_member` (string/integer, optional: '1' or 'on' if checked)
  - `school_year` (string, optional)
  - `semester` (string, optional)
  
  Updates membership status for primary and/or secondary parents in a class section. Uses `subject_type` ('primary' or 'second') and `subject_id` to track membership.

## GradingController
**File:** `app/Http/Controllers/Api/GradingController.php`  
**Purpose:** Unified interface for CRUD operations across scores (homework, quizzes, projects, midterms, finals, semester tests, comments) and comprehensive grading management.

**Endpoints:**
- `GET /api/v1/grading/{type}/{class_section_id?}/{student_id?}` (`show`) – Retrieves scores for a specific type. `type` must be one of `homework|quiz|project|midterm|final|test|comments`. Optional `class_section_id` and `student_id` parameters. Filters by student, semester, and school year. Returns student information, scores array, type, class section ID, semester, and school year.
- `POST /api/v1/grading` (`update`) – Updates scores for various types. Body requires:
  - `type` (required) – One of: `homework`, `quiz`, `project`, `midterm`, `final`, `test`, `comments`
  - `student_id` (required for midterm/final/test/comments)
  - `class_section_id` (required for midterm/final/test)
  - For `homework|quiz|project`: `score_ids` (array), `scores` (array), `comments` (optional array)
  - For `midterm|final|test`: `score` (numeric)
  - For `comments`: `comment` (string)
  
  After updating scores, automatically triggers semester score recalculation for all students in the class section via `SemesterScoreService`.
- `GET /api/v1/grading` (`grading`) – Returns comprehensive grading data for all students grouped by class sections. Returns:
  - `grades` – Array grouped by class_id, containing class sections with `class_section_id` and `class_section_name`
  - `students_by_section` – Array keyed by section_id, containing students with their PTAP scores and semester scores
  - `semester` – Current semester
  - `school_year` – Current school year
  
  Uses dual-join strategy to match semester_scores by both business ID (class_section_id) and primary key (id) for compatibility.
- `GET /api/v1/grading/scores-comments` (`getScoreComment`) – Retrieves all scores and comments for all students in the current semester and school year. Returns a comprehensive dataset including:
  - Student basic information (school_id, firstname, lastname, class_name)
  - Attendance data (score, absences, total_days)
  - All score types: `final_exam`, `homework`, `midterm`, `project`, `quiz`, `semester_score`
  - Comments array for each student
  - Semester scores with all averages (homework_avg, quiz_avg, project_avg, midterm_exam_score, final_exam_score, attendance_score, participation_score, ptap_score, test_avg, semester_score)

## HealthController
**File:** `app/Http/Controllers/Api/HealthController.php`  
**Purpose:** Operational health check combining filesystem permissions and database schema sanity.

- `GET /api/v1/health` (`index`) – Public endpoint (no auth required) that performs health checks on:
  - **Filesystem paths**: Checks if upload directories exist and are writable:
    - `uploads` base directory
    - `uploads/reimbursements`
    - `uploads/receipts`
    - `uploads/checks`
  - **Database schema**: Verifies existence of critical tables and required columns:
    - `user_preferences` table and `timezone` column
    - `settings` table and `timezone` column
    - `migrations` table
  
  Returns JSON payload with:
  - `ok` (boolean) – Overall health status
  - `paths` (array) – Status of each filesystem path with `label`, `path`, `exists`, `writable`
  - `database` (object) – Database schema checks with table/column existence flags
  - `write_path` (string) – Base storage path
  - `timestamp` (string) – ISO 8601 timestamp of the check
  
  HTTP Status Codes:
  - `200 OK` – All checks passed
  - `503 Service Unavailable` – One or more checks failed

## HomeworkController
**File:** `app/Http/Controllers/Api/HomeworkController.php`  
**Purpose:** CRUD for per-student homework scores scoped by class section, with bulk update and column management capabilities.

**Endpoints:**
- `GET /api/v1/homework` (`index`) – Paginated list with optional `class_section_id` query parameter. Filters by current semester and school year.
- `GET /api/v1/homework/student/{id}` (`getByStudent`) – Returns all homework entries for a specific student, filtered by current semester and school year.
- `GET /api/v1/homework/class-section` (`getByClassSection`) – Retrieves comprehensive homework data for a class section. Query param `class_section_id` (required). Returns:
  - `homework_scores` – Scores grouped by student ID
  - `students` – List of students in the class section
  - `homework_headers` – Array of unique homework_index values
  - `semester`, `school_year`, `class_section_id`
  - `has_homework_cols` – Boolean indicating if any homework columns exist
- `GET /api/v1/homework/students-with-scores` (`getStudentsWithScores`) – Returns students with their homework scores. Query param `class_section_id` (required). Returns students array with `student_id`, `firstname`, `lastname`, and `scores` object keyed by homework_index.
- `POST /api/v1/homework` (`create`) – Creates a single homework entry. Body requires:
  - `student_id` (integer, required)
  - `class_section_id` (integer, required)
  - `homework_index` (integer, required)
  - `score` (numeric, optional)
  - `comment` (string, optional)
- `POST /api/v1/homework/update-scores` (`updateScores`) – Bulk update homework scores for multiple students. Body requires:
  - `scores` (object, required) – Nested object: `{student_id: {homework_index: score}}`
  - `class_section_id` (integer, required)
  
  Behavior:
  - Updates existing scores if record exists
  - Creates new records if they don't exist
  - Deletes records if score is blank/null
  - Automatically triggers semester score recalculation for all students in the class section
- `POST /api/v1/homework/add-column` (`addNextColumn`) – Adds a new homework column (index) for all students in a class section. Body requires:
  - `class_section_id` (integer, required)
  
  Returns:
  - `homework_index` – The new homework index number
  - `new_homework_id` – ID of the first inserted record
  - `students_processed` – Number of students for whom the column was added
- `PATCH /api/v1/homework/{id}` (`update`) – Updates a single homework entry. Allows updating `score` and/or `comment` fields.

## HomeworkTrackingController
**File:** `app/Http/Controllers/Api/HomeworkTrackingController.php`  
**Purpose:** Build a Sunday-based schedule of homework indices for dashboards with comprehensive tracking data.

- `GET /api/v1/homework/tracking` (`index`) – Returns comprehensive homework tracking data. Query parameters:
  - `start_date` (optional, default: '2025-09-21') – Start date for the tracking period
  - `end_date` (optional, default: '2026-01-18') – End date for the tracking period
  - `page` (optional, default: 1) – Page number for paginated teacher/section results (8 per page)
  
  Returns:
  - `semester` – Current semester
  - `school_year` – Current school year
  - `sundays` – Array of all Sunday dates (Y-m-d format) within the date range, starting from the first Sunday on/after start_date
  - `event_days` – Object mapping dates (Y-m-d) to boolean true for no-school days from calendar events
  - `date_to_index` – Object mapping Sunday dates to homework_index numbers (null for no-school Sundays)
  - `teachers` – Paginated array of class sections with:
    - `class_section_id` – Class section ID
    - `class_id` – Class ID (for sorting: KG=13, Grades 1-11, Youth=12)
    - `class_section_name` – Name of the class section
    - `teachers` – Array of main teacher names
    - `tas` – Array of TA names
  - `has_homework` – Nested object: `{class_section_id: {homework_index: true}}` indicating which sections have homework for which indices
  - `hw_entered_at` – Nested object: `{class_section_id: {homework_index: 'Y-m-d'}}` with first creation date per homework index
  - `has_homework_by_date` – Nested object: `{class_section_id: {sunday_date: true}}` mapping homework to the nearest prior non-no-school Sunday
  - `hw_entered_at_by_date` – Nested object: `{class_section_id: {sunday_date: 'Y-m-d'}}` with earliest entry date per Sunday
  - `pagination` – Pagination metadata:
    - `page` – Current page number
    - `total_pages` – Total number of pages
    - `per_page` – Items per page (8)
    - `total_rows` – Total number of class sections
  
  The endpoint calculates Sunday-based homework indices, skips no-school days, aggregates homework data by both index and date, and provides teacher/TA information for each class section. Results are sorted by grade order (KG first, then Grades 1-11, then Youth).

## InventoryController
**File:** `app/Http/Controllers/Api/InventoryController.php`  
**Purpose:** Comprehensive inventory management system for tracking items, categories, stock movements, classroom audits, book distribution, and inventory summaries.

**Item Management:**
- `GET /api/v1/inventory` (`index`) – List inventory items filtered by `type` (classroom/book/office/kitchen), `school_year`, and `semester`. Returns items with categories, condition options, school years, and user names for updated_by fields.
- `GET /api/v1/inventory/create` (`create`) – Get form data for creating a new item, including categories and condition options for the specified type.
- `GET /api/v1/inventory/{id}` (`show`) – Retrieve a single inventory item with its categories and condition options.
- `POST /api/v1/inventory` (`store`) – Create a new inventory item. Automatically records initial stock movement if quantity > 0. Body requires `name`, `type`, optional `category_id`, `quantity`, `description`, `unit`, `sku`, `notes`. For books: `isbn`, `edition`. For classroom: `condition`.
- `PATCH /api/v1/inventory/{id}` (`update`) – Update an inventory item. Type is locked to the original item type. Updates `updated_by` automatically.
- `DELETE /api/v1/inventory/{id}` (`delete`) – Remove an inventory item.

**Category Management:**
- `POST /api/v1/inventory/categories` (`saveCategory`) – Create or update a category. Body requires `type`, `name`, optional `description`. For book categories: `grade_min`, `grade_max` (validated: min ≤ max, both ≤ 13). Prevents duplicate (type, name) combinations. Returns conflict error if duplicate exists.

**Classroom Audit:**
- `GET /api/v1/inventory/classroom/{id}/audit` (`auditClassroomForm`) – Get audit form data for a classroom item, including current good/needs_repair/need_replace/cannot_find quantities.
- `POST /api/v1/inventory/classroom/{id}/audit` (`auditClassroomStore`) – Save audit data. Calculates deltas for loss/missing quantities and records stock movements (out for increases, in for decreases). Updates good_qty as on-hand minus needs_repair. Body requires `needs_repair_qty`, `need_replace_qty`, `cannot_find_qty`.

**Summary & Reports:**
- `GET /api/v1/inventory/summary/{type?}` (`summary`) – Get inventory summary for a type (default: classroom). Returns items with aggregated received/issued quantities from movements, filtered by optional `school_year` query param.
- `GET /api/v1/inventory/summary-all` (`summaryAll`) – Comprehensive summary across all types or a selected type. Query params: `school_year` (default: current), `type` (all/book/classroom/office/kitchen). Returns rows with opening, received, distributed, other_out, adjust_net, ending, onhand, variance calculations. Includes totals row.

**Stock Adjustments:**
- `GET /api/v1/inventory/{id}/adjust` (`adjustForm`) – Get form data for adjusting stock.
- `POST /api/v1/inventory/{id}/adjust` (`adjustStore`) – Adjust inventory quantity. Body requires `mode` (in/out/adjust), `quantity` (> 0), optional `reason`, `note`. Records movement and prevents negative stock for out/adjust modes.

**Book Distribution (Teacher):**
- `GET /api/v1/inventory/books/distribute` (`teacherDistributeForm`) – Get book distribution form for teachers. Requires authentication and teacher/TA role. Filters books by category grade range matching the selected class section's grade level. Groups books by category with grade range labels. Returns students in the class, prior distribution history for selected book, and on-hand quantity. Query params: `class_section_id` (optional if teacher has only one class), `item_id` (optional, for showing history).
- `POST /api/v1/inventory/books/distribute` (`teacherDistributeStore`) – Distribute books to students. Body requires `item_id`, `class_section_id`, `student_ids` (array), optional `note`. Validates students belong to teacher's class, checks stock availability, prevents duplicate distributions (only assigns to students who don't already have the book this school year). Records one movement per student with type 'distribution'. Returns count of successfully distributed books.

**Movement Management:**
- `GET /api/v1/inventory/movements` (`movementsIndex`) – List all inventory movements with enriched data (item name, performed_by name, teacher name, student name, class section name). Query params: `school_year`, `semester` for filtering. Ordered by ID descending.
- `GET /api/v1/inventory/movements/create` (`movementsCreate`) – Get form data for creating a movement, including movement types, semesters, items, class sections, teachers, and students.
- `GET /api/v1/inventory/movements/{id}` (`movementsEdit`) – Get a single movement with hydrated display names.
- `POST /api/v1/inventory/movements` (`movementsStore`) – Create a movement. Body requires `item_id`, `qty_change`, `movement_type` (initial/in/out/adjust/distribution), optional `reason`, `note`, `semester`, `school_year`, `teacher_id`, `student_id`, `class_section_id`. Automatically sets `performed_by` from session.
- `PATCH /api/v1/inventory/movements/{id}` (`movementsUpdate`) – Update a movement. Allows updating all fields except `item_id` (immutable after creation).
- `DELETE /api/v1/inventory/movements/{id}` (`movementsDelete`) – Delete a movement.
- `POST /api/v1/inventory/movements/bulk-delete` (`movementsBulkDelete`) – Bulk delete movements. Body requires `ids` (array of movement IDs).

**Movement Types:** `initial`, `in`, `out`, `adjust`, `distribution`

**Inventory Types:** `classroom`, `book`, `office`, `kitchen`

**Key Features:**
- Automatic quantity recalculation from movement history
- Legacy item support: ensures initial movements exist for items without movement history
- School year opening balance tracking: ensures initial movement exists for each school year
- Classroom-specific: good_qty automatically calculated as on-hand minus needs_repair_qty
- Book distribution: grade range filtering, prevents duplicate distributions, stock validation
- Comprehensive audit trail with user tracking (updated_by, performed_by)

## InvoiceController
**File:** `app/Http/Controllers/Api/InvoiceController.php`  
**Purpose:** Comprehensive invoice management including generation, calculation, PDF export, and parent invoice tracking.

**Endpoints:**
- `GET /api/v1/invoices` (`index`) – Paginated list of invoices with optional filters: `parent_id`, `status`, `school_year`, `page`, `per_page`. Returns invoices with pagination metadata.
- `GET /api/v1/invoices/{id}` (`show`) – Returns a single invoice by ID or `404` if not found.
- `GET /api/v1/invoices/management-data` (`managementData`) – Composite data for invoice management view. Returns:
  - `schoolYears` – Available school years from invoices
  - `invoices` – Array of parent invoice summaries with:
    - `parent_name`, `parent_id`
    - `enrolledKids` – Array of enrolled students with name, grade, tuition_fee
    - `withdrawnKids` – Array of withdrawn students
    - `invoice_amount`, `refund_amount`, `invoice_date`, `last_updated`, `invoice_id`
  - Query params: `schoolYear` or `year` (defaults to configured year)
- `GET /api/v1/invoices/unpaid` (`unpaidInvoices`) – Returns all unpaid invoices ordered by due date ascending.
- `GET /api/v1/invoices/parent/{parentId}` (`getByParent`) – Returns all invoices for a specific parent. Optional query param: `school_year` (defaults to configured year).
- `POST /api/v1/invoices/generate` (`generateInvoice`) – Generates or updates invoice for a parent. Body requires `parent_id`. Calculates tuition fees based on enrolled/withdrawn students, applies discounts, includes event charges, and handles refunds. Creates new invoice if none exists, or updates existing invoices with recalculated totals. Returns `{ok, updated, updated_ids, insert_id}`.
- `POST /api/v1/invoices/check-and-generate` (`checkAndGenerateInvoice`) – Checks enrollment status and generates invoice if needed. Body requires `parent_id` and `status`. Only generates for statuses: `payment pending`, `withdrawn`, `enrolled`.
- `GET /api/v1/invoices/{id}/pdf` (`generatePdfInvoice`) – Prepares invoice data for PDF generation. Returns comprehensive invoice data including parent info, students (enrolled/withdrawn), charges, payments, discounts, refunds, and additional charges. Note: Actual PDF rendering would need separate implementation.
- `POST /api/v1/invoices` (`store`) – Creates a new invoice. Body should include invoice fields (see InvoiceModel fillable). Automatically sets `school_year` and `semester` from configuration if not provided.
- `PATCH /api/v1/invoices/{id}` (`update`) – Updates invoice fields. Allowed fields: `status`, `paid_amount`, `balance`, `description`.
- `PATCH /api/v1/invoices/{id}/status` (`updateStatus`) – Updates invoice status only. Body requires `status` field.
- `DELETE /api/v1/invoices/{id}` (`delete`) – Deletes an invoice.

**Invoice Calculation Logic:**
- Tuition fees calculated based on student grade levels (regular vs youth)
- Regular students (grade <= configured `grade_fee`): First student full price, additional students discounted
- Youth students (grade > `grade_fee`): Flat youth fee per student
- Refund window: Withdrawn students excluded from billing if within refund deadline, otherwise billed
- Event charges: Summed from event charges table
- Discounts: Recalculated based on voucher type (percent or fixed)
- Additional charges: Applied from `additional_charges` table (add/deduct types)
- Balance calculation: `total_amount - discounts - refunds_paid - payments_received`

**Helper Methods:**
- `calculateTuitionFee()` – Calculates tuition based on enrolled/withdrawn students and refund window
- `calculateTotalTuitionFee()` – Computes total tuition with regular/youth fee logic
- `recalculateAndUpdateDiscount()` – Recalculates and updates discount amounts for invoices
- `prepareInvoiceData()` – Prepares comprehensive invoice data for display/PDF
- `getGradeLevel()` – Parses grade names to numeric levels (handles KG, Pre-K, Youth, numeric grades)
- `compareGrades()` – Compares grade levels for sorting

## IpBanController
**File:** `app/Http/Controllers/Api/IpBanController.php`  
**Purpose:** Manage IP lockouts resulting from failed login attempts.

**Endpoints:**
- `GET /api/v1/ip-bans` (`index`) – Paginated list of IP ban records filtered by `status=all|active|expired`. Query params: `page`, `per_page`, `status`. Returns paginated results with IP addresses, attempt counts, blocked_until dates, and timestamps.
- `GET /api/v1/ip-bans/{id}` (`show`) – Fetch a specific ban record by ID or `404` if not found.
- `POST /api/v1/ip-bans/unban` (`unban`) – Unban IP(s). Body accepts:
  - `id` (integer) – Unban by record ID
  - `ip` (string) – Unban by IP address
  - `all` (integer, 1) – Unban all active bans (sets `blocked_until` to null and `attempts` to 0 for all active bans)
  - Returns count of unbanned IPs and success message
- `POST /api/v1/ip-bans` (`ban`) – Ban an IP with explicit date. Body requires:
  - `ip` (string, required) – IP address to ban
  - `blocked_until` (date, required) – Ban expiration date/time
  - Optional: `attempts` (integer, default 5), `reason` (string)
  - Creates new record if IP doesn't exist, or updates existing record
  - Returns the ban record
- `POST /api/v1/ip-bans/ban-now` (`banNow`) – Ban an IP immediately for specified hours. Body accepts:
  - `id` (integer) – Ban by record ID, or
  - `ip` (string) – Ban by IP address
  - `hours` (integer, default 24) – Number of hours to ban (minimum 1, defaults to 24)
  - Calculates `blocked_until` automatically from current time + hours
  - Sets attempts to max(current attempts, 10) for clarity
  - Returns IP address, blocked_until date, and hours