# Alma — User Journeys

A complete map of every actor × journey across the platform, with
the current status of each so we can pick what to tackle next.

Sourced from the live codebase. **Reconciled 2026-06-10** against
`develop` @ `563795b` (through SIS Phase 13.5 — person editors,
progression/graduation, parent + alumni portals, real Arkesel SMS
with wallet + sender IDs). For the module-level master view see
`PRODUCT_SCOPE.md`.

---

## Status legend

| Marker | Meaning |
|---|---|
| ✅ **Shipped** | Built end-to-end, smoke-tested, visible in the UI a real user would touch. |
| 🟢 **Mostly shipped** | Core flow works; one or two edges still rough (e.g. no email yet, no UI for a niche edge case). |
| 🟡 **Partial** | Schema + backend shipped but UI absent, OR UI placeholder with no backend, OR command-line only. |
| 🟦 **Stub** | Role / route / dashboard exists but nothing meaningful behind it. |
| ⬜ **Not started** | No code yet. |

---

## 1 · Platform (super admin)

> Actor: `super_admin` on `central` team — Alma operator, not a school user.

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 1.1 | Sign in to platform dashboard | ✅ | `DashboardRedirectController` short-circuits super admins → `platform.dashboard` |
| 1.2 | Onboard a new tenant (4-step wizard + 5 demo users) | ✅ | `CreateTenantAction`, `Platform/Tenants/Create.vue` |
| 1.3 | List / search / filter tenants | ✅ | `platform.tenants.index` |
| 1.4 | View tenant detail (stats, identity, users) | ✅ | `Platform/Tenants/Show.vue` |
| 1.5 | Edit tenant (identity, levels, education profile) | ✅ | `Platform/Tenants/Edit.vue` |
| 1.6 | Suspend / reactivate / archive a tenant | ✅ | `platform.tenants.suspend` / `.reactivate` / `.destroy` |
| 1.7 | Manage platform-wide users (search, scope, archive, restore) | ✅ | `Platform/Users/Index.vue` |
| 1.8 | Reset a tenant user's password / toggle active / toggle verified | ✅ | `platform.users.reset-password` etc |
| 1.9 | Manage system role templates (edit perms → auto-propagate) | ✅ | `RoleTemplatesController` |
| 1.10 | Manage roles per tenant (create / edit / delete custom) | ✅ | `platform.roles.*` |
| 1.11 | Manage global lookups (~25 categories) | ✅ | `Platform/Lookups/*` |
| 1.12 | Impersonate any non-super tenant user | ✅ | `Impersonator` service + banner |
| 1.13 | Stop impersonation from anywhere | ✅ | `POST /impersonate/stop` outside `verified` group |
| 1.14 | Platform-wide finance dashboard | ⬜ | Per-tenant finance exists; cross-tenant aggregation does not |
| 1.15 | Platform analytics (MRR, active schools, application volume) | ⬜ | No models / dashboard |
| 1.16 | Billing / subscription management for tenants | ⬜ | Tenants don't pay Alma in code yet |
| 1.17 | System health / queue / errors dashboard | ⬜ | Activity log exists; ops view does not |

---

## 2 · Tenant administration (tenant_admin / registrar / ict_administrator)

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 2.1 | Forced school-profile setup wizard on first sign-in | ✅ | `RequireTenantSetup` middleware + `Admin/Setup.vue` |
| 2.2 | Manage campuses | ✅ | inline-edit table |
| 2.3 | Manage faculties (with colleges) | ✅ |  |
| 2.4 | Manage departments | ✅ |  |
| 2.5 | Manage programmes (duration, qualification, credit hours, cutoffs) | ✅ |  |
| 2.6 | Manage academic years + terms + intakes | ✅ | `AcademicYearController` |
| 2.7 | Publish / close / archive intakes (state machine) | ✅ | with grace-day overdue auto-close |
| 2.8 | Manage tenant users (`admin/security/users`) | ✅ | + role assignment |
| 2.9 | Manage tenant roles (with system-default vs customised badges + revert) | ✅ | `Admin/Security/Roles.vue` |
| 2.10 | View activity log | ✅ | `admin.security.activity.index` |
| 2.11 | Configure password / MFA policies per tenant | ✅ | `admin.security.policies.*` |
| 2.12 | Manage API tokens (Sanctum) | ✅ | `Settings/ApiTokens.vue` |
| 2.13 | Configure student-number scheme (token pattern) | ✅ | stored in `education_system_profile` |
| 2.14 | Tenant branding (logo day / night) | ✅ | shows on offer letter PDF + shells |
| 2.15 | Tenant data export bundle | ✅ | UI download button + `php artisan tenant:export` |
| 2.16 | Manage admission requirement sets + programme cutoffs UI | ✅ | per-programme cutoffs editor shipped |
| 2.17 | Tenant-wide announcements / broadcast | ✅ | `BroadcastAnnouncement` + audience picker (Phase 12.4) |
| 2.18 | Tenant settings → integrations (SMS provider keys etc) | ⬜ | SMS uses stub; no UI to plug in real keys |

