End-to-End Workflow

This chapter walks through a complete semester lifecycle, showing how all the components from previous chapters work together in practice.

Phase 0: Semester Setup

Staff Actions:

Phase 1: Tutorial/Talk Registration Campaign

Staff Actions:

Student Experience:

Technical Flow:

• Eligibility check via Campaign#evaluate_policies_for happens when user visits the campaign page
• Ineligible users see an error message explaining the reason
• Eligible users see the registration interface (register buttons for FCFS, preference form for preference-based)
• Each registration request creates a Registration::UserRegistration with status pending (preference-based) or confirmed/rejected (FCFS)
• Registration::PolicyEngine evaluates all active policies in order during the initial eligibility check

Phase 2: Preference-Based Allocation (if applicable)

Staff Actions:

• At or after registration deadline, staff triggers campaign.allocate_and_finalize!
• Campaign status transitions: open → closed → processing → completed

Technical Details:

Phase 3: Allocation Materialization

Staff Actions:

• Staff calls campaign.finalize!
• Registration::AllocationMaterializer iterates through all Registration::Item records
• For each item, collects confirmed user IDs and calls registerable.materialize_allocation!(user_ids:, campaign:)

Domain Effects:

Phase 4: Post-Allocation Roster Maintenance

Staff Operations via Roster::MaintenanceService:

Phase 5: Coursework Assessments & Grading

Setup Flow:

Grading Flow:

Publication:

• Staff publishes results by setting assessment.results_published = true

For Talks (Simplified):

Phase 6: Achievement Tracking

Staff Actions:

• Staff creates Achievement records for students
• Examples: blackboard_presentation, class_participation, peer_review
• These augment quantitative points for eligibility determination

Phase 7: Student Performance Materialization

Staff Configuration:

• Staff configures the StudentPerformance::Rule for the lecture (minimum points, required achievements, etc.).
• A background job runs StudentPerformance::Service.compute_and_upsert_all_records!(lecture), which populates or updates the StudentPerformance::Record for every student in the lecture.

Materialized Data in StudentPerformance::Record:

Staff Actions:

• Staff reviews the materialized records to verify correctness
• Staff can trigger manual recomputation if needed
• Records are ready for teacher certification (next phase)

Staff Actions:

• Staff reviews the materialized records to verify correctness
• Staff can trigger manual recomputation if needed
• Records are ready for teacher certification (next phase)

Phase 8: Teacher Certification

Staff Workflow:

Certification Data (StudentPerformance::Certification):

Rule Change Handling:

Recomputation Triggers:

Phase 9: Exam Registration Campaign

Campaign Setup:

Phase 9: Exam Registration Campaign

Pre-Flight Checks:

Campaign Setup:

Student Experience:

• Students see their eligibility status based on their Certification.status
• Only students with status: :passed certifications can successfully register
• Registration is first-come-first-served until capacity is reached
• Students receive immediate confirmation or rejection with a reason

Registration Flow:

graph LR
    A[Student Attempts Registration] --> B[PolicyEngine Evaluates]
    B --> C{Student Performance Policy}
    C --> D[Lookup Certification]
    D --> E{Certification.status}
    E -->|:passed| F[Continue to next policy]
    E -->|:failed| G[Reject: Not eligible]
    E -->|:pending| H[Reject: Certification incomplete]
    F --> I[All Policies Pass]
    I --> J[Confirm Registration]

After Registration Phase:

• Campaign remains open while students register
• When registration deadline is reached, staff calls campaign.close!
• Campaign transitions to processing status
• Staff then proceeds to finalization (Phase 10)

After Registration Phase:

• Campaign remains open while students register
• When registration deadline is reached, staff calls campaign.close!
• Campaign transitions to processing status
• Staff then proceeds to finalization (Phase 10)

Phase 10: Exam Registration Finalization

Pre-Finalization Checks:

Remediation Workflow:

Finalization Process:

Post-Finalization State:

• Exam Roster now contains subset of eligible students who registered (e.g., 85 of 126 eligible)
• Staff views Exam Roster screen to manage participants
• Roster is ready for exam administration (room assignments, grading)

