Review & Awards

The review process moves applications through stages from initial receipt to final decision. Once awards are granted, disbursements track the financial outflow with categorization for reporting.

Review workflow

Stage transitions

Applications move through the ApplicationStage pipeline:

new → under_review → accepted → (disbursement created)
                   → declined

The ScholarshipService::updateStage() method handles transitions:

public function updateStage(
    ScholarshipApplication $application,
    ApplicationStage $stage,
    ?string $notes = null,
): void;

Each stage transition triggers:

1. Application update — stage field updated, reviewer_notes optionally updated
2. Activity logging — Records the transition on the contact’s timeline
3. Applicant notification — Sends a status email with stage-specific messaging:
   • under_review — “Your application is now under review”
   • accepted — “Your application has been accepted”
   • declined — “Your application has been declined”

Granting awards

The ScholarshipService::awardScholarship() method handles the full award process:

public function awardScholarship(ScholarshipApplication $application): Disbursement;

This method:

1. Accepts the application — Calls updateStage() with ApplicationStage::Accepted
2. Creates a disbursement — Records the financial outflow linked to the scholarship and contact
3. Logs activity — Records ActivityType::ScholarshipAwarded with the award amount

Example

$disbursement = $scholarshipService->awardScholarship($application);
// Disbursement created for the scholarship's full award amount
// Application stage set to 'accepted'
// Applicant notified via email
// Activity logged on contact timeline

Disbursement model

Disbursements track outgoing payments from a foundation.

Field	Type	Description
id	UUID	Primary key
foundation_id	UUID	Owning foundation
contact_id	UUID?	Recipient contact
scholarship_id	UUID?	Linked scholarship (for scholarship awards)
amount	integer	Amount in cents
category	DisbursementCategory	Accounting category
description	string?	Description of the disbursement
disbursed_at	datetime?	When the payment was made

Disbursement categories

The DisbursementCategory enum provides accounting classification:

Category	Value	Description
Scholarship	scholarship	Scholarship award payment
Grant	grant	Grant to an individual or organization
Operational	operational	Operating expenses
Program	program	Program-related expenses
Admin	admin	Administrative costs

When a scholarship is awarded via awardScholarship(), the category is automatically set to scholarship.

Disbursement relationships

Relationship	Type	Target
foundation()	BelongsTo	Foundation
contact()	BelongsTo	Contact (the recipient)
scholarship()	BelongsTo	Scholarship

API endpoints

Application management

Method	Path	Description
GET	/api/scholarships/{id}/applications	List applications for a scholarship
GET	/api/applications/{id}	Show application details
PATCH	/api/applications/{id}/stage	Update application stage
DELETE	/api/applications/{id}	Delete an application

Disbursement management

Method	Path	Description
GET	/api/disbursements	List all disbursements
POST	/api/disbursements	Create a disbursement
GET	/api/disbursements/{id}	Show a disbursement
DELETE	/api/disbursements/{id}	Delete a disbursement

Connecting scholarships and disbursements

The Scholarship model provides direct access to its disbursements:

$scholarship->disbursements(); // HasMany<Disbursement>

This allows reporting on total funds disbursed per scholarship program, remaining budget (comparing amount * max_awards against actual disbursements), and per-recipient award history.