---

## 3 · Admissions (applicant + admissions_officer)

### 3a · Applicant journey

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 3.1 | Anonymous voucher purchase (Hubtel stub) | ✅ | `Apply/Voucher/Buy.vue` |
| 3.2 | Receive voucher receipt via email | ✅ | email log captures it |
| 3.3 | Register as applicant on Apply portal | ✅ | `Apply/Register.vue` |
| 3.4 | Sign in to Apply portal | ✅ | `Apply/Login.vue` |
| 3.5 | Redeem voucher with name confirmation | ✅ | `Apply/Redeem.vue` |
| 3.6 | Application wizard — Biodata → Exam Results → Documents (auto-save) | ✅ |  |
| 3.7 | Programme picker with live green/amber/red adjudication | ✅ | unique to Alma |
| 3.8 | Declarations + submit | ✅ |  |
| 3.9 | Track application status timeline | ✅ |  |
| 3.10 | View offer letter PDF (watermarked) | ✅ | `Offer` model + dompdf |
| 3.11 | Accept / decline offer | ✅ | `Apply/Application/Status.vue` |
| 3.12 | Pay acceptance fee (Hubtel stub) | ✅ | `Apply/Payment/*` |
| 3.13 | Apply UI shows admissions-closed state + countdown | ✅ | when intake.status != open |
| 3.14 | Submission blocked when intake closes mid-draft | ✅ | `ApplicationController::submit` gate |
| 3.15 | Applicant impersonated by registrar to debug their form | ✅ | DashboardRedirect routes applicants → `apply.landing` |
| 3.16 | Applicant uploads supplementary docs after submission | ⬜ | No post-submit doc upload flow |
| 3.17 | Applicant message thread with admissions officer | ⬜ | No model |

### 3b · Admissions officer journey

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 3.18 | Officer cohort dashboard (analytics + charts) | ✅ | `AdmissionsAnalytics` + Chart.js |
| 3.19 | Application queue with filters (status / verdict / programme / intake / sort) | ✅ |  |
| 3.20 | Application detail view with full adjudication trace | ✅ |  |
| 3.21 | Record decision (under_review / offered / rejected / waitlisted) | ✅ |  |
| 3.22 | Auto-generate offer letter PDF on `offered` | ✅ | `GenerateOfferLetter` action |
| 3.23 | Offer-letter template editor (CRUD per tenant) | ✅ | `OfferTemplatesController` |
| 3.24 | Bulk offer issuance (queued job + preview) | ✅ | `BulkOffersController` |
| 3.25 | Conditional offers (template auto-pick) | ✅ |  |
| 3.26 | Nightly auto-close overdue intakes + auto-reject pending applications | ✅ | `intakes:close-overdue` |
| 3.27 | Applicant→Person bridge runs on enrolment (dedup by national ID / email) | ✅ | `UpsertPersonFromApplication` |
| 3.28 | Application-documents → student-documents ingest on enrolment | ✅ | `IngestApplicationDocuments` |
| 3.29 | Entrance exam management (sittings, assign, score) | ✅ | `EntranceExamsController` (Module 1.1) |
| 3.30 | Interview scheduling (panels, invite, recommend) | ✅ | `InterviewsController` (Module 1.2) |
| 3.31 | Reference handling (tokenized referee submission) | ✅ | `ReferenceSubmissionController` (Module 1.3) |
| 3.32 | Scholarship schemes + applications + award | ✅ | `ScholarshipsController` (Module 1.4) |
| 3.33 | International processing + credential equivalency → adjudication | ✅ | `InternationalController` (Module 1.5) |
| 3.29 | Officer bulk-message a cohort | ⬜ | No UI |
| 3.30 | Waitlist promotion workflow | ⬜ | `waitlisted` status exists; no promote action |

---

## 4 · Student Information System (registrar + student)