Phase 11: Exam Grading & Grade Schemes

Grading Setup:

Grade Scheme Application:

Final Result:

• Students have both granular points (TaskPoint records) and final grade (Participation#grade_value)

Phase 11: Exam Grading & Grade Schemes

Grading Setup:

Grade Scheme Application:

Final Result:

• Students have both granular points (TaskPoint records) and final grade (Participation#grade_value)

Phase 12: Late Adjustments & Recomputation

System Response:

Phase 12: Late Adjustments & Recomputation

System Response:

Phase 13: Reporting & Administration

Ongoing Activities:

Key Invariants Throughout the Workflow

Phase 13: Reporting & Administration

Ongoing Activities:

Key Invariants Throughout the Workflow

Chronological Summary

Sequence Diagram

sequenceDiagram
    participant Student
    participant Campaign
    participant Solver
    participant Materializer
    participant Rosterable
    participant Assessment
    participant PerfService as StudentPerformance::Service
    participant PerfRecord as StudentPerformance::Record
    participant Teacher
    participant Evaluator as StudentPerformance::Evaluator
    participant Certification as StudentPerformance::Certification
    participant ExamCampaign
    participant Policy as Registration::Policy

    Student->>Campaign: Visit campaign page
    Campaign->>Policy: Evaluate eligibility (registration phase)
    alt Not eligible
        Campaign-->>Student: Show error with reason
    else Eligible
        Campaign-->>Student: Show registration interface
        Student->>Campaign: Submit registration (FCFS or preference)
    end
    Note over Campaign: If preference mode...
    Campaign->>Solver: Run assignment at deadline
    Solver-->>Campaign: Set confirmed/rejected

    Campaign->>Materializer: finalize!
    Materializer->>Rosterable: materialize_allocation!(user_ids)
    Note over Rosterable: Tutorial/Talk rosters updated

    Assessment->>Rosterable: Seed participations from roster
    Student->>Assessment: Submit coursework
    Note over Assessment: Tutors grade → TaskPoints created

    Assessment->>PerfService: Grading events trigger updates
    PerfService->>PerfRecord: compute_and_upsert_record_for(user)
    Note over PerfRecord: Factual record updated (points, achievements)

    rect rgb(255, 245, 235)
    note over Teacher,Certification: Teacher Certification Phase
    Teacher->>Evaluator: bulk_proposals(lecture)
    Evaluator->>PerfRecord: Read all records
    Evaluator-->>Teacher: Generate eligibility proposals
    Teacher->>Teacher: Review proposals
    Teacher->>Certification: Create certifications (passed/failed)
    Note over Certification: All students certified
    end

    rect rgb(235, 245, 255)
    note over Student,Policy: Exam Registration Phase
    Teacher->>ExamCampaign: Attempt to open campaign
    ExamCampaign->>Certification: Pre-flight: verify completeness
    Certification-->>ExamCampaign: All certifications complete
    ExamCampaign->>ExamCampaign: Transition to open

    Student->>ExamCampaign: Visit exam registration page
    ExamCampaign->>Policy: Evaluate student_performance policy
    Policy->>Certification: Lookup certification for student
    Certification-->>Policy: Return status (passed/failed)
    alt Passed certification
        Policy-->>ExamCampaign: Pass result
        ExamCampaign-->>Student: Show register button
        Student->>ExamCampaign: Click register
        ExamCampaign-->>Student: Confirm registration
    else Failed/pending certification
        Policy-->>ExamCampaign: Fail result
        ExamCampaign-->>Student: Show error (not eligible)
    end
    end

    rect rgb(245, 255, 245)
    note over Teacher,Rosterable: Finalization Phase
    Teacher->>ExamCampaign: Trigger finalize!
    ExamCampaign->>Certification: Validate completeness again
    Certification-->>ExamCampaign: All complete
    ExamCampaign->>Rosterable: materialize_allocation!(eligible_user_ids)
    Note over Rosterable: Exam roster materialized
    end

    Note over Assessment: After exam...
    Assessment->>Assessment: Grade exam tasks
    Assessment->>Assessment: Apply grade scheme
    Assessment-->>Student: Final grades published