# Registration To Certificate Workflow

## Objective

Provide one operational workflow from public registration to academic completion and certificate issuance.

## 1. Public Registration

Entry point:
- `/register`
- `course` and `session` query params can preselect the course/cohort.

Core flow:
1. Student enters personal data.
2. Student chooses a cohort.
3. System creates a reserved enrollment for 24 hours.
4. Student chooses payment method.
5. Student uploads receipt if the method requires proof.
6. Registration waits for finance review.

Main code:
- `app/Livewire/Registration/RegistrationStepper.php`
- `app/Application/UseCases/Registration/SavePersonalDataStep.php`
- `app/Application/UseCases/Registration/Cohorts/ChooseCohort.php`
- `app/Application/UseCases/Payments/SelectPaymentMethod.php`
- `app/Application/UseCases/Payments/Receipts/UploadReceipt.php`

## 2. Payment Confirmation

Operational rule:
- Choosing a payment method does not make the learner academically active yet.
- The learner becomes operationally active after payment confirmation.

Current confirmed payment statuses:
- `confirmed`
- `verified`

When payment is confirmed:
- registration status is normalized to `confirmed`
- enrollment status is normalized to `confirmed`
- `enrolled_at` is filled if missing

Main code:
- `app/Observers/PaymentObserver.php`
- `app/Listeners/Registrations/SyncEnrollmentAfterPaymentConfirmed.php`

## 3. Cohort Schedule

The cohort stores the teaching frame:
- `start_date`
- `end_date`
- `days_of_week`
- `start_time`
- `end_time`

Attendance sessions are then generated from that frame.

Main code:
- `app/Models/Session.php`
- `app/Domain/Attendance/AttendanceScheduleService.php`

## 4. Attendance Taking

Attendance is captured per generated teaching session.

Supported statuses:
- `present`
- `absent`
- `late`
- `excused`

Operational side effects:
- First attendance marks `attendance_confirmed_at`
- If the marked session is the first cohort session, present/late learners get `first_session_attended_at`
- This powers first-session no-show follow-up

Main code:
- `app/Domain/Attendance/AttendanceWorkflowService.php`
- `app/Domain/Attendance/AttendanceInsightsService.php`

## 5. Academic Completion

Academic completion is now separate from payment confirmation.

An enrollment can move from `confirmed` to `completed` only when:
1. The cohort has finished.
2. Payment is confirmed.
3. Attendance is fully finalized for all cohort sessions.

Main code:
- `app/Services/EnrollmentProgressService.php`
- `app/Console/Commands/SyncEnrollmentCompletionStatusesCommand.php`

Scheduler:
- `academics:sync-enrollment-statuses`

## 6. Certificate Eligibility

Certificate issuance is now based on real academic rules, not only enrollment status.

Current checks:
1. Enrollment must be `confirmed` or `completed`
2. Student account must be linked
3. Payment must be confirmed
4. Cohort must be finished
5. Attendance must be finalized
6. Attendance rate must be greater than or equal to policy minimum
7. Absences must not exceed policy maximum
8. No certificate must already exist for that enrollment

Main code:
- `app/Services/CertificateEligibilityService.php`
- `app/Services/EnrollmentProgressService.php`
- `app/Application/UseCases/Admin/Certificates/GenerateCertificate.php`

## 7. Attendance Policy

Certificate policy is read from `attendance_policies`.

Fields currently used for certificate decisions:
- `min_attendance_percent_for_certificate`
- `max_absences_for_certificate`

Fallback defaults:
- minimum attendance: `80%`
- maximum absences: `3`

Main code:
- `app/Models/AttendancePolicy.php`
- `database/migrations/2026_04_17_090000_add_certificate_rules_to_attendance_policies_table.php`

## 8. Admin Certificate Workspace

The eligible queue now shows only records that truly satisfy certificate rules.

The readiness reason also reflects real blocking causes such as:
- payment not confirmed
- cohort not finished
- attendance not finalized
- attendance below minimum
- absence limit exceeded

Main code:
- `app/Livewire/Admin/Certificates/AdminCertificatesEligibleQueuePage.php`
- `resources/views/livewire/admin/certificates/admin-certificates-eligible-queue-page.blade.php`

## 9. Practical Operations Notes

- A learner may be financially confirmed before the cohort ends.
- A learner may be academically completed before becoming certificate-eligible if attendance is still incomplete in the records.
- Certificate issuance remains an admin action, but eligibility is now enforced by the system.

## 10. Recommended Next Steps

For a fully mature academic workflow, the next recommended additions are:
1. Admin UI to edit attendance policy per cohort
2. Student-facing course progress widget
3. Explicit academic outcome states such as `passed`, `failed_attendance`, `certificate_blocked`
4. Optional auto-issue flow after admin approval of the final cohort closure