### 4a · Registrar / officer journey

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 4.1 | Student directory with state / programme filters + FTS search | ✅ | Phase 8 (`websearch_to_tsquery`) |
| 4.2 | Student profile (biodata, contacts, IDs, family, state, classification, card, docs, timeline) | ✅ | the WOW page |
| 4.3 | Request leave of absence (kind / dates / reason) | ✅ | modal on profile |
| 4.4 | Approve / reject pending leave | ✅ | inline on profile |
| 4.5 | Auto-resume leaves when `effective_to` arrives (nightly) | ✅ | `sis:process-mobility` |
| 4.6 | Request internal programme transfer | ✅ | modal with programme picker |
| 4.7 | Approve / reject transfer (atomic registration close+open) | ✅ |  |
| 4.8 | Request new student card | ✅ | `CardService` |
| 4.9 | Issue + activate card | ✅ |  |
| 4.10 | Mark card lost / damaged / surrendered | ✅ |  |
| 4.11 | Reissue card (v+1 chained to predecessor) | ✅ |  |
| 4.12 | Auto-expire active cards when student leaves active state | ✅ | StateMachine ↔ CardService crosswire |
| 4.13 | Verify / unverify a student document | ✅ | inline on profile |
| 4.14 | Withdrawal flow (voluntary / academic / disciplinary / deceased) | ✅ | `WithdrawalService` + profile UI (Phase 12.3) |
| 4.15 | Refund eligibility computed at withdrawal (14d / 60d window) | ✅ | computed + finance disbursement UI (Phase 12.3) |
| 4.16 | Nightly classification recompute | ✅ | `sis:recompute-classifications` |
| 4.17 | Edit Person biodata (name correction, DOB fix) | ✅ | `PersonsController` edit modal (Phase 13.1) |
| 4.18 | Add / edit / remove Person identifications (Ghana Card, passport) | ✅ | Government-IDs card + verify (Phase 13.1) |
| 4.19 | Add / edit family / sponsor relationships | ✅ | Family card + add/remove + link-parent (Phase 13.1/13.4) |
| 4.20 | Bulk operations (e.g. issue cards to all freshmen) | 🟡 | Bulk register + promote + graduate shipped; bulk card issuance ⬜ |
| 4.21 | Promotion / progression (year N → N+1 batch) | ✅ | `PromoteCohort` + Progression UI (Phase 13.2) |
| 4.22 | Graduation workflow (mark cohort as `graduated`) | ✅ | `GraduateCohort` + Progression UI (Phase 13.2) |
| 4.23 | Transcripts generation | ✅ | `GenerateTranscript` + Blade PDF + registrar Issue button (Phase 10.5) |
| 4.24 | Alumni rollover (graduated → alumni role) | ✅ | `RollAlumni` auto-runs after graduation (Phase 13.2) |
| 4.25 | Search across staff + students (full tenant directory) | ⬜ | FTS only on student-side; no staff Person yet |

### 4b · Student self-service journey

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 4.26 | Student dashboard (state badge, standing, credits, active card, activity) | ✅ | `Student/Dashboard.vue` |
| 4.27 | Student profile (biodata read-only, contacts editable, IDs, family, docs) | ✅ | `Student/Profile.vue` |
| 4.28 | Update own email (re-verification triggered) | ✅ | `student.profile.emails.update` |
| 4.29 | Update own phone | ✅ |  |
| 4.30 | Download own documents via signed-URL viewer | ✅ | reuses encrypted storage + watermarking |
| 4.31 | Self-request leave / deferment | ⬜ | Backend service exists; no student-facing UI |
| 4.32 | View own card with QR / NFC details | 🟡 | Active card visible; no print-this-card export |
| 4.33 | Report card lost (triggers reissue request) | ⬜ |  |
| 4.34 | Upload supplementary document (medical cert, indemnity) | ⬜ | Encrypted storage exists; no upload UI |
| 4.35 | View own lifecycle history with full provenance | 🟡 | Recent-activity strip on dashboard; no dedicated history page |
| 4.36 | View / update address | 🟡 | Read-only on profile; no edit form |
| 4.37 | Verify primary email | ⬜ | Field exists; no link-emailing flow |
| 4.38 | Set notification preferences | ✅ | Settings › Notifications — channel × category matrix (Module 8a) |

---

