# Earlier MVP decisions and acceptance history

Current release: [Phase 1 implementation and verification](phase-1-implementation.md). It covers enrollment, subjects, Sections, schedules, COR Versions and manual final grades. The broader gradebook/material implementation below is historical and does not describe the current product surface.

The Course/Year/curriculum/Section gap documented here was addressed in Phase 1. The new evidence includes draft prefilling, class sharing, finance boundaries, membership ending, checked amendments and retained CORs. Historical results below remain unchanged as evidence of the earlier implementation.

This implementation follows the accepted ADRs and the enrollment-to-final-grade plan. The superseded department-finalization ADR is not implemented. This document records the conservative choices needed to turn unresolved details into working MVP behavior.

## Architecture and access

One repository contains Laravel controllers, Form Requests, authorization policies, reusable business services, React components and database migrations. There is one database per school, shared by its branches. An external mobile API can later call the same services; the MVP uses session-authenticated Inertia requests.

Staff roles are fixed permission bundles in config/school.php. Each assignment has its own branch and optional department. This small scoped-grant model avoids adding a general permission editor or a multi-tenant package to a school-per-deployment application. School Administrator is a school-wide setup/account role; financial recording and teacher-owned grade decisions require their separate permissions. Only a class's currently assigned, authorized subject teacher can change scores, finalize or correct its grades.

Student accounts have no staff assignments and link to one student record. They receive only their own finalized enrollment, roster identity and grades. Materials and transcripts are stored on the private disk and authorized again for every download. Account deactivation/password/access changes invalidate sessions; temporary passwords require a change on first use. There is no sign-up route.

## Periods, curricula and enrollment

An academic period is an explicitly configured school year or semester. The initial gradebook produces one final result per class offering in that enrollment period. Separate quarterly/interim reports are not assumed. The next period always receives new offerings, enrollments, scores and CORs; identity and history continue.

Curriculum publication verifies that prerequisite subjects are present and that dependencies contain no cycles. Published versions are immutable through the app. A student's existing version within the same program cannot silently switch during returning enrollment. New-program assignments are explicit. High school loads use the staff-selected year/grade level; college permits eligible subjects from different year levels. There is no automatic progression.

Only passing, finalized results from earlier periods and registrar-approved equivalent credits satisfy prerequisites. Draft grades and pending transcripts do not. Unmet prerequisites block finalization of a load containing the dependent subject; staff can remove that subject. No override exists. Finalization rechecks eligibility and section capacity while locking the affected records. A COR records a snapshot of the student, program, curriculum, period, subjects, sections, schedules and teachers.

## Finance

The MVP records positive integer-cent charges and payments with unique references. Payments cannot exceed recorded debt. Financial entries are append-only through the application. Balances are not copied into new terms as new charges.

Finance explicitly reviews an enrollment after all relevant current charges and payments are entered. A positive outstanding balance requires a designated finance approver's documented arrangement, including reason and payment terms. A normal settled clearance requires zero debt. Every ledger change invalidates existing draft clearance, which must be reviewed again. Arrangements apply to that enrollment and do not erase debt or automatically clear the next term. Finalized historical enrollments and their CORs are preserved.

Current-fee policy is represented by the charges that school finance records and its explicit clearance; the app does not invent a universal minimum payment or tuition schedule. Outstanding-account dashboard balances include all recorded obligations, while queues follow the selected period. Report transaction rows honor their period filter.

## Grades

For each category, sum earned points / sum available points × category percentage. Category weights must total 100%. Sum category contributions and round half-up to two decimal places. Every category requires at least one assessment, and every enrolled student requires a score for every item before finalization. An explicit zero is a score; blank means missing.

Percentage policies use the configured passing mark. Numeric policies require an explicit conversion table covering 0.00–100.00 without gaps or overlaps to two decimal places. Passing meaning belongs to the configured conversion, not an assumed universal 1.0/2.0 mapping. Teachers review the converted value and can adjust it with a recorded reason. A class retains its policy snapshot.

