# BV-SIS — Admission Workflow Report

**Date:** 10 July 2026  
**Service:** `App\Services\Admission\ApplicationWorkflowService`

---

## Status Machine

| Status | Label |
|--------|-------|
| draft | Draft |
| submitted | Submitted |
| document_verification | Document Verification |
| academic_review | Academic Review |
| interview | Interview |
| pending_decision | Pending Decision |
| approved | Approved |
| rejected | Rejected |
| waitlisted | Waitlisted |
| offer_issued | Offer Issued |
| offer_accepted | Offer Accepted |
| offer_declined | Offer Declined |
| converted_to_student | Converted to Student |

---

## Transition Rules

Configured in `admission_workflow_transitions` (seeded) and enforced by `ApplicationWorkflowService`.

Typical happy path:

1. **Draft → Submitted** (portal submit / staff submit)  
2. **Submitted → Document Verification**  
3. **Document Verification → Academic Review**  
4. **Academic Review → Interview** (if required) or **Pending Decision**  
5. **Pending Decision → Approved / Rejected / Waitlisted**  
6. **Approved → Offer Issued**  
7. **Offer Issued → Offer Accepted / Offer Declined**  
8. **Offer Accepted → Converted to Student**

Every transition writes `application_status_logs` with from/to, user, notes, meta.

---

## Staff Actions (ApplicationsController)

| Action | Route | Effect |
|--------|-------|--------|
| Submit | `applications/{id}/submit` | Draft → Submitted |
| Assign reviewer | `applications/{id}/assign-reviewer` | Sets assigned_reviewer_id |
| Transition | `applications/{id}/transition` | Arbitrary allowed status change |
| Decide | `applications/{id}/decide` | Creates AdmissionDecision + status update |

---

## Offer Lifecycle

1. Generate from template (`OfferLetterService`) with variable replacement + QR token  
2. PDF Blade: `admission.offer-letters.pdf`  
3. Email via `AdmissionNotificationService`  
4. Accept / Decline endpoints update offer + application status  

---

## Fee Lifecycle

1. Configure `registration_fee_setups`  
2. Generate invoice (`RegistrationFeeService`)  
3. Record payment → update `payment_status`  
4. Receipt / print views  

---

## Portal Flow

1. `/apply` — start (create applicant + draft application)  
2. `/apply/{uuid}/step` — multi-step save (autosave)  
3. `/apply/{uuid}/submit` — submit for review  
4. `/apply/track` — lookup by application number  

---

## Notifications

| Event | Channel |
|-------|---------|
| Application submitted | Email + SMS (Africa's Talking if configured) |
| Documents missing | Email/SMS |
| Interview invitation | Email/SMS |
| Offer issued | Email/SMS |
| Offer accepted/rejected | Email/SMS |
| Registration reminder | Email/SMS |

SMS credentials optional — service logs when unset.