## 5 · Academic / teaching

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 5.1 | Course catalogue schema (courses, credit hours, prereqs) | ✅ | Curriculum editor + course CRUD (Phase 11.1) |
| 5.2 | Course registration schema (student × course × year × semester) | ✅ | Bulk-register cohort + self-registration (Phase 11.3/11.4) |
| 5.3 | Lecturer assigned to course | ✅ | `course_assignments` + registrar Assignments UI (Phase 10.2) |
| 5.4 | Timetable / class schedule | ✅ | Rooms + weekly blocks + conflict detection (Phase 12.2) |
| 5.5 | Attendance capture (lecturer-side) | ✅ | `AttendanceSession` capture grid (Phase 12.1) |
| 5.6 | Attendance view (student-side) | ✅ | Student attendance summary (Phase 12.1) |
| 5.7 | Assignments / submissions | ✅ | LMS Module 6 — `lms_assignments`/`lms_submissions`, resubmit-until-graded, late policy, inline grading + GradeSync (see 5.28–5.34) |
| 5.8 | Grade entry (lecturer) | ✅ | gradebook matrix with autosave + live letter/point (Phase 10.3) |
| 5.9 | Grade approval (HOD / dean / registrar release) | ✅ | release queue + return-with-notes (Phase 10.4) |
| 5.10 | Per-tenant grade scale config (A=4.0 etc) | ✅ | `GradeScale` + `GradeScales` defaults + `tenants:backfill-grade-scale` (Phase 10.1) |
| 5.11 | GPA computation (year + cumulative) | ✅ | `ClassificationEngine` populates `gpa_year` + `gpa_cumulative` on release |
| 5.12 | Transcript generation (signed PDF) | ✅ | `GenerateTranscript` action + Blade template + student self-serve (Phase 10.5) |
| 5.13 | Programme-level course planning (curriculum) | ✅ | `CurriculumItem`/`CurriculumRule` + editor (Phase 11.1) |
| 5.14 | Course substitution / waiver workflow | 🟡 | `RegistrationWaiver` for prereq overrides; no general substitution |
| 5.15 | Per-course assessment plan (Quizzes / Midterm / Final with weights) | ✅ | `course_assessment_components` + editor (Phase 10.2) |
| 5.16 | Class-of-degree resolution from cumulative GPA | ✅ | `GradeScale::classify` + tenant `classification_bands` (Phase 10.5) |
| 5.17 | Academic policy config UI (credits / GPA / classification bands) | ✅ | `Academic\PolicyController` — edits `education_system_profile` knobs the engines read (Module 3) |
| 5.18 | Accreditation tracking (bodies + programme accreditations + expiry) | ✅ | `AccreditationController` (Module 3) |
| 5.19 | Course offerings + seat capacity enforcement | ✅ | `CourseOffering` + `CourseRegistrar` (Module 4) |
| 5.20 | Waitlisting + auto-promote on drop (FIFO) | ✅ | `CourseRegistrar::place/drop` + waitlist UI (Module 4) |
| 5.21 | Advisor/registrar approval of registrations (per-tenant toggle) | ✅ | approval queue + policy toggle (Module 4) |
| 5.22 | Repeat / resit management (attempt tracking) | ✅ | `attempt_no` + `is_resit` on re-registration (Module 4) |
| 5.23 | Hard server-side timetable conflict enforcement (room + lecturer) | ✅ | `ScheduleConflicts` (Module 5) |
| 5.24 | Automatic timetable generation (greedy auto-fill) | ✅ | `TimetableGenerator` + preview/commit (Module 5) |
| 5.25 | Exam timetable with room + invigilator conflict checks | ✅ | `ExamSlot` + `ExamTimetableController` (Module 5) |
| 5.26 | Lecturer workload dashboard vs configurable max | ✅ | hours summed from blocks (Module 5) |
| 5.27 | Online / hybrid class link management | ✅ | `meeting_mode` + `meeting_provider` + REUSABLE `meeting_url` on blocks; Join strips on student timetable + LMS Sessions tab (Modules 5 + 6) |
| 5.28 | Zero-setup LMS course spaces (derived, no configuration) | ✅ | `LmsAccess` — lecturer spaces from `CourseAssignment`, student spaces from `CourseRegistration` (registered/completed/failed); registrar bypass via grades.release (Module 6 L-a) |
| 5.29 | Course materials (topic/week-grouped files + links) | ✅ | `lms_materials` — encrypted uploads + grants, visibility toggle (Module 6 L-a) |
| 5.30 | Auto-marked online quizzes (MCQ/TF, windows, time limits, attempts) | ✅ | `QuizMarker` — server-side marking + time-limit enforcement; answers never serialised (Module 6 L-c) |
| 5.31 | LMS marks → gradebook sync | ✅ | `GradeSync` writes scaled scores through `SaveRegistrationScores` into the existing release pipeline; locked batches warn (Module 6 L-b/L-c) |
| 5.32 | Class recordings, auto-named + serialized by date | ✅ | `lms_recordings` — "CS101 — Tuesday class — 2026-06-09"; unique per session+date; quick-add prefills latest past weekday (Module 6 L-d) |
| 5.33 | Course-space announcements w/ student notifications | ✅ | `LmsAnnouncementPosted` via the prefs-aware notification stack (Module 6 L-e) |
| 5.34 | Discussion forums / plagiarism check / SCORM | ⬜ | LMS v2 — logged on the map as remaining |