Finalization by the subject teacher immediately makes results official and locks normal score/grade editing. Correct Grade records the old/new grade, pass meaning, teacher, reason and time. It changes the official result used by future prerequisite checks without recalculating historical enrollments. Approved external source grades are stored only on transfer credits and do not enter local assessment calculations. GPA/GWA and repeat-attempt averaging are not invented while school averaging rules remain undefined.

## Dashboards and reports

Teacher/student homes prioritize classes. Registrar and finance views prioritize their enrollment/clearance queues; administration and department views show grade completion. Home views initially show current periods by date, with an explicit All periods option. Lists, totals, files and exports are authorized on the server. Multi-role grants do not multiply every permission across every visible branch.

Reports include enrollment register, prerequisite/retake review, credit evaluation, class roster, official grade sheet, completion status and financial transaction statements. Print and CSV use the same report definitions. CSV formula-leading cells are escaped. COR has its own printable document. Financial/academic report permissions remain separate; students use their own portal instead of school-wide reports.

## Student directory and profiles

Students opens a searchable, paginated school directory with a home-branch filter. Desktop uses a table; phones use student cards with a photo or initials, student number, branch, curricula and a View student action. A student's profile contains Overview, Current records, Grades, Enrollment history and Files tabs. Subject loads and official grades also use stacked cards on phones so the grade/result and teacher/schedule remain readable without sideways scrolling.

Overview includes the full name, immutable student number/home branch, birth date, optional email/phone/address, optional parent or guardian contact, assigned curricula and linked portal status. Registrar and enrollment staff maintain these details and upload photos/documents. School administrators can read profiles. Each permission retains its own branch scope; a setup or teacher role alone does not grant student-record editing.

Current records distinguishes active finalized enrollment, upcoming enrollment and drafts using configured period dates. History lists retained enrollments and issued CORs. Grades shows only teacher-finalized results, preserving percentage/numeric policies and subsequent teacher correction history. External credits retain their source grades and pending/credited status separately from local results. General audit events remain database-only.

Photos accept JPEG, PNG or WebP up to 4 MB/4096 pixels per side. Documents accept PDF, Word, text and supported raster images up to 10 MB, with a title/category and uploader/date metadata. Uploads use private storage; photo, document and existing transcript downloads recheck student ownership and branch authorization. Private paths are not included in page props. Uploads, edits, views, downloads and denied requests are audited. The additive student-profile migration preserves existing student identities and academic records.

## Acceptance evidence

| Requirement | Owning implementation | Verification |
| --- | --- | --- |
| Login, no sign-up, user creation/types/access | AuthController, UserService, SchoolSession, Users page | HTTP authentication/account tests and browser account-creation test |
| Branch and department boundaries | AccessService and model policies | Combined-role scope, direct-record, private-file and CSV tests |
| Enrollment and repeat cycle | EnrollmentService and Enrollment/Cor pages | College semester cycle and junior/senior-high yearly-cycle tests |
| Debt and authorized arrangements | FinanceService | Debt block, unauthorized approver and ledger invalidation tests |
| Curriculum versions and prerequisites | SetupService, EnrollmentService | Published-version guard, draft/final prerequisite and failed-grade tests |
| Transfer equivalencies | DocumentService and Credits page | Pending/approved evidence and transcript authorization tests |
| Scores, conversion, finalization, corrections | GradeService and Course page | Missing/maximum score, conversion, teacher-only finalization and correction-history tests |
| Student portal and materials | CourseOfferingPolicy, CourseController | Own-record and enrolled-class access tests |
| Student directory, profile and private files | StudentController, StudentProfileService, StudentFileService and Student policies | Profile detail/history/official-grade tests, branch and file authorization tests, desktop/phone form checks and populated grade-cycle check |
| Audit throughout, no viewer | AuditObserver, AuditRequest, AuditService | Change/security/denied-action events, password redaction and missing audit endpoint tests |
| Figma-responsive UI | Public Sans, shared tokens/icons, Shell and UI components | Desktop and 390px browser smoke checks, console checks and screenshots |

The automated PHP suite is run with SQLite and against the isolated PostgreSQL test database. Browser verification runs against the local PostgreSQL-backed application. Production deployment and school-specific data migration are separate operations.