---

## 6 · Examinations

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 6.1 | Exam scheduling per academic year + term | ✅ | `ExamSlot` + `ExamTimetableController` (Module 5/6) |
| 6.2 | Hall / venue allocation + seating | ✅ | `ExamSeatAllocator` + logistics page (Module 6a) |
| 6.3 | Invigilator roster (multi per exam) | ✅ | `ExamInvigilator` (Module 6a) |
| 6.4 | Results processing pipeline (raw scores → grade) | ✅ | `ReleaseGrades` + `ClassificationEngine` |
| 6.5 | Results release approval | ✅ | submit → release; + senate ratification step (Module 6b) |
| 6.6 | Re-mark / appeal workflow | ✅ | `ResultAppeal` — lodge / review / adjust (Module 6c) |
| 6.7 | Senate result workflow (ratify before publish) | ✅ | per-tenant toggle + senate queue (Module 6b) |
| 6.8 | Supplementary / resit-result processing | ✅ | `SupplementaryResult` supersedes a fail (Module 6d) |
| 6.9 | Certificate generation (template-driven PDF) | ✅ | `GenerateCertificate` + templates (Module 6e) |

---

## 7 · Finance

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 7.1 | Voucher payment via Hubtel stub | ✅ | `PaymentGateway` interface + stub |
| 7.2 | Acceptance fee payment | ✅ |  |
| 7.3 | Payment callbacks / verification | ✅ |  |
| 7.4 | Finance admin dashboard (payments index + analytics) | ✅ | `Admin/Finance/*` |
| 7.5 | CSV export of payments | ✅ |  |
| 7.6 | Real payment-gateway integration (replace stub) | 🟡 | Interface ready; payment PSP still stubbed (SMS went real in 13.3/13.5, payments pending) |
| 7.7 | Other payment gateways (Paystack, Flutterwave, MTN MoMo direct) | ⬜ | Interface is gateway-agnostic; no implementations |
| 7.8 | Tuition / fee schedules per programme / level | ✅ | Phase 9.2 — `FeeSchedule` + editor UI |
| 7.9 | Invoice generation per student per academic year | ✅ | Phase 9.3 — `InvoiceGenerator` service + admin trigger |
| 7.10 | Payment-plan / instalment management | ✅ | Phase 9.7 — `CreateInstalmentPlan` + registrar split modal |
| 7.11 | Statement-of-account export (per student PDF) | ✅ | Phase 9.4 — registrar + student `StatementsController` |
| 7.12 | Refund disbursement workflow | ✅ | dedicated refund flow on approved withdrawal (Phase 12.3) |
| 7.13 | Late-fee accrual | ✅ | Phase 9.8 — `finance:accrue-late-fees` nightly cron + tenant policy |
| 7.14 | Reconciliation against bank statement | ✅ | Phase 9.9 — CSV import + 2-pass matcher + manual attach UI |
| 7.15 | Tax invoice / receipt PDF | ✅ | `Receipt` auto-created per settled payment in `AllocatePayment`; lazy PDF via `RenderReceiptPdf` + DocumentGrant; admin payments column + student Fees section (Module 7b) |
| 7.16 | Bursary / waiver / write-off ledger adjustments | ✅ | Phase 9.6a — modal on statement |
| 7.17 | Generic "Pay any invoice" student endpoint | ✅ | Phase 9.6b — per-invoice Pay button |
| 7.18 | Financial holds (place / release; block reg + transcripts + certs) | ✅ | `FinancialHolds` service + gates in `CourseRegistrar`, transcript controllers, `GenerateCertificate`; admin Holds page (Module 7a) |
| 7.19 | Sponsor register + coverage-% sponsorships | ✅ | `Sponsor`/`Sponsorship` (≤100% combined per student); admin Sponsors pages (Module 7c) |
| 7.20 | Consolidated sponsor statement (HTML + PDF) | ✅ | `SponsorStatement` service + `pdf/sponsor-statement` (Module 7c) |
| 7.21 | Hostel billing | ✅ | `IssueHostelInvoice` on seat-map booking (Module 11c); receipts + pay-any-invoice flow apply |

---

## 8 · Communications

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 8.1 | Notification channel abstraction (SMS + email) | ✅ | scaffolding shipped |
| 8.2 | Email log capture + admin viewer | ✅ | `admin.communications.emails.*` |
| 8.3 | Resend a logged email | ✅ |  |
| 8.4 | Mailpit dev capture (`:8025`) | ✅ |  |
| 8.5 | Real SMS gateway integration (Arkesel) | ✅ | `ArkeselSmsGateway` + platform wallet + sender IDs (Phase 13.3/13.5) |
| 8.6 | Notification preferences per user | ✅ | per-channel × per-category opt-out matrix; `NotificationPreferences` service enforced in `AnnouncementDelivered::via()` (Module 8a) |
| 8.7 | Bulk announcements (cohort / programme / faculty) | ✅ | `BroadcastAnnouncement` + audience picker (Phase 12.4) |
| 8.8 | Templated comms + scheduled reminders | ✅ | `CommsTemplate` ({{token}} subject+body) + `ScheduledReminder` (audience + cadence) + `comms:send-reminders` hourly cron (Module 8b) |
| 8.13 | Emergency alerts (all-channel, bypass opt-outs) | ✅ | `BroadcastEmergencyAlert` + `EmergencyAlertDelivered`; ignores prefs, distinct urgency UI (Module 8c) |
| 8.14 | Push notifications | 🟡 | `PushGateway` interface + `StubPushGateway`; real FCM/web-push deferred (Module 8d) |
| 8.15 | Live chat support | 🟡 | `ChatProvider` interface + `StubChatProvider`; real provider deferred (Module 8d) |
| 8.9 | In-app inbox | ✅ | Laravel notifications inbox for every role (Phase 12.4) |
| 8.10 | SMS wallet (pre-paid balance, top-up, low-balance alerts) | ✅ | `SmsWalletService` + ledger (Phase 13.5) |
| 8.11 | SMS sender-ID request → review → approve lifecycle | ✅ | `SmsSenderIdService` (Phase 13.5) |
| 8.12 | Outbound SMS log + retry | ✅ | `OutboundSmsController` (Phase 13.3) |

---

## 9 · Authentication, security, IAM

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 9.1 | Self-register on Apply portal | ✅ |  |
| 9.2 | Sign in (Fortify) | ✅ |  |
| 9.3 | Sign-in error messaging (unverified / suspended / no role / tenant suspended) | ✅ | `SignInGate` |
| 9.4 | Sign out from PublicShell + ApplyShell + AppShell | ✅ |  |
| 9.5 | Email verification flow | ✅ | end-to-end send + click + verify (Quick Win 3) |
| 9.6 | Password reset (Fortify) | ✅ |  |
| 9.7 | 2FA enable + challenge | ✅ | Fortify TwoFactorAuthenticatable |
| 9.8 | Passkey registration / use | ✅ | enrol UI in Settings/Security + use UI in Login (Quick Win 2) |
| 9.9 | Super-admin impersonation start + stop + banner | ✅ |  |
| 9.10 | Activity log capture for every mutation | ✅ | `ActivityLogger` |
| 9.11 | Per-tenant password policies (length / complexity / rotation) | ✅ |  |
| 9.12 | Session management (revoke other sessions) | ⬜ |  |
| 9.13 | OAuth / SSO (Google / Microsoft for staff, social for applicants) | ⬜ |  |

---

## 10 · Library / Hostel / HR / Transport

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 10.1 | Library catalogue + lending | ✅ | Module 12 — see 10.21–10.26 |
| 10.2 | Hostel allocation + room map | ✅ | Module 11 — see 10.6–10.13 |
| 10.3 | HR — staff records, contracts, payroll links | ✅ | Module 13 — see 10.14–10.20 |
| 10.4 | Transport — routes, vehicles, drivers | ⬜ |  |
| 10.5 | Asset / inventory management | ⬜ |  |
| 10.6 | Room classes w/ facilities + default yearly fee | ✅ | `HostelRoomClass` (facilities JSON); admin Classes page (Module 11a) |
| 10.7 | Hostel → room → bed inventory (gender-restricted) | ✅ | beds auto-seeded to capacity; occupancy derived from active allocations (Module 11a) |
| 10.8 | Per-hostel × class fee override | ✅ | `HostelClassFee` + `Hostel::feeFor()` (Module 11a) |
| 10.9 | Student seat-map self-service booking (instant) | ✅ | `Student/Hostel.vue` + `HostelSeatMap`; `BookBed` service; PG partial unique indexes guard races (Module 11b) |
| 10.10 | Officer manual allocation + check-in / check-out / cancel | ✅ | admin Allocations page; check-out frees the bed (Module 11b) |
| 10.11 | Hostel invoice on booking; void on pre-check-in cancel | ✅ | `IssueHostelInvoice` (HOSTEL fee item, ledger charge + reversing credit) (Module 11c) |
| 10.12 | Visitor log (check-in/out) | ✅ | `HostelVisitor`; Residence page (Module 11d) |
| 10.13 | Residence incidents (report → resolve) | ✅ | `HostelIncident`; Residence page (Module 11d) |
| 10.14 | Employee register + contracts | ✅ | `Employee`/`EmployeeContract` (new contract supersedes); admin Employees pages (Module 13a) |
| 10.15 | Salary structure (earnings/deductions line items) | ✅ | `EmployeePayItem` w/ toggle; net preview on employee page (Module 13a) |
| 10.16 | Monthly payroll run + payslip PDFs | ✅ | `RunPayroll` snapshot → `Payslip` (lazy PDF via DocumentGrant); finalise locks (Module 13b) |
| 10.17 | Leave entitlements + request → approve | ✅ | `LeaveBalances` enforced at request AND approval; per-employee matrix (Module 13c) |
| 10.18 | Appraisal cycles (performance management) | ✅ | cycles + rating/strengths/improvements/goals, draft → submitted (Module 13d) |
| 10.19 | Staff task delegation | ✅ | `StaffTask` assign → in_progress → done/cancelled (Module 13e) |
| 10.20 | Staff attendance sign-in/out | ✅ | `StaffAttendance` daily log (Module 13e) |
| 10.21 | Library catalogue (items + barcoded copies) | ✅ | `LibraryItem`/`LibraryCopy`; availability derived from active loans (Module 12a) |
| 10.22 | Circulation desk — issue / return by accession scan | ✅ | `Circulation` service; students AND staff borrow; max-loans + double-issue guards + PG partial unique index (Module 12b) |
| 10.23 | Overdue fines → student ledger | ✅ | per-day tenant policy; `IssueLibraryFineInvoice` (LIBRARY_FINE fee item) payable on Fees page; staff fines register-only (Module 12b) |
| 10.24 | Digital library (eBooks + external links) | ✅ | encrypted pdf/epub uploads + signed grants; student Library page + nav (Module 12c) |
| 10.25 | Journal subscriptions w/ expiry | ✅ | expired items hidden from students, downloads blocked (Module 12c) |
| 10.26 | RFID reader integration | 🟡 | `RfidProvider` + stub (Module 12d); barcode scanning live via keyboard-wedge |

---

## 11 · Parents

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 11.1 | Parent dashboard | ✅ | Children list w/ GPA + attendance + fee balance (Phase 13.4) |
| 11.2 | Parent sees their child's records (linked via `person_relationships` kind=parent) | ✅ | `ParentPortal\ChildController` drill-down + registrar link-parent flow (Phase 13.4) |
| 11.3 | Parent receives fee / attendance / results notifications | 🟡 | Inbox reaches parents; no parent-targeted auto-alerts yet |
| 11.4 | Parent pays fees for child | 🟡 | Balance + "Pay fees" CTA surfaced; payment uses stub PSP |

---

## 12 · Alumni

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 12.1 | Alumni dashboard | ✅ | Class-of-degree badge + GPA + transcripts shortcut (Phase 13.4) |
| 12.2 | Alumni profile / network | 🟡 | Own profile ✅; cross-cohort directory ⬜ |
| 12.3 | Donation / giving | ⬜ |  |
| 12.4 | Events + RSVPs | ⬜ |  |
| 12.5 | Alumni-to-current-student mentorship | ⬜ |  |

---

## 13 · Reports & analytics

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 13.1 | Admissions cohort analytics dashboard | ✅ | Phase A2 |
| 13.2 | Finance dashboard (basic) | ✅ |  |
| 13.3 | SIS dashboards (enrolment counts, state distribution, classification trends) | ⬜ | Data ready; no Chart.js page |
| 13.4 | Compliance / accreditation report bundles | ⬜ |  |
| 13.5 | Tenant data export bundle (zip of CSVs + docs) | 🟡 | Command exists; no UI trigger |
| 13.6 | Scheduled report delivery (weekly email) | ⬜ |  |

---

## 15 · ICT Lab Management (ict_administrator) — 🟡 (built 2026-06-10; agents pending)

Built as Module 15 (map numbering). Perms: `ictlab.manage`
(ict_administrator), `ictlab.book` (+ teachers, lecturers).

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 15.1 | Computer/equipment inventory | ✅ | `labs` + `lab_assets` (kind, specs JSON, status); admin Labs pages |
| 15.2 | Maintenance history per asset | ✅ | `lab_maintenance_logs` w/ costs; inline history on the lab page |
| 15.3 | Lab-user management (access) | ✅ | reuses IAM — `ictlab.*` permissions on existing roles |
| 15.4 | Lab attendance (entry/exit) | ✅ | `lab_attendances` sign-in/out log + student typeahead |
| 15.5 | Lab booking (conflict-free) | ✅ | standalone `lab_bookings` calendar; `overlapping()` scope rejects clashes; agenda view |
| 15.6 | Software & license management | ✅ | `lab_software` + per-lab installs; expiry + seat-overage warnings |
| 15.7 | Network monitoring | 🟡 | `MonitoringProvider` + stub (Module 15e); real probe/agent deferred |
| 15.8 | Maintenance tracking (fault tickets) | ✅ | `lab_tickets` open → assign → resolve → close; flips asset status faulty↔working |
| 15.9 | Security management | ✅ | ActivityLogger audit on every mutation + policy engine |
| 15.10 | Report generation | ✅ | dashboard stats strip (assets by status, open tickets); §18 reporting will extend |
| 15.11 | Remote classroom control | 🟡 | `RemoteControlProvider` + stub; Veyon / NetSupport integration recommended |

---

## 16 · Developer / DevOps surfaces

| # | Journey | Status | Notes / References |
|---|---|---|---|
| 16.1 | Encrypted document storage (per-tenant HKDF keys) | ✅ |  |
| 16.2 | Signed in-platform document viewer + time-limited grants + watermarks | ✅ |  |
| 16.3 | Activity log indexed + queryable | ✅ |  |
| 16.4 | API tokens (Sanctum) | ✅ |  |
| 16.5 | Public REST API surface (read student, etc) | ⬜ | Tokens exist; no documented endpoints |
| 16.6 | Webhooks (e.g. "student enrolled" → external system) | ⬜ |  |
| 16.7 | Migration rollback safety on production data | n/a | Development discipline; no code journey |

---

## How to read this for prioritisation

The core registrar operating loop now ships end-to-end (admissions →
enrolment → fees → registration → timetable → attendance → grading →
transcripts → progression → graduation → alumni, with parent
visibility and real SMS). **Updated next bets**, ranked by impact vs
effort given current foundations:

1. **Real payment gateway** (7.6) — swap the stub PSP for a live
   provider (Hubtel/Paystack/MoMo). The single biggest blocker to
   real-money production; SMS already went real in Phase 13.3/13.5.
2. **Examination logistics & certificates** (§6) — exam timetable,
   hall/seating, resit processing, senate workflow, certificate
   generation. Completes the academic loop's tail.
3. **SIS / financial analytics dashboards** (13.2–13.3) — read-side
   build on data that already exists; high perceived value.
4. **ICT Lab Management tiers 15.1–15.5** (§15) — contained, reuses
   attendance/scheduling/audit engines; first real home for the
   `ict_administrator` role.
5. **Campus Operations trio** (§10 — Hostel, Library, HR) — follow
   the facility-ops pattern proven by ICT Lab; Hostel also unblocks
   hostel-billing in Finance.
6. **Native mobile apps** (LMS shipped 2026-06-11) —
   Phase-3 horizon; largest builds, best after the operational core
   is fully production-hardened.

---

_Last reconciled: 2026-06-10 against `develop` @ `563795b` (SIS Phase 13.5).
Module-level master view: `PRODUCT_SCOPE.md`._