Architecture & Implementation Book for the Integration of MÜSLI into MaMpf

This book documents the architecture, user-facing features, and implementation plan for the integration of MÜSLI features into MaMpf. It is organized into three main parts:

1. Core Architecture: Documents the backend services, data models, and workflows. This includes:

   • Registration workflows (campaigns, policies, allocation)
   • Preference-based assignment strategy
   • Post-allocation administration patterns
   • Assessments, grading, and eligibility computation
   • The end-to-end lifecycle from enrollment to grading

2. User-Facing Applications: Describes the dashboards and interfaces for students and staff that consume the core architecture.

3. Project Planning: Outlines the high-level implementation plan and migration strategy for integrating these new features into the existing platform.

Use the chapters in the sidebar for deep dives into each topic. This document serves as a quick orientation.

Overview

A high‑level map of the architecture proposed for the integration of MÜSLI into MaMpf. Each later layer depends only on stable persisted results from earlier phases (no hidden cross‑coupling).

flowchart LR
    A[Registration] --> B[Allocation];
    B --> C[Rosters];
    C --> D[Assessments & Grading];
    D --> E[Eligibility];
    E --> F[Exam Registration];
    F --> H[Exam Grading];
    H --> G[Reporting];

Core flow (see End-to-End Workflow):

1. Campaign setup & user registrations (Registration System)
2. Preference assignment (if needed) (Algorithm Details)
3. Allocation materialization to domain rosters (Rosters)
4. Ongoing roster administration (moves, late adds)
5. Coursework assessments, submissions, points & grades (Assessments & Grading)
6. Achievements & eligibility computation (exam gating) (Student Performance)
7. Exam registration (policy gated)
8. Exam assessment creation & grading (Grading Schemes)
9. Dashboards for students & staff (Student Dashboard, Teacher & Editor Dashboard)
10. Reporting, integrity checks (Integrity & Invariants)
11. Roadmap & extensibility (Future Extensions)

Book Structure

Core Architecture

• Overview (this)
• Domain Model
• Registration System
• Rosters
• Assessments & Grading
• Student Performance
• Grading Schemes
• End-to-End Workflow
• Algorithm Details
• Examples & Demos
• Integrity & Invariants
• Future Extensions

User-Facing Applications

• Teacher & Editor Dashboard
• Student Dashboard

Project Planning

• Implementation Plan

Design Tenets

• Single source of truth per concern (e.g., confirmed assignments live in UserRegistrations + domain rosters after materialization).
• Idempotent transitions (finalize!, materialize_allocation!).
• Append/extend rather than mutate history (overrides, policy traces).
• Pluggable strategies & policies

Domain Model

This chapter summarizes principal entities; authoritative behavioral details live in the referenced chapters.

Registration

Rosters

Assessments & Grading

Student Performance & Certification

Grading Schemes

Allocation Algorithm

Linking Concepts

Core Domain Models:

• User - Students, teachers, tutors who participate in the system
• Lecture - A course offering (e.g., "Linear Algebra WS 2024/25")
• Tutorial - A tutorial group within a lecture
• Talk - A student presentation or seminar talk
• Assignment - A homework assignment
• Exam - An exam assessment

How they link to the systems:

Example Flows:

1. Tutorial Registration: Lecture (campaignable) → creates Registration::Campaign → contains Registration::Item wrapping Tutorial (registerable) → students submit Registration::UserRegistration

2. Exam Registration: Lecture (campaignable) → creates Registration::Campaign → contains Registration::Item wrapping Exam (registerable) → students submit Registration::UserRegistration → policies check eligibility

3. Homework Grading: Assignment (pointable) → linked to Assessment::Assessment → contains Assessment::Task → tutors record Assessment::TaskPoint → aggregated into Assessment::Participation

4. Exam Eligibility: Lecture → students complete Assignment assessments → StudentPerformance::Service aggregates points into StudentPerformance::Record → StudentPerformance::Evaluator generates proposals → teacher creates StudentPerformance::Certification → Registration::Policy (kind: student_performance) checks Certification.status when student attempts Exam registration via the lecture's exam campaign

High-Level ERD (Simplified)

erDiagram
    USER ||--o{ REGISTRATION_USER_REGISTRATION : submits
    REGISTRATION_CAMPAIGN ||--o{ REGISTRATION_ITEM : has
    REGISTRATION_ITEM ||--o{ REGISTRATION_USER_REGISTRATION : options
    REGISTRATION_CAMPAIGN ||--o{ REGISTRATION_POLICY : guards
    REGISTRATION_ITEM }o--|| REGISTERABLE : polymorphic
    ASSESSMENT ||--o{ ASSESSMENT_PARTICIPATION : has
    ASSESSMENT ||--o{ TASK : has
    TASK ||--o{ TASK_POINT : points
    ASSESSMENT_PARTICIPATION ||--o{ TASK_POINT : aggregates
    SUBMISSION ||--o{ TASK_POINT : optional
    USER ||--o{ ASSESSMENT_PARTICIPATION : participates
    LECTURE_PERFORMANCE_RECORD }o--|| USER : "factual data"
    LECTURE_PERFORMANCE_RECORD }o--|| LECTURE : "scoped to"
    LECTURE_PERFORMANCE_CERTIFICATION }o--|| USER : "decision for"
    LECTURE_PERFORMANCE_CERTIFICATION }o--|| LECTURE : "scoped to"
    LECTURE_PERFORMANCE_CERTIFICATION }o--|| LECTURE_PERFORMANCE_RECORD : "based on (optional)"
    ACHIEVEMENT }o--|| USER : "accomplished by"
    ACHIEVEMENT }o--|| LECTURE : "belongs to"
    GRADE_SCHEME_SCHEME ||--|| ASSESSMENT : "applies to"

See details:

• Registration System
• Allocation & Rosters
• Assessments & Grading
• Exam Model
• Student Performance
• Grading Schemes
• Algorithm Details

Registration System

Problem Overview

MaMpf needs a flexible registration system to handle:

• Regular courses: Students register for tutorials within a lecture
• Seminars: Students register for talks within a seminar (special type of lecture)
• Mixed scenarios: Combining lecture enrollment with tutorial/talk assignment via a chained process

Solution Architecture

We use a unified system with:

• Registration Campaigns: Time-bounded processes for registration
• Polymorphic Design: Any model can become registerable or campaignable (host campaigns)
• Two-step Chaining: Optional prerequisite campaigns (e.g., must register for seminar before selecting talks) implemented via a prerequisite_campaign policy
• Allocation Persistence: Store the final allocation (confirmed vs rejected) and optional per-item counters
• Strategy Layer: Pluggable solver for preference-based allocation (Min-Cost Flow now; CP-SAT later)
• Domain Materialization (mandatory): After allocation, propagate confirmed assignments back into domain models (e.g., populate talk speakers, tutorial rosters)
• Registration Policies: Composable eligibility rules (student performance, institutional email, prerequisite, etc.)
• Policy Phases: Policies declare a phase: registration, finalization, or both. Only policies applicable to the current phase are evaluated/enforced. See Student Performance → Certification (05-student-performance.md) for how finalization uses Certification.
• Policy Engine: Phase-aware evaluation of ordered active policies; short-circuits on first failure

Registration::Campaign (ActiveRecord Model)

The Registration Process Orchestrator

The main fields and methods of Registration::Campaign are:

Behavior Highlights

• Guards registration window (open?)
• Delegates fine-grained eligibility to ordered RegistrationPolicies via Policy Engine
• Triggers solver (preference-based) after close (often at/after deadline)
• Finalizes and materializes allocation once only (idempotent)

Assigned vs Unassigned

• Assigned: the student has exactly one confirmed Registration::UserRegistration in the campaign after allocation/close.
• Unassigned: the student participated (has registrations) but has zero confirmed entries. On close/finalization, any remaining pending entries are normalized to rejected so the state is explicit.
• No extra tables are required. Helper methods on Registration::Campaign can expose unassigned_user_ids, unassigned_users, and unassigned_count computed from UserRegistration records.

Close vs Finalize

• Close registration: stops intake and edits; transitions open → closed. Used to lock the window early or when the deadline passes automatically.
• Run allocation (preference-based only): triggers solver; transitions closed → processing. FCFS campaigns skip this step (results already determined).
• Finalize results: before materialization, evaluates all active policies whose phase is finalization or both for each confirmed user (via a Registration::FinalizationGuard). A student_performance policy in finalization phase requires Certification=passed for all confirmed users. If any user fails a finalization-phase policy (or has missing/pending certification) the process aborts and status remains processing (or closed for FCFS) for remediation. After passing guards, materializes confirmed results and transitions to completed.
• Planning-only campaigns: close only; do not call finalize!. Results remain in reporting tables and are not materialized. When planning_only is true, finalize!/allocate_and_finalize! are no-ops.
• Lecture performance completeness checks:
  • Campaign save: Warns if any students lack certifications (any phase with student_performance policy)
  • Campaign open: Hard-fails if any students have missing/pending certifications (registration or both phase)
  • Campaign finalize: Hard-fails if any confirmed registrants have missing/pending certifications (finalization or both phase); auto-rejects students with failed certifications

See also: Student Performance → Certification (05-student-performance.md).

Campaign Lifecycle & Freezing Rules

Campaigns transition through several states to ensure data integrity and fair user experience. Certain attributes freeze at specific lifecycle points to prevent inconsistent or unfair changes.

State Definitions:

• draft: Campaign is being configured, not visible to students
• open: Registration window is active, students can register
• closed: Registration window ended (automatically at deadline or manually)
• processing: Allocation algorithm running (preference-based only)
• completed: Results published, rosters materialized

Freezing Rules

Campaign Attributes

Policies

Items

Capacity Constraints

Implementation Notes

Validation Example:

validate :allocation_mode_frozen_after_open, on: :update
validate :policies_frozen_after_open, on: :update
validate :capacity_decrease_respects_confirmed, on: :update

def allocation_mode_frozen_after_open
  if allocation_mode_changed? && !draft?
    errors.add(:allocation_mode, "cannot be changed after campaign opens")
  end
end

Item Removal:

• Check item.user_registrations.exists? before allowing deletion
• Alternative: Soft-delete (set active: false) instead of destroying

UI Feedback:

• Disable/gray out frozen fields in forms
• Show tooltips explaining why changes are blocked
• Display warning before opening campaign: "Settings will be locked after opening"

Example Implementation (Phase-aware planned state)

module Registration
  class Campaign < ApplicationRecord
    belongs_to :campaignable, polymorphic: true
    has_many :registration_items,
             class_name: "Registration::Item",
             dependent: :destroy
    has_many :user_registrations,
             class_name: "Registration::UserRegistration",
             dependent: :destroy
    has_many :registration_policies,
             class_name: "Registration::Policy",
             dependent: :destroy

    enum allocation_mode: { first_come_first_served: 0, preference_based: 1 }
    enum status: { draft: 0, open: 1, closed: 2, processing: 3, completed: 4 }

    validates :title, :registration_deadline, presence: true

    def evaluate_policies_for(user, phase: :registration)
      if phase == :registration
        return Registration::PolicyEngine::Result.new(pass: false, code: :campaign_not_open) unless open?
      end
      engine = Registration::PolicyEngine.new(self)
      engine.eligible?(user, phase: phase)
    end

    def policies_satisfied?(user, phase: :registration)
      evaluate_policies_for(user, phase: phase).pass
    end

    def open_for_registrations?
      open?
    end

    def finalize!
      return false if planning_only?
      return false unless closed? || processing?
      Registration::FinalizationGuard.new(self).check!
      Registration::AllocationMaterializer.new(self).materialize!
      update!(status: :completed)
    end

    def allocate!
      return false unless preference_based? && closed?
      update!(status: :processing)
      Registration::AllocationService.new(self, strategy: :min_cost_flow).allocate!
      true
    end

    def allocate_and_finalize!
      return false if planning_only?
      return false unless allocate!
      finalize!
    end

    def close!
      update!(status: :closed) if status == "open"
    end
  end
end

The system automatically calls close! when registration_deadline is reached via a scheduled job.

Usage Scenarios

• A "Tutorial Registration" campaign is created for a Lecture. It's preference_based and allows students to rank their preferred tutorial slots. Items point to Tutorial. (Admin UI: Tutorial Show (open); Student UI: Show – preference-based, Confirmation)
• A "Talk Assignment" campaign is created for a Lecture (often a seminar). It's preference_based or first_come_first_served and assigns talk slots. Items point to Talk.
• A "Lecture Registration" campaign is created for a Lecture (commonly seminars). It's typically first_come_first_served and enrolls students directly. The single item points to the Lecture. (Student UI: Show – FCFS)
• A "Seminar Enrollment" campaign is created for a Lecture (acting as a seminar). It's first_come_first_served to quickly fill the limited seminar seats. (Student UI: Show – FCFS)
• An "Interest Registration" campaign is created for a Lecture before the term to gauge demand (planning-only). It's first_come_first_served with a very high capacity; when it ends, you do not call finalize!. Results are used for hiring/planning and are not materialized to rosters. (Admin UI: Interest Show (draft))
• An "Exam Registration" campaign is created for an Exam. It is first_come_first_served and may include a student_performance policy (phase: registration or both) for advisory eligibility messaging; finalization enforces Certification=passed only if a finalization-phase student_performance policy exists. Items point to Exam. (Admin UI: Exam Show; Student UI: Show – exam (FCFS); see also action required: institutional email)

Planning-only campaigns (Interest Registration)

Registration::Campaignable (Concern)

The Campaign Host

Responsibilities

• Provides a central point for grouping related campaigns.
• Simplifies finding campaigns related to a specific object (e.g., all registrations for a given lecture).

Example Implementation

# app/models/concerns/registration/campaignable.rb
module Registration
  module Campaignable
    extend ActiveSupport::Concern

    included do
      has_many :registration_campaigns,
               as: :campaignable,
               class_name: "Registration::Campaign",
               dependent: :destroy
    end
  end
end

Implementations Here

• Lecture: Hosts campaigns for its tutorials or talks.
• Exam: Hosts a campaign for exam seat registration.

Registration::Item (ActiveRecord Model)

The Selectable Catalog Entry

The main fields and methods of Registration::Item are:

module Registration
  class Item < ApplicationRecord
    belongs_to :registration_campaign,
               class_name: "Registration::Campaign"
    belongs_to :registerable, polymorphic: true
    has_many :user_registrations,
             class_name: "Registration::UserRegistration",
             dependent: :destroy

    def assigned_users
      user_registrations.confirmed.includes(:user).map(&:user)
    end
  end
end

Usage Scenarios

Each scenario below is the item-side view of the campaign types listed earlier. The Registration::Item belongs to the associated campaign and wraps the concrete registerable record that users ultimately get assigned to.

• For a "Tutorial Registration" campaign: A RegistrationItem is created for each Tutorial (e.g., "Tutorial A (Mon 10:00)"). The registerable association points to the Tutorial record.
• For a "Talk Assignment" campaign: A RegistrationItem is created for each Talk (e.g., "Talk: Machine Learning Advances"). The registerable association points to the Talk record.
• For a "Lecture Registration" campaign: A RegistrationItem is created for the lecture itself. The registerable association points to the Lecture record. This will be useful mostly when the lecture is a seminar. Lecture then has a dual role: as campaignable and as registerable.
• For an "Exam Registration" campaign: A RegistrationItem is created for the exam itself. The registerable association points to the Exam record. The campaign's campaignable is the parent Lecture. Each exam (Hauptklausur, Nachklausur, Wiederholungsklausur) gets its own campaign hosted by the lecture, with that exam as the sole registerable item.

Registration::Registerable (Concern)

The Registration Target

Responsibilities

• Provide a capacity (fixed column or computed).
• Implement materialize_allocation!(user_ids:, campaign:) to apply confirmed results idempotently.
• Remain agnostic of solver or eligibility logic.

Not Responsibilities

• Eligibility checks (policies handle that).
• Storing pending registrations (that’s UserRegistration).
• Orchestrating allocation (that's the Registration::Campaign).

Public Interface

Example Implementation

# app/models/concerns/registration/registerable.rb
module Registration
  module Registerable
    extend ActiveSupport::Concern

    def capacity
      self[:capacity] || raise(NotImplementedError, "#{self.class} must define #capacity")
    end

    def allocated_user_ids
      raise NotImplementedError, "#{self.class} must implement #allocated_user_ids to delegate to roster"
    end

    def remaining_capacity
      [capacity - allocated_user_ids.size, 0].max
    end

    def full?
      remaining_capacity.zero?
    end

    def materialize_allocation!(user_ids:, campaign:)
      raise NotImplementedError, "#{self.class} must implement #materialize_allocation!"
    end
  end
end

Implementation Details

The Registration::Item model uses belongs_to :registerable, polymorphic: true. Any model that includes the Registration::Registerable concern (e.g., Tutorial, Talk) becomes a valid target for this association.

The materialize_allocation! method is the most critical part of the interface. It is responsible for taking the final list of user_ids from the allocation process and persisting them into the domain model's own roster.

This method must be idempotent, meaning running it multiple times with the same user_ids and campaign produces the same result. A common pattern is to first remove all roster entries associated with the given campaign and then add the new ones, all within a single database transaction. Concrete examples are shown in the Tutorial and Talk sections later in this document.

The allocated_user_ids method must be implemented by each registerable model to delegate to its roster system. This returns the current materialized roster (domain data), as opposed to Registration::Item#assigned_users which returns users with confirmed registrations (registration system data). After finalization, these should match.

Usage Scenarios

• A Tutorial includes Registerable to manage its student roster.
• A Talk includes Registerable to designate students as its speakers.
• A Lecture (acting as a seminar) includes Registerable to manage direct enrollment.
• A future Exam model would include Registerable to manage allocation for an exam.

Registration::UserRegistration (ActiveRecord Model)

A User's Application for an Item

The main fields and methods of Registration::UserRegistration are:

Behavior Highlights

• The status tracks the lifecycle: pending (awaiting allocation), confirmed (successful), or rejected (unsuccessful).
• The preference_rank is only used in preference_based campaigns and must be unique per user within a campaign.
• In first_come_first_served mode, a registration is typically created directly with confirmed status if capacity allows.
• Business logic should enforce that a user can only have one confirmed registration per campaign.

Example Implementation

module Registration
  class UserRegistration < ApplicationRecord
    belongs_to :user
    belongs_to :registration_campaign,
               class_name: "Registration::Campaign"
    belongs_to :registration_item,
               class_name: "Registration::Item"

    enum status: { pending: 0, confirmed: 1, rejected: 2 }

    validates :preference_rank,
              presence: true,
              if: -> { registration_campaign.preference_based? }
    validates :preference_rank,
              uniqueness: { scope: [:user_id, :registration_campaign_id] },
              allow_nil: true
  end
end

Usage Scenarios

• Preference-based: Alice submits two Registration::UserRegistration records for a campaign: one for "Tutorial A" with preference_rank: 1, and one for "Tutorial B" with preference_rank: 2. Both have status: :pending.
• First-Come-First-Served: Bob registers for the "Seminar Algebraic Geometry". A single Registration::UserRegistration record is created with status: :confirmed immediately, as long as there is capacity.

First-Come-First-Served Workflow

In FCFS mode, registration status is determined immediately upon submission:

Controller Logic (recommended):

# app/controllers/registration/user_registrations_controller.rb
def create
  campaign = Registration::Campaign.find(params[:campaign_id])
  item = campaign.registration_items.find(params[:item_id])

  return unless campaign.policies_satisfied?(current_user, phase: :registration)

  status = item.remaining_capacity > 0 ? :confirmed : :rejected

  Registration::UserRegistration.create!(
    user: current_user,
    registration_campaign: campaign,
    registration_item: item,
    status: status,
    preference_rank: nil  # Not used in FCFS
  )
end

Key Differences from Preference-Based:

Capacity Enforcement:

• Check item.remaining_capacity before creating the registration
• If capacity exhausted, create with status: :rejected (no waitlist)
• Alternatively, return error and don't create record at all

Registration::Policy (ActiveRecord Model)

A Composable Eligibility Rule

The main fields and methods of Registration::Policy are:

Behavior Highlights

• Policies are evaluated in ascending position order.
• The PolicyEngine short-circuits on the first policy that fails.
• Returns a structured outcome ({ pass: true/false, ... }) for clear feedback.
• Adding a new rule type involves adding to the kind enum and implementing its logic in evaluate, with no schema changes required.

The evaluate method of a policy returns a hash. While the top-level structure is consistent (containing a boolean pass key), individual policies can enrich the result with a details hash, providing context-specific information. This is particularly useful for complex rules like student performance eligibility.

Example Implementation

module Registration
  class Policy < ApplicationRecord
    belongs_to :registration_campaign,
               class_name: "Registration::Campaign"
    acts_as_list scope: :registration_campaign

    enum kind: {
      student_performance: "student_performance",
      institutional_email: "institutional_email",
      prerequisite_campaign: "prerequisite_campaign",
      custom_script: "custom_script"
    }

    enum phase: {
      registration: "registration",
      finalization: "finalization",
      both: "both"
    }

    scope :active, -> { where(active: true) }
    scope :for_phase, ->(p) { where(phase: ["both", p.to_s]) }

    def evaluate(user)
  case kind.to_sym
  when :student_performance then eval_student_performance(user)
      when :institutional_email then eval_email(user)
      when :prerequisite_campaign then eval_prereq(user)
      when :custom_script then eval_custom(user)
      else fail_result(:unknown_kind, "Unknown policy kind")
      end
    end

    private

    def pass_result(code = :ok, details = {})
      { pass: true, code: code, details: details }
    end

    def fail_result(code, message, details = {})
      { pass: false, code: code, message: message, details: details }
    end

    def eval_student_performance(user)
      lecture = Lecture.find(config["lecture_id"])

      cert = StudentPerformance::Certification.find_by(lecture: lecture, user: user)

      if cert&.passed?
        pass_result(:certification_passed)
      else
        fail_result(
          :certification_not_passed,
          "Lecture performance certification required",
          certification_status: cert&.status || :missing
        )
      end
    end

    def eval_email(user)
      allowed = Array(config["allowed_domains"])
      return pass_result(:no_constraint) if allowed.empty?
      domain = user.email.to_s.split("@").last
      if allowed.include?(domain)
        pass_result(:domain_ok)
      else
        fail_result(:domain_blocked, "Email domain not allowed",
                    domain: domain, allowed: allowed)
      end
    end

    def eval_prereq(user)
      prereq_id = config["prerequisite_campaign_id"]
      return fail_result(:missing_prerequisite_id, "No prerequisite specified") unless prereq_id

      prereq_campaign = Registration::Campaign.find_by(id: prereq_id)
      return fail_result(:prerequisite_not_found, "Prerequisite campaign not found") unless prereq_campaign

      lecture = prereq_campaign.campaignable
      ok = lecture.respond_to?(:roster) && lecture.roster.include?(user)

      ok ? pass_result(:prerequisite_ok) : fail_result(:prerequisite_missing, "Not on prerequisite roster")
    end

    def eval_custom(_user)
      pass_result(:custom_not_implemented)
    end
  end
end

Policy Result Reference

Each policy kind returns a standardized result hash with optional details. The following table documents the expected details keys for each policy kind:

All results include:

• pass (boolean): Whether the policy passed
• code (symbol): Machine-readable result code (e.g., :certification_passed, :domain_blocked)
• message (string, optional): Human-readable message (only on failure)
• details (hash, optional): Additional context as documented above

Why JSONB for Policy.config?

Policies are composable and heterogeneous. Each kind needs different parameters (domains list, lecture reference, prerequisite campaign id, future custom scripts). Using JSONB for config avoids schema churn and lets us:

• Add new policy kinds without migrations.
• Evolve per-kind parameters independently.
• Keep the public API stable (kind, config), while the typed UI and per-kind validations enforce structure.

Constraints and guardrails:

• The UI is typed per kind; users never edit raw JSON.
• Models validate allowed keys and shapes per kind.
• Index JSONB keys if needed for queries (e.g., config ->> 'lecture_id').
• Only minimal data belongs here. For exam eligibility, thresholds and criteria live in StudentPerformance::Rule; the policy stores only { "lecture_id": <id> }.

See UI: Policies tab in Exam Show.

Usage Scenarios

• Email constraint: kind: :institutional_email, phase: :registration, config: { "allowed_domains": ["uni.edu"] }
• Lecture performance gate (advisory + enforcement): kind: :student_performance, phase: :both, config: { "lecture_id": 42 }
• Prerequisite: kind: :prerequisite_campaign, phase: :registration, config: { "prerequisite_campaign_id": 55 }

Registration::PolicyEngine (Service Object)

The Eligibility Pipeline

Public Interface

Behavior Highlights

• Iterates policies in position order.
• Stops at the first failure (fast fail).
• Returns a structured Result object containing the pass/fail status, the policy that failed (if any), and a full trace of all evaluations.
• This Result object is used by Registration::Campaign#evaluate_policies_for to provide clear feedback to the UI.

Example Implementation

module Registration
  class PolicyEngine
    Result = Struct.new(:pass, :failed_policy, :trace, keyword_init: true)

    def initialize(campaign)
      @campaign = campaign
    end

    def eligible?(user, phase: :registration)
      trace = []
      applicable = @campaign.registration_policies.active.for_phase(phase).order(:position)
      applicable.each do |policy|
        outcome = policy.evaluate(user)
        trace << { policy_id: policy.id, kind: policy.kind, phase: policy.phase, outcome: outcome }
        return Result.new(pass: false, failed_policy: policy, trace: trace) unless outcome[:pass]
      end
      Result.new(pass: true, failed_policy: nil, trace: trace)
    end
  end
end

Usage Scenarios

• A trace showing two passed registration-phase policies and one failed policy produces a clear message to the user.
• A finalization guard iterates confirmed users with phase: :finalization; any failure aborts materialization.

Registration::AllocationService (Service Object)

The Allocation Solver

Public Interface

Responsibilities

• Takes a Registration::Campaign as input.
• Gathers all pending Registration::UserRegistration records with their preference ranks.
• Gathers all Registration::Item records with their capacities.
• Executes a specific allocation strategy (e.g., Min-Cost Flow) to find an optimal assignment.
• Updates the status of each Registration::UserRegistration to either :confirmed or :rejected based on the solver's output.

Not Responsibilities

• It does not materialize the results into the final domain models (e.g., Tutorial rosters). That is handled by the AllocationMaterializer called within finalize!. This keeps the concerns of "solving the assignment" and "persisting the results" separate.

Implementation Details

The service uses a Strategy Pattern to delegate the actual solving to a dedicated class based on the chosen strategy. This allows for different solver implementations (e.g., Min-Cost Flow, CP-SAT) to be used interchangeably.

For a detailed breakdown of the graph modeling and solver implementation, see the Allocation Algorithm Details chapter.

Example Implementation

# This service acts as a dispatcher for different solver strategies.
module Registration
  class AllocationService
    def initialize(campaign, strategy: :min_cost_flow, **opts)
      @campaign = campaign
      @strategy = strategy
      @opts = opts
    end

    def allocate!
      solver =
        case @strategy
        when :min_cost_flow then Registration::Solvers::MinCostFlow.new(@campaign, **@opts)
        # when :cp_sat then Registration::Solvers::CpSat.new(@campaign, **@opts) # Future
        else
          raise ArgumentError, "Unknown strategy: #{@strategy}"
        end
      solver.run
    end
  end
end

# Example of a concrete solver strategy class.
# See 07-algorithm-details.md for the full implementation.
module Registration
  module Solvers
    class MinCostFlow
      def initialize(campaign, **opts)
        @campaign = campaign
        # ... gather users, items, preferences ...
      end

      def run
        # 1. Build the graph model for the solver
        # 2. Solve the model
        # 3. Persist the results back to Registration::UserRegistration statuses
      end
    end
  end
end

Usage Scenarios

• After the deadline for a preference_based tutorial registration campaign, a background job calls Registration::AllocationService.new(campaign).allocate!. The service runs the solver and updates thousands of Registration::UserRegistration records to either :confirmed or :rejected.
• An administrator manually triggers the assignment for a seminar's talk selection via a button in the UI, which in turn calls this service.

Registration::AllocationMaterializer (Service Object)

The Roster Populator

Public Interface

Responsibilities

• Gathers all confirmed Registration::UserRegistration records for the campaign.
• Groups them by their Registration::Item.
• For each Registration::Item, it calls materialize_allocation! on the underlying registerable object, passing the final list of user IDs.
• This process is the crucial hand-off from the temporary registration system to the permanent domain models.

Example Implementation

module Registration
  class AllocationMaterializer
    # Missing top-level docstring, please formulate one yourself 😁
    def initialize(campaign)
      @campaign = campaign
    end

    def materialize!
      registrations_by_item = @campaign.user_registrations
                                       .confirmed
                                       .includes(:registration_item)
                                       .group_by(&:registration_item)

      ActiveRecord::Base.transaction do
        registrations_by_item.each do |item, registrations|
          user_ids = registrations.map(&:user_id)
          item.registerable.materialize_allocation!(user_ids: user_ids, campaign: @campaign)
        end
      end
    end
  end
end

Registration::FinalizationGuard (Service Object)

The Finalization Gatekeeper

Public Interface

Example Implementation

module Registration
  class FinalizationGuard
    def initialize(campaign)
      @campaign = campaign
    end

    def check!
      policies = @campaign.registration_policies.active.for_phase(:finalization).order(:position)
      return true if policies.empty?

      confirmed = @campaign.user_registrations.confirmed.includes(:user)

      confirmed.each do |ur|
        user = ur.user
        policies.each do |policy|
          if policy.kind == "student_performance"
            lecture = Lecture.find(policy.config["lecture_id"])
            cert = StudentPerformance::Certification.find_by(lecture: lecture, user: user)

            if cert.nil? || cert.pending?
              raise StandardError, "Finalization blocked: certification missing or pending for user #{user.id}"
            elsif cert.failed?
              ur.update!(status: :rejected)
              next
            end
          else
            outcome = policy.evaluate(user)
            unless outcome[:pass]
              raise StandardError, "Finalization blocked by policy #{policy.id} (#{policy.kind})"
            end
          end
        end
      end
      true
    end
  end
end

Behavior Highlights

• Auto-reject failed certifications: Students with StudentPerformance::Certification.status == :failed are automatically moved to rejected status
• Hard-fail on missing/pending: If any confirmed student has no certification or status: :pending, raise error and block finalization
• Remediation UI trigger: The error message should trigger UI showing which students need certification resolution
• Other policies: Evaluated normally; any failure blocks finalization

See also: Student Performance → Certification and Pre-flight Validation (05-student-performance.md).

Enhanced Domain Models

The following sections describe how existing MaMpf models will be enhanced to integrate with the registration system.

User (Enhanced)

The Registrant

Example Implementation

class User < ApplicationRecord
  has_many :user_registrations,
       class_name: "Registration::UserRegistration",
       dependent: :destroy
  has_many :registration_campaigns,
       through: :user_registrations
  has_many :registration_items,
       through: :user_registrations
end

Lecture (Enhanced)

The Primary Host and Seminar Target

Dual Role

• As Registration::Campaignable: Can organize tutorial registration or talk selection campaigns.
• As Registration::Registerable: Students can register for the lecture itself (common for seminars).

Example Implementation

class Lecture < ApplicationRecord
  include Registration::Campaignable      # Can host campaigns for tutorials/talks
  include Registration::Registerable      # Can be registered for (seminar enrollment)
    # ... existing code ...

    # Implements the contract from the Registerable concern
    def materialize_allocation!(user_ids:, campaign:)
        # This method is the hand-off point to the roster management system.
        # Its responsibility is to take the final list of user IDs and
        # persist them as the official roster for this lecture (seminar),
        # sourced from this specific campaign.
        #
        # The concrete implementation using the Roster::Rosterable concern is detailed
        # in the "Allocation & Rosters" chapter.
    end
end

Tutorial (Enhanced)

A Common Registration Target

Example Implementation

class Tutorial < ApplicationRecord
  include Registration::Registerable
    # ... existing code ...

    # Implements the contract from the Registerable concern
    def materialize_allocation!(user_ids:, campaign:)
        # This method is the hand-off point to the roster management system.
        # Its responsibility is to take the final list of user IDs and
        # persist them as the official roster for this tutorial, sourced
        # from this specific campaign.
        #
        # The concrete implementation using the Roster::Rosterable concern is detailed
        # in the "Allocation & Rosters" chapter.
    end
end

Talk (Enhanced)

A Target for Speaker Allocation

Example Implementation

class Talk < ApplicationRecord
  include Registration::Registerable
    # ... existing code ...

    # Implements the contract from the Registerable concern
    def materialize_allocation!(user_ids:, campaign:)
        # Similar to the Tutorial, this method hands off the final list
        # of speakers to the roster management system.
        #
        # The concrete implementation using the Roster::Rosterable concern is detailed
        # in the "Allocation & Rosters" chapter.
    end
end

Campaign Lifecycle (State Diagram)

stateDiagram-v2
    [*] --> draft
    draft --> open : open
    open --> closed : close (manual or at deadline)
    closed --> completed : finalize! (optional)

    note right of closed
        Regular FCFS campaigns: finalize to materialize rosters.
        Planning-only: stay in closed, skip finalize.
    end note

ERD

erDiagram
  "Registration::Campaign" ||--o{ "Registration::Item" : has
  "Registration::Campaign" ||--o{ "Registration::Policy" : has
  "Registration::Campaign" ||--o{ "Registration::UserRegistration" : has
  "Registration::Item" ||--o{ "Registration::UserRegistration" : has
  USER ||--o{ "Registration::UserRegistration" : submits
  "Registration::Item" }o--|| REGISTERABLE : polymorphic
  "Registration::Campaign" }o--|| CAMPAIGNABLE : polymorphic

Preference-Based State Diagram

stateDiagram-v2
    [*] --> draft: Campaign created
    draft --> open: Admin opens campaign
    open --> closed: Admin closes OR deadline reached
    closed --> processing: Allocation runs
    processing --> completed: Admin finalizes
    
    note right of draft
        Admin configures items,
        policies, deadline
    end note
    
    note right of open
        Users submit preferences;
        all status: pending
    end note
    
    note right of processing
        Registration closed;
        run allocation solver
    end note
    
    note right of completed
        Allocation finalized;
        rosters materialized
    end note

Sequence Diagram (Preference-Based Flow)

This diagram shows the typical lifecycle for a preference-based campaign.

sequenceDiagram
    actor User
    participant Controller
    participant Campaign as Registration::Campaign
    participant UserReg as Registration::UserRegistration
    actor Job as Background Job
    participant AllocationSvc as Registration::AllocationService
    participant Solver as Registration::Solvers::MinCostFlow
    participant Materializer as Registration::AllocationMaterializer
    participant RegTarget as Registerable (e.g., Tutorial)

    rect rgb(235, 245, 255)
    note over User,Controller: Registration phase (campaign is open)
    User->>Controller: Visit campaign page
    Controller->>Campaign: evaluate_policies_for(user, phase: :registration)
    alt eligible
        Controller-->>User: Show preference ranking form
        User->>Controller: Submit preferences
        loop for each preference
            Controller->>UserReg: create(user_id, item_id, rank)
        end
        Controller-->>User: Preferences saved
    else not eligible
        Controller-->>User: Show reason from PolicyEngine
    end
    end

    note over User,Job: Deadline passes

    rect rgb(255, 245, 235)
    note over Job,RegTarget: Allocation & finalization
    Job->>Campaign: allocate_and_finalize!
    Campaign->>Campaign: update!(status: :closed)
    Campaign->>AllocationSvc: new(campaign).allocate!
    AllocationSvc->>Solver: new(campaign).run()
    note right of Solver: Build graph, solve, persist statuses
    Solver->>UserReg: update_all(status: confirmed/rejected)
    Campaign->>Campaign: update!(status: :processing)
    Campaign->>Campaign: finalize!
    Campaign->>Materializer: new(campaign).materialize!
    Materializer->>RegTarget: materialize_allocation!(user_ids, campaign)
    note right of RegTarget: Update roster (idempotent)
    Campaign->>Campaign: update!(status: :completed)
    end

FCFS State Diagram

stateDiagram-v2
    [*] --> draft: Campaign created
    draft --> open: Admin opens campaign
    open --> closed: Admin closes OR deadline reached
    closed --> completed: Admin finalizes (optional)
    
    note right of draft
        Admin configures items,
        policies, deadline
    end note
    
    note right of open
        Users submit registrations;
        immediate confirm/reject
    end note
    
    note right of closed
        Registration closed;
        results visible
    end note
    
    note right of completed
        For planning-only:
        skip finalize!
        
        For materialization:
        finalize! applies to rosters
    end note

Sequence Diagram (FCFS Flow)

This diagram shows the lifecycle for a first-come-first-served campaign.

sequenceDiagram
    actor Student
    participant UI as Student UI
    participant Controller as UserRegistrationsController
    participant Campaign
    participant Item
    participant UserReg as UserRegistration
    participant PolicyEngine
    participant Roster as Domain Roster

    rect rgb(235, 245, 255)
    note over Student,PolicyEngine: Registration phase (campaign is open)
    Student->>UI: Visit campaign page
    UI->>Controller: GET /campaigns/:id
    Controller->>Campaign: find(campaign_id)
    Controller->>Campaign: open_for_registrations?
    Campaign-->>Controller: true
    
    Controller->>Campaign: evaluate_policies_for(user, phase: :registration)
    Campaign->>PolicyEngine: eligible?(user, phase: :registration)
    PolicyEngine-->>Campaign: Result(pass: true/false, ...)
    Campaign-->>Controller: Result
    
    alt policies fail
        Controller-->>UI: Ineligible state
        UI-->>Student: Show error: "Not eligible (reason)"
    else policies pass
        Controller-->>UI: Show register buttons
        UI-->>Student: Display available items
        
        Student->>UI: Click "Register for Item X"
        UI->>Controller: POST /campaigns/:id/user_registrations
        
        Controller->>Item: find(item_id)
        Controller->>Item: remaining_capacity
        Item-->>Controller: capacity count
        
        alt capacity available
            Controller->>UserReg: create!(status: :confirmed, ...)
            UserReg-->>Controller: registration record
            Controller-->>UI: Success
            UI-->>Student: "Registered successfully"
        else capacity exhausted
            Controller->>UserReg: create!(status: :rejected, ...)
            UserReg-->>Controller: registration record
            Controller-->>UI: Info: "No capacity"
            UI-->>Student: "Item full, registration rejected"
        end
    end
    end
    
    note over Student,Roster: Later: Admin closes campaign
    
    rect rgb(255, 245, 235)
    note over Student,Roster: View results (processing state)
    Student->>UI: View results
    UI->>Controller: GET /campaigns/:id
    Controller->>Campaign: status
    Campaign-->>Controller: :closed, :processing, or :completed
    Controller-->>UI: Show campaign with status
    UI-->>Student: Display confirmed/rejected
    end
    
    rect rgb(245, 255, 235)
    note over Controller,Roster: Optional: Admin finalizes (materialization)
    Controller->>Campaign: finalize!
    Campaign->>Campaign: evaluate_policies_for(confirmed_users, phase: :finalization)
    alt finalization policies fail
        Campaign-->>Controller: Error (stays in :processing)
    else finalization policies pass
        Campaign->>Item: materialize_allocation!(confirmed_user_ids)
        Item->>Roster: Update domain roster
        Roster-->>Item: Done
        Item-->>Campaign: Done
        Campaign->>Campaign: update!(status: :completed)
        Campaign-->>Controller: Success
    end
    end

Proposed Folder Structure

To keep the new components organized according to Rails conventions, the new files would be placed as follows:

app/
├── models/
│   ├── concerns/
│   │   └── registration/
│   │       ├── campaignable.rb
│   │       └── registerable.rb
│   └── registration/
│       ├── campaign.rb
│       ├── item.rb
│       ├── policy.rb
│       └── user_registration.rb
│
└── services/
  └── registration/
    ├── solvers/
    │   ├── min_cost_flow.rb
    │   └── cp_sat.rb (future)
    ├── allocation_service.rb
    ├── allocation_materializer.rb
    └── policy_engine.rb

This structure separates the ActiveRecord models, shared concerns, and business logic (service objects and solvers) into their conventional directories.

Key Files

• app/models/registration/campaign.rb - Orchestrates the registration process
• app/models/registration/user_registration.rb - Records user registrations (registration requests)
• app/models/registration/policy.rb - Defines eligibility rules
• app/services/registration/allocation_service.rb - Runs allocation solver
• app/services/registration/allocation_materializer.rb - Persists results to domain models

Database Tables

• registration_campaigns - Campaign orchestration records
• registration_items - Catalog entries linking campaigns to registerables
• registration_user_registrations - User registration request records with status and preference rank
• registration_policies - Eligibility rules with kind, phase, config, and position

Rosters

Problem Overview

• After campaigns are completed and allocations are materialized into domain models, staff must maintain real rosters.

Managing unassigned candidates

• View unassigned candidates: from the completed Campaign Show or on the Roster Overview via a right-side panel "Candidates from campaign" showing only users unassigned in that campaign.
• Inspect context: for preference-based campaigns, show each student's top 3 original preferences inline, with a way to view the full list on demand.
• Actions:
  • Assign to group: place the student into a specific tutorial if capacity permits.
  • Move: standard roster operations continue to work across groups.

Solution Architecture

• Canonical Source: Domain rosters on registerable models (e.g., Tutorial.students, Talk.speakers).
• Uniform API: A Roster::Rosterable concern provides a consistent interface (roster_user_ids, replace_roster!, etc.).
• Single Service: A Roster::MaintenanceService handles atomic moves, adds, and removals with capacity checks and logging.
• Campaign-Independent: Actions operate directly on Roster::Rosterable models; no campaign context is needed for manual changes.
• Fast Dashboards: The maintenance service can update denormalized counters like Registration::Item.assigned_count to keep UIs in sync.
• Auditing (Future Enhancement): The service includes a log() method as a hook for future auditing. This can be implemented later to write to a dedicated audit trail (e.g., a RosterChangeEvent model or using a gem like PaperTrail). This would provide a full history of all manual roster modifications, separate from the immutable record of the initial automated assignment stored in Registration::UserRegistration.
• Exam-specific finalization: When materializing exam rosters from a campaign, eligibility is revalidated at finalize-time; registrants who became ineligible are excluded unless an override exists.

Roster::Rosterable (Concern)

The Universal Roster API

Public Interface & Contract

Behavior Highlights

• Explicit Contract: The concern raises a NotImplementedError if an including class fails to override required methods (#roster_user_ids, #replace_roster!, #roster_entries, #mark_campaign_source!), ensuring the contract is met.
• Idempotent: Calling replace_roster! with the same set of IDs should result in no change.
• Registration Integration: Provides allocated_user_ids and materialize_allocation! to satisfy the Registration::Registerable interface, allowing rosters to be managed by the registration system.
• Campaign Tracking: The materialize_allocation! method preserves manually-added roster entries while replacing campaign-sourced entries, using the source_campaign field on join table records. // ...existing code...

Example Implementation

# filepath: app/models/concerns/roster/rosterable.rb
module Roster
  module Rosterable
    extend ActiveSupport::Concern

    def roster_user_ids
      raise NotImplementedError, "#{self.class.name} must implement #roster_user_ids"
    end

    def replace_roster!(user_ids:)
      raise NotImplementedError, "#{self.class.name} must implement #replace_roster!"
    end

    def allocated_user_ids
      roster_user_ids
    end

    def materialize_allocation!(user_ids:, campaign:)
      transaction do
        current_ids = roster_user_ids
        campaign_sourced_ids = current_ids.select do |uid|
          roster_entries.exists?(user_id: uid, source_campaign: campaign)
        end

        other_ids = current_ids - campaign_sourced_ids
        new_ids = (other_ids + user_ids).uniq

        replace_roster!(user_ids: new_ids)
        mark_campaign_source!(user_ids, campaign)
      end
    end

    private

    def add_user_to_roster!(user_id)
      ids = roster_user_ids
      return if ids.include?(user_id)
      replace_roster!(user_ids: ids + [user_id])
    end

    def remove_user_from_roster!(user_id)
      replace_roster!(user_ids: roster_user_ids - [user_id])
    end

    def roster_entries
      raise NotImplementedError, "#{self.class.name} must implement #roster_entries for campaign tracking"
    end

    def mark_campaign_source!(user_ids, campaign)
      raise NotImplementedError, "#{self.class.name} must implement #mark_campaign_source! for campaign tracking"
    end
  end
end

Usage Scenarios

• Tutorial and Talk both include Roster::Rosterable.
• Tutorial implements roster_user_ids by reading from a new tutorial_memberships join table (to be created).
• Talk implements replace_roster! using its existing speaker_talk_joins association.

Roster::MaintenanceService

Staff Maintenance

Public Interface

Behavior Highlights

• Transactional: All operations, especially move_user!, are performed within a database transaction to ensure atomicity.
• Capacity Enforcement: Enforces the capacity of the target Roster::Rosterable unless an allow_overfill: true flag is passed.
• Auditing Hook: Calls a log() method to provide a hook for future audit trail implementation.
• Denormalization: Can update denormalized counters like Registration::Item.assigned_count to keep dashboards in sync.

Example Implementation

# filepath: app/services/roster/maintenance_service.rb
class Roster::MaintenanceService
  def initialize(actor:)
    @actor = actor
  end

  def move_user!(user_id:, from:, to:, allow_overfill: false, reason: nil)
    raise ArgumentError, "type mismatch" unless from.class == to.class
    ActiveRecord::Base.transaction do
      enforce_capacity!(to) unless allow_overfill
      from.send(:remove_user_from_roster!, user_id)
      to.send(:add_user_to_roster!, user_id)
      touch_counts!(from, to)
      log(:move, user_id: user_id, from: from, to: to, reason: reason)
    end
  end

  def add_user!(user_id:, to:, allow_overfill: false, reason: nil)
    ActiveRecord::Base.transaction do
      enforce_capacity!(to) unless allow_overfill
      to.send(:add_user_to_roster!, user_id)
      touch_counts!(to)
      log(:add, user_id: user_id, to: to, reason: reason)
    end
  end

  def remove_user!(user_id:, from:, reason: nil)
    ActiveRecord::Base.transaction do
      from.send(:remove_user_from_roster!, user_id)
      touch_counts!(from)
      log(:remove, user_id: user_id, from: from, reason: reason)
    end
  end

  private

  def enforce_capacity!(rosterable)
    raise "Capacity reached" if rosterable.full?
  end

  def touch_counts!(*rosterables)
    # Logic to find associated Registration::Items and update assigned_count
  end

  def log(action, **data)
    # Hook for future auditing (e.g., create RosterChangeEvent record)
  end
end

Usage Scenarios

• Moving a student: An administrator moves a student from a full tutorial to one with free space.

  service = Roster::MaintenanceService.new(actor: current_admin)
  tutorial_from = Tutorial.find(1)
  tutorial_to = Tutorial.find(2)
  student_id = 123
  service.move_user!(user_id: student_id, from: tutorial_from, to: tutorial_to, reason: "Balancing class sizes")
  

• Adding a late-comer: A student who missed the deadline is manually added to a tutorial.

  service = Roster::MaintenanceService.new(actor: current_admin)
  tutorial = Tutorial.find(5)
  student_id = 456
  service.add_user!(user_id: student_id, to: tutorial, reason: "Late registration approved by professor")
  

• Removing a dropout: A student officially drops the course.

  service = Roster::MaintenanceService.new(actor: current_admin)
  tutorial = Tutorial.find(3)
  student_id = 789
  service.remove_user!(user_id: student_id, from: tutorial, reason: "Student dropped course")
  

Enhanced Domain Models

The following sections describe how existing MaMpf models are enhanced to integrate with the roster management system by implementing the Rosterable concern.

Tutorial (Enhanced)

A Rosterable Target

Rosterable Implementation

The Tutorial model includes the Roster::Rosterable concern to provide a standard interface for managing its student roster via a join table.

Example Implementation

# filepath: app/models/tutorial.rb
class Tutorial < ApplicationRecord
  include Registration::Registerable
  include Roster::Rosterable

  has_many :tutorial_memberships, dependent: :destroy
  has_many :students, through: :tutorial_memberships, source: :user

  def roster_user_ids
    tutorial_memberships.pluck(:user_id)
  end

  def replace_roster!(user_ids:)
    TutorialMembership.transaction do
      tutorial_memberships.delete_all
      user_ids.each { |uid| tutorial_memberships.create!(user_id: uid) }
    end
  end

  def roster_entries
    tutorial_memberships
  end

  def mark_campaign_source!(user_ids, campaign)
    tutorial_memberships.where(user_id: user_ids)
                       .update_all(source_campaign_id: campaign.id)
  end
end

The tutorial_memberships table should include a source_campaign_id column (nullable) to track which campaign materialized each roster entry.

Talk (Enhanced)

A Rosterable Target

Rosterable Implementation

The Talk model includes the Roster::Rosterable concern to provide a standard interface for managing its speakers.

Example Implementation

# filepath: app/models/talk.rb
class Talk < ApplicationRecord
  include Registration::Registerable
  include Roster::Rosterable

  has_many :speaker_talk_joins, dependent: :destroy
  has_many :speakers, through: :speaker_talk_joins

  def roster_user_ids
    speaker_talk_joins.pluck(:speaker_id)
  end

  def replace_roster!(user_ids:)
    SpeakerTalkJoin.transaction do
      speaker_talk_joins.delete_all
      user_ids.each { |uid| speaker_talk_joins.create!(speaker_id: uid) }
    end
  end

  def roster_entries
    speaker_talk_joins
  end

  def mark_campaign_source!(user_ids, campaign)
    speaker_talk_joins.where(speaker_id: user_ids)
                      .update_all(source_campaign_id: campaign.id)
  end
end

The speaker_talk_joins table should include a source_campaign_id column (nullable) to track which campaign materialized each speaker assignment.

ERD for Roster Implementations

This diagram shows the concrete database relationships for the two example Roster::Rosterable implementations. The Roster::Rosterable concern provides a uniform API over these different underlying structures.

erDiagram
    TUTORIAL ||--o{ TUTORIAL_MEMBERSHIP : "has (to be created)"
    TUTORIAL_MEMBERSHIP }o--|| USER : "links to"

    TALK ||--o{ SPEAKER_TALK_JOIN : "has (existing)"
    SPEAKER_TALK_JOIN }o--|| USER : "links to"

Sequence Diagram

This diagram shows the two distinct phases: the initial, automated materialization of the roster, followed by ongoing manual maintenance by staff.

sequenceDiagram
    actor Admin
    participant Campaign as Registration::Campaign
    participant Materializer as Registration::AllocationMaterializer
    participant RosterService as Roster::MaintenanceService
    participant Rosterable as Roster::Rosterable (e.g., Tutorial)

    rect rgb(235, 245, 255)
    note over Campaign,Rosterable: Phase 1: Automated Materialization
    Campaign->>Materializer: new(campaign).materialize!
    Materializer->>Rosterable: materialize_allocation!(user_ids:, campaign:)
    note right of Rosterable: From Registration::Registerable
    Rosterable->>Rosterable: 1. Query current roster_user_ids
    Rosterable->>Rosterable: 2. Identify campaign-sourced entries
    Rosterable->>Rosterable: 3. Merge with new user_ids
    Rosterable->>Rosterable: 4. Call replace_roster!(merged_ids)
    Rosterable->>Rosterable: 5. Mark new entries with source_campaign_id
    end

    note over Admin, Rosterable: ... time passes ...

    rect rgb(255, 245, 235)
    note over Admin,Rosterable: Phase 2: Manual Roster Maintenance
    Admin->>RosterService: new(actor: admin).move_user!(...)
    RosterService->>Rosterable: from.remove_user_from_roster!(user_id)
    RosterService->>Rosterable: to.add_user_to_roster!(user_id)
    note right of Rosterable: Uses private methods from Roster::Rosterable concern
    end

Proposed Folder Structure

To keep the new components organized, the new files would be placed as follows:

app/
├── models/
│   └── concerns/
│       └── roster/
│           └── rosterable.rb
│
└── services/
    └── roster/
        └── maintenance_service.rb

Key Files

• app/models/concerns/roster/rosterable.rb - Uniform roster API concern
• app/services/roster/maintenance_service.rb - Manual roster modification service

Database Tables

The roster system doesn't introduce new database tables. Instead, it provides a uniform API over existing and to-be-created join tables:

• tutorial_memberships (to be created) - Join table for tutorial student rosters
• speaker_talk_joins (existing) - Join table for talk speaker assignments

Assessments & Grading

Problem Overview

After registrations and allocations are finalized, MaMpf needs to:

• Grade diverse items: Support assignments (with per-task points), exams (points + final grade), and talks (final grade only).
• Handle team submissions: One file uploaded by a team should be graded once, with points automatically distributed to all team members.
• Track granular progress: Break down assignments into tasks (problems), record points per task per student, and aggregate totals.
• Support flexible workflows: Allow draft grading, provisional review, publication, and post-publication adjustments.
• Maintain audit trails: Link graded submissions back to the points awarded for transparency and appeals.

Solution Architecture

We use a unified grading model with clear separation of concerns:

• Canonical Source: Assessment::Assessment acts as the single gradebook for any graded work (Assignment, Exam, Talk, Achievement).
• Dual Capability Model: Two concerns provide orthogonal features:
  • Assessment::Pointable: Enables per-task point tracking ("pointbook" mode).
  • Assessment::Gradable: Enables final grade recording without tasks ("gradebook" mode).
• Participation Tracking: Assessment::Participation records aggregate points, grade, and status per (user, assessment).
• Granular Points: Assessment::Task and Assessment::TaskPoint models support breakdown into graded components when requires_points = true.
• Team-Aware Grading: Assessment::SubmissionGrader implements a fan-out pattern: grade one Submission, create Assessment::TaskPoint records for all team members.
• Roster Integration: Participations are seeded from Roster::Rosterable models (tutorials, talks) or lecture rosters.
• Idempotent Operations: Re-grading the same submission overwrites points consistently; totals are recomputed atomically.

Assessment::Assessment (ActiveRecord Model)

The Gradebook Container

The main fields and methods of Assessment are:

Behavior Highlights

• Acts as the single source of truth for grading configuration
• Guards task creation: tasks exist only when requires_points = true
• Supports two modes: "pointbook" (granular task points) and "gradebook" (final grade only)
• Aggregates student records (participations) which are seeded from rosters

Example Implementation

# filepath: app/models/assessment/assessment.rb
module Assessment
  class Assessment < ApplicationRecord
    belongs_to :assessable, polymorphic: true
    belongs_to :lecture, optional: true

    has_many :tasks, dependent: :destroy, class_name: "Assessment::Task"
    has_many :participations, dependent: :destroy,
      class_name: "Assessment::Participation"
    has_many :task_points, through: :participations,
      class_name: "Assessment::TaskPoint"

  enum status: { draft: 0, open: 1, closed: 2, graded: 3, archived: 4 }

  validates :title, presence: true
  validate :tasks_only_when_requires_points

  def effective_total_points
    total_points.presence || tasks.sum(:max_points)
  end

  def seed_participations_from!(user_ids:)
    existing = participations.pluck(:user_id).to_set
    (user_ids - existing.to_a).each do |uid|
      participations.create!(user_id: uid)
    end
  end

  private

  def tasks_only_when_requires_points
    if tasks.any? && !requires_points
      errors.add(:base, "Tasks are only allowed when requires_points is true")
    end
  end
end

Usage Scenarios

• For a homework assignment: A teacher creates an Assignment record via the "New Assessment" UI. The system creates both the Assignment and a linked Assessment::Assessment record in one transaction, configured with requires_points: true and requires_submission: true. The teacher adds tasks for each problem (P1, P2, P3). Student records are seeded automatically from the tutorial roster.

• For an exam: A teacher creates an Exam record via the "New Assessment" UI. The system creates both the Exam and a linked Assessment::Assessment whose assessable is that exam, with requires_points: true to track per-question scores. After the teacher defines all tasks and grades them, a final grade_value can be computed and stored for each student to represent the official exam grade.

• For a seminar talk: A teacher creates a Talk record in the Content tab. The system automatically creates a linked Assessment::Assessment whose assessable is that talk, with requires_points: false. Later, the teacher records only a final grade for each speaker via the Assessments tab—no tasks or submissions are needed.

• For an achievement: A teacher creates an Achievement record via the "New Assessment" UI (e.g., "Blackboard Presentation" with value_type: boolean). The system creates both the Achievement and a linked Assessment::Assessment, configured with requires_points: false and requires_submission: false. Participations are seeded for all students in the lecture. Tutors mark completion by setting each participation's grade_value to "Pass" or "Fail" (for boolean), or entering a count/percentage (for numeric/percentage types).

Assessment::Participation (ActiveRecord Model)

Per-Student Grade Record

Key Fields & Associations

Behavior Highlights

• Enforces uniqueness per (assessment, user) via database constraint
• Maintains points_total as the sum of all associated TaskPoint records
• Preserves submission history via submitted_at even after status transitions to :graded
• Can carry both granular points (via tasks) and a final grade (for exams)
• Supports workflow states from initial submission through final grading
• Provides locking mechanism to prevent post-publication tampering

Example Implementation

# filepath: app/models/assessment/participation.rb
module Assessment
  class Participation < ApplicationRecord
    self.table_name = "assessment_participations"

    belongs_to :assessment, class_name: "Assessment::Assessment"
    belongs_to :user
    belongs_to :tutorial, optional: true
    belongs_to :grader, class_name: "User", optional: true

    has_many :task_points, dependent: :destroy,
      class_name: "Assessment::TaskPoint"

  enum status: {
    not_started: 0,
    in_progress: 1,
    submitted: 2,
    graded: 3,
    exempt: 4
  }

  validates :user_id, uniqueness: { scope: :assessment_id }

  def recompute_points_total!
    update!(points_total: task_points.sum(:points))
  end

  def results_visible?
    results_published_at.present?
  end
end

Usage Scenarios

• After assessment setup: When an assignment is created, assignment.seed_participations_from_roster! runs, creating one Assessment::Participation record for each student across all lecture tutorials. Each participation is initialized with status: :not_started, points_total: 0, submitted_at: nil, and tutorial_id set to the tutorial the student currently belongs to.

• Student submits work: A student uploads their homework file. The system sets their participation to status: :submitted and records submitted_at: Time.current. This timestamp persists even after grading. The tutorial_id remains unchanged.

• After grading a submission: A tutor grades a team submission for Problem 1. The grading service creates or updates Assessment::TaskPoint records for each team member, then calls recompute_points_total! on their participation to update the aggregate score. The status transitions to :graded and graded_at is set, but submitted_at and tutorial_id remain unchanged—preserving the submission and tutorial history.

• Publishing exam results: After all exam tasks are graded, the teacher marks participations as published: true and their status is :graded. Students can now see their points breakdown and final grade (if grade_value is set). Exam participations have tutorial_id: nil since exams don't have tutorial context.

• Per-tutorial publication (assignments): Tutorial A completes grading on Monday. The tutor sets results_published_at: Time.current for all participations where tutorial_id = tutorial_a.id. Students in Tutorial A can now see their results. Tutorial B's students (with tutorial_id = tutorial_b.id and results_published_at: nil) still see "pending" status.

• Handling exemptions: A student provides a medical certificate and is marked status: :exempt. Their participation record exists but no points are computed, no grade is assigned, and both submitted_at and graded_at remain nil. The tutorial_id is preserved for audit purposes.

• Distinguishing submission vs non-submission: After grading is complete, the teacher can query submitted_at.present? to distinguish students who submitted work (even if they received 0 points for quality) from those who never submitted at all.

• Student switches tutorials mid-semester: Alice is in Tutorial A when participations are initialized for Homework 3. Her participation has tutorial_id: 1 (Tutorial A). In week 6, she switches to Tutorial B. When Tutorial A publishes results, Alice's Homework 3 results become visible because her participation's tutorial_id still points to Tutorial A. Her future assignments will have new participations with tutorial_id: 2 (Tutorial B).

Assessment::Task (ActiveRecord Model)

Atomic Graded Component

Key Fields & Associations

Behavior Highlights

• Exists only when the parent assessment has requires_points: true
• Enforces max_points >= 0 via validation
• Position determines display order in grading interfaces
• Deletion cascades to all associated TaskPoint records

Example Implementation

# filepath: app/models/assessment/task.rb
module Assessment
  class Task < ApplicationRecord
    self.table_name = "assessment_tasks"

    belongs_to :assessment, class_name: "Assessment::Assessment"
    has_many :task_points, dependent: :destroy,
      class_name: "Assessment::TaskPoint"

    validates :title, presence: true
    validates :max_points, numericality: { greater_than_or_equal_to: 0 }
    validates :position, numericality: { only_integer: true }, allow_nil: true

    acts_as_list scope: :assessment
  end
end

Usage Scenarios

• Creating tasks for a homework: After setting up an assignment's assessment, the teacher creates tasks: assessment.tasks.create!(title: "Problem 1", max_points: 10, position: 1), assessment.tasks.create!(title: "Problem 2", max_points: 15, position: 2). Each task defines a gradeable component.

• Exam with multiple questions: An exam assessment has tasks for each question. A task titled "Question 3: Proof of Theorem" with max_points: 8 allows tutors to grade that specific question independently across all students.

• Automatic total calculation: If the assessment's total_points field is blank, calling assessment.effective_total_points sums all task max_points values (e.g., 10 + 15 + 8 = 33 total points).

• Reordering tasks: Teachers can adjust the position field to reorder how tasks appear in the grading interface without changing the underlying data structure.

Assessment::TaskPoint (ActiveRecord Model)

Per-Student, Per-Task Grade Record

Key Fields & Associations

Behavior Highlights

• Enforces uniqueness per (participation, task) via database constraint
• Triggers recomputation of Assessment::Participation.points_total on save
• Visibility controlled by assessment.results_published, not per-task state
• Links back to the specific submission that was graded for audit trails
• Validation ensures points do not exceed task maximum
• Maintains update history via updated_at for complaint resolution tracking

Example Implementation

# filepath: app/models/assessment/task_point.rb
module Assessment
  class TaskPoint < ApplicationRecord
    self.table_name = "assessment_task_points"

    belongs_to :assessment_participation,
      class_name: "Assessment::Participation"
    belongs_to :task, class_name: "Assessment::Task"
    belongs_to :grader, class_name: "User", optional: true
    belongs_to :submission, optional: true

  validates :points, numericality: { greater_than_or_equal_to: 0 }

  after_commit :bubble_totals

  private

  def bubble_totals
    assessment_participation.recompute_points_total!
  end
end

Usage Scenarios

• Grading a team submission: A tutor grades Problem 1 of a team homework. The grading service creates or updates one Assessment::TaskPoint record per team member, all with the same points value (e.g., 8/10), linking each to submission_id: 42 for audit purposes.

• Bonus points: A tutor awards 12 points out of 10 for exceptional work on a problem. The system accepts this without validation errors, allowing the student's total to exceed the nominal maximum.

• Publishing results: After completing all grading, the teacher sets assessment.results_published = true. Students can now see all their task points and comments at once.

• Recomputation trigger: After saving a TaskPoint with 8 points, the after_commit callback automatically calls assessment_participation.recompute_points_total!, updating the student's aggregate score across all tasks.

• Handling complaints: A student views their exam and submits a complaint about Question 2. The tutor reviews the work, agrees there was a grading error, and updates the Assessment::TaskPoint from 5 to 7 points. The updated_at timestamp records when the adjustment was made. The recomputation callback updates the student's points_total and potentially their final grade_value.

• Audit trail: Months later, a student appeals their grade. The teacher queries task_point.submission to retrieve the original PDF that was graded, verifying the points awarded match the work submitted.

Re-grading and Corrections

The grading interface remains available even after an assessment transitions to graded status. This supports corrections for:

• Discovered grading mistakes
• Student complaints requiring point adjustments
• Late bonus point awards

When accessing grading for a graded or published assessment, the UI should display a warning:

Results already published
Changes will be visible to students immediately. Continue?

This ensures teachers are aware that modifications affect published results. The results_published flag controls visibility, not editability—TaskPoint records remain mutable across all assessment states, and recompute_points_total! is idempotent.

def results_visible?
  results_published_at.present?
end

# Publish results for Tutorial X
tutorial_x_participations = assessment.participations
  .where(tutorial_id: tutorial_x.id)
tutorial_x_participations.update_all(results_published_at: Time.current)

# Student view query
participation.results_visible?  # true if results_published_at is set

# Teacher dashboard: which tutorials have published?
assessment.participations
  .select(:tutorial_id, "COUNT(*) as total")
  .where.not(results_published_at: nil)
  .group(:tutorial_id)

Assessment::Assessable (Concern)

Base Contract for Gradeable Models

Public Interface

Behavior Highlights

• Establishes the polymorphic link via has_one :assessment, as: :assessable
• Provides a safe method to create/update the assessment without duplication
• seed_participations_from_roster! should be overridden by including classes to define roster logic
• Does not enforce whether points or grades are used—that's delegated to Assessment::Pointable and Assessment::Gradable

Example Implementation

# filepath: app/models/assessment/assessable.rb
module Assessment
  module Assessable
    extend ActiveSupport::Concern

    included do
      has_one :assessment, as: :assessable, dependent: :destroy,
        class_name: "Assessment::Assessment"
  end

  def ensure_assessment!(title:, requires_points:, requires_submission: false,
                        visible_from: nil, due_at: nil)
    a = assessment || build_assessment
    a.title = title
    a.requires_points = requires_points
    a.requires_submission = requires_submission
    a.visible_from ||= visible_from if visible_from
    a.due_at ||= due_at if due_at
    a.lecture ||= try(:lecture)
    a.save! if a.changed?
    a
  end

  # Override this method in including classes to define roster logic
  # For Assignment: aggregate from lecture.tutorials
  # For Exam: use exam registration roster
  # For Talk: use speaker roster
  def seed_participations_from_roster!
    raise NotImplementedError,
      "#{self.class.name} must implement seed_participations_from_roster!"
  end
end
end

Usage Scenarios

• Initial setup for an assignment: After creating an Assignment record, the teacher calls assignment.ensure_assessment!(title: "Homework 3", requires_points: true, requires_submission: true) to create the linked Assessment::Assessment. Then assignment.seed_participations_from_roster! aggregates students from all lecture tutorials and creates participation records for each.

• Updating assessment metadata: A teacher realizes the due date was wrong and calls assignment.ensure_assessment!(title: "Homework 3", requires_points: true, due_at: 1.week.from_now) again. The method is idempotent—it updates the existing Assessment::Assessment rather than creating a duplicate.

• For exams after registration: An Exam becomes Rosterable after its registration campaign is completed and allocations are materialized. When calling exam.seed_participations_from_roster!, the concern reads from the exam's roster (the confirmed exam registrants) to seed participations. Only students who successfully registered for the exam will have participation records created.

Assessment::Pointable (Concern)

Enables Per-Task Point Tracking

Public Interface

Behavior Highlights

• Includes Assessment::Assessable and builds on its interface
• Forces requires_points: true when creating the assessment
• Enables the creation of Assessment::Task records for breaking down graded components
• Allows optional submission requirement based on the work type
• Assessment will aggregate points from all task-level grades

Example Implementation

# filepath: app/models/assessment/pointable.rb
module Assessment
  module Pointable
    extend ActiveSupport::Concern
    include Assessment::Assessable

  def ensure_pointbook!(title:, requires_submission: false, **opts)
    ensure_assessment!(
      title: title,
      requires_points: true,
      requires_submission: requires_submission,
      **opts
    )
  end
end

Usage Scenarios

• For homework assignments: After creating an assignment, call assignment.ensure_pointbook!(title: "Homework 3", requires_submission: true, due_at: 1.week.from_now). The assessment is configured for task-level grading, and students must upload files. Tasks are then added for each problem.

• For exams with per-question tracking: An exam includes this concern to track points per question. Call exam.ensure_pointbook!(title: "Final Exam", requires_submission: false) since students don't upload files for in-person exams. Tasks represent individual exam questions.

• Idempotent reconfiguration: A teacher realizes they set the wrong due date and calls assignment.ensure_pointbook!(title: "Homework 3", requires_submission: true, due_at: 2.weeks.from_now). The method updates the existing assessment without creating a duplicate.

Assessment::Gradable (Concern)

Enables Final Grade Recording

Public Interface

Behavior Highlights

• Includes Assessment::Assessable and builds on its interface
• Defaults requires_points to false when creating the assessment, but retains true if it was already enabled (e.g., when combined with Assessment::Pointable)
• No tasks or submissions are required
• Directly updates Assessment::Participation.grade_value for each student
• Can be combined with Assessment::Pointable for exams that need both points and final grades

Example Implementation

# filepath: app/models/assessment/gradable.rb
module Assessment
  module Gradable
    extend ActiveSupport::Concern
    include Assessment::Assessable

  def ensure_gradebook!(title:, **opts)
    requires_points = assessment&.requires_points
    ensure_assessment!(
      title: title,
      requires_points: requires_points.nil? ? false : requires_points,
      requires_submission: false,
      **opts
    )
  end

  def set_grade!(user:, value:, grader: nil)
    a = assessment || raise("No gradebook; call ensure_gradebook! first")
    part = a.participations.find_or_create_by!(user_id: user.id)
    part.update!(
      grade_value: value,
      grader_id: grader&.id,
      graded_at: Time.current,
      status: :graded
    )
  end
end

Usage Scenarios

• For seminar talks: After creating a talk, call talk.ensure_gradebook!(title: "Seminar Talk: Topology") to create an assessment without tasks. After the presentation, call talk.set_grade!(user: speaker, value: "1.0", grader: professor) to record the final grade.

• For exams with final grades: An exam includes both Assessment::Pointable and Assessment::Gradable. After all tasks are graded and points computed, the teacher can call exam.set_grade!(user: student, value: "1.3", grader: professor) to store the official grade that appears on transcripts.

• Idempotent grade updates: A teacher corrects a mistakenly entered grade by calling talk.set_grade! again with the new value. The method updates the existing participation record rather than creating a duplicate.

Enhanced Domain Models

The following sections describe how existing MaMpf models are enhanced to integrate with the assessment system by implementing the grading concerns.

Assignment (Enhanced)

A Pointable Target with Submissions

Grading Implementation

The Assignment model includes the Assessment::Pointable concern to provide per-task point tracking.

Example Implementation

class Assignment < ApplicationRecord
  include Assessment::Pointable

  belongs_to :lecture
  has_many :submissions, dependent: :destroy

  after_create :setup_grading

  private

  def setup_grading
    ensure_pointbook!(
      title: title,
      requires_submission: true,
      due_at: deadline
    )
    seed_participations_from_roster!
  end

  def seed_participations_from_roster!
    return unless assessment

    # Aggregate students from all tutorials in the lecture
    lecture.tutorials.each do |tutorial|
      user_ids = tutorial.roster_user_ids
      user_ids.each do |user_id|
        assessment.participations.find_or_create_by!(user_id: user_id) do |part|
          part.tutorial_id = tutorial.id
        end
      end
    end
  end
end

Talk (Enhanced)

A Gradable Target

Grading Implementation

The Talk model includes the Assessment::Gradable concern for simple grade recording.

Example Implementation

class Talk < ApplicationRecord
  include Roster::Rosterable
  include Assessment::Gradable

  after_create :setup_grading

  private

  def setup_grading
    ensure_gradebook!(title: title)
    seed_participations_from_roster!
  end
end

Grading Talks in Seminars

Workflow Overview

1. Talk Creation (Early):

   • Teacher creates talks in the Content tab of a seminar
   • Each talk is created for registration campaign purposes (students sign up for presentation slots)
   • Assessment record is automatically created via after_create :setup_grading hook
   • Participations are seeded from speakers immediately

2. Campaign & Registration:

   • Students register for talk slots via registration campaign
   • Talks exist with linked assessment records, but no grading yet

3. Presentation Delivery:

   • Semester progresses, students deliver presentations
   • Assessment records are already in place, ready for grading

4. Grading (Late):

   • Teacher navigates to Assessments tab in seminar
   • Tab shows read-only list of all talks with inline grading interface
   • Teacher enters final grade directly in the list (no per-task breakdown)
   • Optionally clicks talk title for detailed view to add feedback notes

UI Design for Seminar Assessments

Assessments Tab (Seminar Context):

• Shows only talks (no assignments or exams in seminars)
• No "New Assessment" button (talks are created via Content tab)
• Inline grade input per row for fast grading workflow
• Columns: Title | Speaker(s) | Grade (inline dropdown) | Status | Actions (view details)
• Help text: "Talks are created in the Content tab"

Grading UX:

• One click to focus grade dropdown, one click to save
• Grade range: 1.0 - 5.0 (German grading scale) or Pass/Fail
• Auto-save on blur or explicit Save button
• Click talk title → opens assessment show page for detailed feedback

Exam

A Flexible Gradable Target

Assessment Integration

The Exam model includes both Assessment::Pointable and Assessment::Gradable concerns for flexible exam grading. The grading mode is configurable per exam instance.

Grading Modes

With Pointbook (Pointbook + Gradebook):

• Includes both Assessment::Pointable and Assessment::Gradable
• Tutors grade per-question/problem points via tasks
• System computes points_total for each student
• Staff applies grade scheme to convert points to final grades
• Use cases: Written exams with detailed point breakdown, oral exams with rubric scoring

Without Pointbook (Gradebook only):

• Includes only Assessment::Gradable
• Examiner records final grade directly
• No per-question breakdown needed
• No points tracking, just final grade (e.g., "1.0", "2.3")
• Use cases: Holistic oral exams, pass/fail written exams, interviews

Grading Workflow

With per-question points:

1. Students register for exam via registration campaign
2. Campaign materializes → exam roster is populated
3. After exam is administered, staff creates Assessment::Assessment with requires_points: true
4. seed_participations_from_roster! creates participation records
5. Tutors grade per-question points via tasks
6. System computes points_total for each student
7. Staff applies grade scheme to convert points to final grades

Without per-question points:

1. Students register for exam via registration campaign
2. Campaign materializes → exam roster is populated
3. Staff creates Assessment::Assessment with requires_points: false
4. seed_participations_from_roster! creates participation records
5. Examiner records final grade directly after examination
6. No point calculation needed

For multiple choice exam support and legal compliance, see Exam Model - Multiple Choice Exams.

Submission (Extended Model)

Team-Capable Graded Work

Existing Structure

The Submission model already handles team uploads:

Assessment Integration (Changed)

To integrate with the grading system, the submission structure changes:

Rationale for Key Decisions

Why change assignment_id to assessment_id:

• More general: Enables future support for exam and talk submissions (e.g., scanned answer sheets, presentation files)
• Decouples submissions from specific domain models
• Aligns with unified grading architecture

Why keep tutorial_id:

• Performance: Fast queries for "all submissions in Tutorial X" without user joins
• Disambiguation: Determines which tutorial grades cross-tutorial teams (edge case)
• Historical accuracy: Preserves context even if students change tutorials mid-semester

Migration Guide

Overview: Transition existing submissions from assignment_id to assessment_id.

Steps:

1. Add assessment_id column to submissions table (with foreign key constraint)
2. Backfill: for each submission, set assessment_id from submission.assignment.assessment.id
3. Remove the old assignment_id column and its foreign key
4. Update Submission model:
   • Change belongs_to :assignment to belongs_to :assessment, class_name: "Assessment::Assessment"
   • Update any code that references submission.assignment to use assessment navigation

Consideration: Ensure all assignments have their assessments created before running the backfill migration.

Behavior Highlights

• Team submissions already work via has_many :users through user_submission_joins
• One submission can have multiple owners (team members)
• Optional task_id enables per-task file uploads for granular grading
• Grading service targets the submission and fans out points to all team members
• File uploads handled via Shrine for manuscript and correction PDFs
• Token-based sharing for team formation

Usage Scenarios

• Team homework submission: Alice, Bob, and Carol form a team for Homework 3. Alice uploads HW3.pdf via the submission interface. The system creates one Submission record linked to all three students via user_submission_joins, then updates each team member's Assessment::Participation record: status: :submitted and submitted_at: Time.current. When a tutor grades this submission, TaskPoint records are created for all three team members with identical points.

• Per-task uploads (new feature): An assignment allows students to upload separate files for each problem. The team uploads Problem1.pdf with task_id: 1, Problem2.pdf with task_id: 2. Each upload updates the team members' Assessment::Participation.submitted_at timestamp (idempotent if already set). Tutors can grade each problem independently, and the grading service still fans out points to all team members for each task.

• Audit trail for complaints: A student complains about their grade on Problem 2. The teacher queries the TaskPoint record, follows the submission_id link, and retrieves the original Problem2.pdf file to review the grading decision.

• Individual submissions: For assignments that don't allow teams, each student uploads their own file. The Submission has only one entry in user_submission_joins, maintaining backward compatibility with the existing single-user flow.

Assessment::SubmissionGrader (Service)

Team-Aware Grading Orchestrator

Public Interface

Behavior Highlights

• Fan-out pattern: one submission graded → Assessment::TaskPoint created for each team member
• Idempotent: re-grading the same submission/task overwrites points consistently
• Links each Assessment::TaskPoint back to the submission_id for audit trail
• Triggers Assessment::Participation.recompute_points_total! after grading
• Validates that the task belongs to the submission's assessment
• Wraps all operations in a database transaction for atomicity
• Visibility controlled separately via assessment.results_published

Example Implementation

# filepath: app/services/assessment/submission_grader.rb
module Assessment
  class SubmissionGrader
    def grade_task!(submission:, task:, points:, grader:, comment: nil)
      assessment = submission.assessment
      raise ArgumentError, "Task not in assessment" unless
        task.assessment_id == assessment.id

      member_ids = submission.users.pluck(:id)
      parts = assessment.participations.where(user_id: member_ids)

      ApplicationRecord.transaction do
        parts.find_each do |part|
          tp = Assessment::TaskPoint.find_or_initialize_by(
          assessment_participation_id: part.id,
          task_id: task.id
        )
        tp.points = points
        tp.grader = grader
        tp.comment = comment if comment.present?
        tp.submission_id = submission.id
        tp.save!
      end
      parts.find_each(&:recompute_points_total!)
    end
  end

  def grade_tasks!(submission:, grades_by_task_id:, grader:)
    Task.where(id: grades_by_task_id.keys).find_each do |t|
      grade_task!(
        submission: submission,
        task: t,
        points: grades_by_task_id[t.id],
        grader: grader
      )
    end
  end
end

Usage Scenarios

• Grading a team homework: A tutor grades Problem 1 of a submission by Alice, Bob, and Carol. They call Assessment::SubmissionGrader.new.grade_task!(submission: sub, task: problem1, points: 8, grader: tutor). The service creates three Assessment::TaskPoint records (one per team member), each with 8 points and linked to the same submission. Each team member's Assessment::Participation.points_total is updated.

• Bulk grading all tasks: After reviewing the entire submission, the tutor calls service.grade_tasks!(submission: sub, grades_by_task_id: { 1 => 8, 2 => 12, 3 => 5 }, grader: tutor). The service iterates through each task and fans out points, updating all participations in a single transaction.

• Re-grading after complaint: A student complains about Problem 2. The tutor reviews and agrees, calling grade_task! again with updated points. The existing Assessment::TaskPoint records are overwritten (upsert), and totals are recomputed. The audit trail via submission_id remains intact.

• Publishing results: Tutors grade all submissions. Once grading is complete, the teacher calls assessment.update!(results_published: true), making all points visible to students at once.

ERD

erDiagram
    Assessment ||--o{ Participation : "has many"
    Assessment ||--o{ Task : "has many"
    Assessment }o--|| Assessable : "belongs to (polymorphic)"

    Participation ||--o{ TaskPoint : "has many"
    Participation }o--|| User : "belongs to"
    Participation }o--|| Assessment : "belongs to"

    Task ||--o{ TaskPoint : "has many"
    Task }o--|| Assessment : "belongs to"

    TaskPoint }o--|| Participation : "belongs to"
    TaskPoint }o--|| Task : "belongs to"
    TaskPoint }o--|| Submission : "belongs to (optional)"
    TaskPoint }o--|| User : "graded by (optional)"

    Submission ||--o{ TaskPoint : "generates (optional)"
    Submission ||--o{ UserSubmissionJoin : "has many"
    Submission }o--|| Assessment : "belongs to"
    Submission }o--|| Tutorial : "belongs to"
    Submission }o--|| Task : "for specific task (optional)"

    UserSubmissionJoin }o--|| Submission : "belongs to"
    UserSubmissionJoin }o--|| User : "belongs to"

    Assignment ||--|| Assessment : "assessable"
    Exam ||--|| Assessment : "assessable"
    Talk ||--|| Assessment : "assessable"

Sequence Diagram: Assessment Creation & Submission Workflow

sequenceDiagram
    actor Teacher
    participant A as Assignment
    participant Assess as Assessment::Assessment
    participant L as Lecture
    participant Tut as Tutorial
    participant Part as Assessment::Participation
    actor Student
    participant Sub as Submission

    Teacher->>A: Create assignment
    A->>Assess: ensure_pointbook!(title, requires_submission: true)
    Assess->>Assess: Create/update assessment record
    Assess-->>A: Assessment created

    Teacher->>A: seed_participations_from_roster!
    A->>L: lecture.tutorials
    L-->>A: [tutorial_1, tutorial_2, ...]

    loop For each tutorial
        A->>Tut: tutorial.roster_user_ids
        Tut-->>A: [student_ids...]
    end

    A->>A: user_ids.uniq (deduplicate)

    loop For each unique student
        A->>Part: Create participation
        Part->>Part: Set status: :not_started
        Part->>Part: Set points_total: 0
    end

    A-->>Teacher: Participations seeded

    Teacher->>Assess: Add tasks (Problem 1, Problem 2, ...)
    Assess->>Assess: Create Assessment::Task records

    Note over Teacher,Assess: Assessment is now ready for student work

    Student->>Sub: Upload homework file
    Sub->>Sub: Create submission record
    Sub->>Sub: Link to team members via user_submission_joins

    loop For each team member
        Sub->>Part: Find participation by user_id
        Part->>Part: Update status: :submitted
        Part->>Part: Set submitted_at: Time.current
    end

    Sub-->>Student: Submission confirmed

    Note over Student,Part: Participations track submission history<br/>even after grading

Sequence Diagram: Team Grading Workflow

sequenceDiagram
    actor Tutor
    participant UI as Grading UI
    participant SG as Assessment::SubmissionGrader
    participant Sub as Submission
    participant Part as Assessment::Participation
    participant TP as Assessment::TaskPoint

    Tutor->>UI: Select submission for Problem 1
    UI->>Sub: Fetch team members
    Sub-->>UI: [Alice, Bob, Carol]

    Tutor->>UI: Enter points: 8/10
    UI->>SG: grade_task!(submission, task, 8, tutor)

    SG->>Sub: submission.assessment
    Sub-->>SG: Assessment
    SG->>Sub: submission.users.pluck(:id)
    Sub-->>SG: [user_id_1, user_id_2, user_id_3]

    SG->>Part: Find participations for team members
    Part-->>SG: [participation_1, participation_2, participation_3]

    rect rgb(240, 248, 255)
        Note over SG,TP: Database Transaction

        loop For each team member
            SG->>TP: find_or_initialize_by(participation, task)
            TP-->>SG: TaskPoint instance
            SG->>TP: Update points, grader, submission_id
            SG->>TP: save!
        end

        loop For each participation
            SG->>Part: recompute_points_total!
            Part->>TP: sum(:points)
            TP-->>Part: Updated total
            Part->>Part: update!(points_total)
        end
    end

    SG-->>UI: Grading complete
    UI-->>Tutor: Show success confirmation

    Note over Tutor,TP: Points visible when<br/>assessment.results_published = true

State Diagram: Assessment Status Transitions

stateDiagram-v2
    [*] --> draft: Assessment created

    draft --> open: Teacher opens for students
    draft --> archived: Cancelled before opening

    open --> closed: Due date passed / manually closed

    closed --> graded: All participations graded
    closed --> open: Reopened (deadline extended)

    graded --> archived: Semester ends
    graded --> closed: Re-opened for re-grading

    archived --> [*]

    note right of draft
        Teacher configures tasks,
        not visible to students
    end note

    note right of open
        Students can view/submit,
        results_published: false
    end note

    note right of closed
        No more submissions,
        grading in progress
    end note

    note right of graded
        All graded,
        results can be published
    end note

Proposed Folder Structure

app/
├── models/
│   ├── assessment/
│   │   ├── assessment.rb
│   │   ├── participation.rb
│   │   ├── task.rb
│   │   ├── task_point.rb
│   │   ├── assessable.rb
│   │   ├── pointable.rb
│   │   └── gradable.rb
│   │
│   ├── assignment.rb           # includes Assessment::Pointable
│   ├── talk.rb                 # includes Assessment::Gradable
│   ├── exam.rb                 # includes both concerns + Registration + Roster
│   └── submission.rb           # extended with assessment_id
│
└── services/
    └── assessment/
        └── submission_grader.rb

Key Files:

• Models: app/models/assessment/ contains all namespaced models
• Concerns: Assessable, Pointable, Gradable live within the namespace
• Services: app/services/assessment/submission_grader.rb handles team grading
• Enhanced Models: Assignment, Talk, Exam include the assessment concerns
• Migrations: Will include changes to add assessment_id to submissions table

Database Tables

The following tables support the assessment system:

Naming rationale: Namespaced table names follow Rails conventions and prevent collisions with potential future models (e.g., Quiz::Task, Exercise::Task).

Schema Updates for Per-Tutorial Publication

New columns for assessment_participations:

# filepath: db/migrate/20250105000000_add_tutorial_and_publication_to_participations.rb
class AddTutorialAndPublicationToParticipations < ActiveRecord::Migration[7.0]
  def change
    add_reference :assessment_participations, :tutorial,
      foreign_key: true, null: true, index: true
    add_column :assessment_participations, :results_published_at,
      :datetime, null: true
    add_index :assessment_participations, :results_published_at
  end
end

Migration rationale:

• tutorial_id: Nullable to support exams and talks without tutorial context
• results_published_at: Enables per-tutorial publication for assignments
• Indexed for fast tutorial-scoped queries and publication status checks
• Foreign key constraint maintains referential integrity

Backfill strategy for existing data:

# For existing assignment participations, backfill tutorial_id from submission
Submission.includes(:users, :tutorial).find_each do |sub|
  sub.users.each do |user|
    participation = Assessment::Participation.find_by(
      assessment_id: sub.assessment_id,
      user_id: user.id
    )
    participation&.update_column(:tutorial_id, sub.tutorial_id)
  end
end

Exam Model

Problem Overview

MaMpf needs a formal representation of exams that can:

• Act as a registration target with capacity limits and eligibility checks (see Student Performance)
• Track which students are registered for which exam dates/locations
• Link to the assessment system for grading
• Support multiple exam dates per lecture (e.g., Hauptklausur, Nachklausur, Wiederholungsklausur)

Solution Architecture

We introduce a new Exam model that:

• Belongs to a Lecture: Each exam is scoped to a specific lecture offering
• Implements Registration::Registerable: Acts as a registration target (students register for the exam)
• Implements Roster::Rosterable: Manages the list of registered students
• Implements Assessment::Assessable: Links to an Assessment::Assessment for grading

The parent Lecture (which implements Registration::Campaignable) hosts the registration campaigns. Each exam (Hauptklausur, Nachklausur, etc.) gets its own campaign with that exam as the sole registerable item.

Exam (ActiveRecord Model)

Key Attributes

Role in the System

1. As Registerable (Registration Target)

# The parent lecture hosts the campaign
lecture = Lecture.find(123)
campaign = lecture.registration_campaigns.create!(
  title: "Hauptklausur Registration",
  allocation_mode: :first_come_first_served,
  registration_deadline: 2.weeks.from_now
)

# The exam is the sole registerable item
exam = lecture.exams.create!(
  title: "Hauptklausur",
  date: 3.weeks.from_now,
  capacity: 200
)
campaign.registration_items.create!(registerable: exam)

2. As Rosterable (Student Tracking)

# After allocation, students are materialized into the exam roster
exam.roster_user_ids # => [101, 102, 103, ...]

3. As Assessable (Grading Container)

# After the exam, link it to an assessment for grading
assessment = Assessment::Assessment.create!(
  assessable: exam,
  lecture: exam.lecture,
  title: "#{exam.title} Grading"
)

Example Implementation

class Exam < ApplicationRecord
  belongs_to :lecture

  include Registration::Registerable
  include Roster::Rosterable
  include Assessment::Assessable

  validates :lecture, presence: true
  validates :title, presence: true
  validates :date, presence: true
  validates :capacity, numericality: { greater_than: 0, allow_nil: true }

  def materialize_allocation!(user_ids:, campaign:)
    replace_roster!(
      user_ids: user_ids,
      source_type: "Registration::Campaign",
      source_id: campaign.id
    )
  end

  def registration_open?
    Time.current < registration_deadline
  end

  def past?
    date < Time.current
  end
end

Database Migration

class CreateExams < ActiveRecord::Migration[7.0]
  def change
    create_table :exams do |t|
      t.references :lecture, null: false, foreign_key: true
      t.string :title, null: false
      t.datetime :date, null: false
      t.string :location
      t.integer :capacity, null: false
      t.datetime :registration_deadline
      t.text :description

      t.timestamps
    end

    add_index :exams, [:lecture_id, :date]
  end
end

Exam Registration Flow

Setup (Staff Actions)

Student Experience

1. Student visits exam registration campaign page
2. System checks eligibility via Registration::PolicyEngine (queries StudentPerformance::Certification.status)
3. If ineligible, student sees error message explaining why (e.g., "Certification pending" or "Certification failed")
4. If eligible (status IN passed/forced_passed), student sees registration interface
5. Student submits registration
6. Registration is confirmed immediately (FCFS) or after deadline (preference-based, if multiple exam dates)
7. After registration closes, materialize_allocation! updates exam roster (allocation filtered to only certified students)

Exam Grading Flow

After Exam is Administered

Usage Scenarios

Scenario 1: Regular Final Exam

exam = lecture.exams.create!(
  title: "Final Exam",
  date: Date.new(2025, 2, 15),
  location: "Main Hall",
  capacity: 200,
  registration_deadline: Date.new(2025, 2, 1)
)

campaign = exam.registration_campaigns.create!(
  title: "Final Exam Registration",
  allocation_mode: :first_come_first_served,
  registration_deadline: exam.registration_deadline
)

campaign.registration_policies.create!(
  kind: :student_performance,
  config: { lecture_id: lecture.id }
)

# Teacher creates certifications for eligible students
lecture.active_users.find_each do |user|
  evaluator = StudentPerformance::Evaluator.new(lecture: lecture, user: user)
  proposal = evaluator.proposal

  StudentPerformance::Certification.create!(
    lecture: lecture,
    user: user,
    status: proposal[:status],  # :passed or :failed
    rule_snapshot: proposal[:rule_snapshot],
    notes: proposal[:notes]
  )
end

# Pre-flight check before opening
campaign.validate_certifications!  # raises if missing certifications

Scenario 2: Multiple Exam Dates (Regular + Retake)

regular_exam = lecture.exams.create!(
  title: "Regular Exam",
  date: Date.new(2025, 2, 15),
  capacity: 200
)

retake_exam = lecture.exams.create!(
  title: "Retake Exam",
  date: Date.new(2025, 3, 15),
  capacity: 50
)

campaign = lecture.registration_campaigns.create!(
  title: "Exam Date Selection",
  allocation_mode: :preference_based
)

campaign.registration_items.create!(registerable: regular_exam)
campaign.registration_items.create!(registerable: retake_exam)

State Diagram

stateDiagram-v2
    [*] --> Created
    Created --> RegistrationOpen : registration_deadline not reached
    RegistrationOpen --> RegistrationClosed : deadline passed
    RegistrationClosed --> Administered : exam date reached
    Administered --> Graded : grades entered
    Graded --> [*]

Proposed File Structure

app/
└── models/
    └── exam.rb

Student Performance

Problem Overview

After coursework and achievements are recorded, MaMpf needs to:

• Enforce prerequisites: Prevent unqualified students from being finalized on exam rosters.
• Support flexible criteria: Combine point thresholds, achievement counts, and custom rules.
• Materialize results: Store computed performance data to avoid expensive queries during registration page loads.
• Guarantee correctness: Recompute performance data on demand to ensure decisions use fresh facts.
• Allow teacher certification: Let teachers confirm pass/fail (with manual overrides) with an audit trail.
• Trigger recomputation: Update materialized data when coursework grades change or policies are updated.
• Integrate with registration: Work seamlessly with the Registration::Policy system.

Solution Architecture

We use a factual materialization + teacher certification + phased policy checks:

• Factual Source: StudentPerformance::Record stores materialized performance data per (lecture, user). It contains facts only, not interpretations.
• Not a Cache: This is an authoritative data snapshot for reads. Correctness is ensured by just-in-time recomputation in critical flows.
• Teacher Certification: StudentPerformance::Certification captures teacher-declared status (pending, passed, failed) with audit fields and a snapshot of the rule used when certifying. Manual overrides are encoded as source: :manual.
• Policy Phases: Registration::Policy entries are evaluated by phase: registration, finalization, or both. Enforcement happens only if a policy is configured for that phase. Policies check Certification status at runtime once certifications are complete.
• Service-Based Computation: StudentPerformance::Service aggregates points and achievements and upserts the factual StudentPerformance::Record.
• Evaluator (Teacher Tool): StudentPerformance::Evaluator is a teacher-facing tool that interprets factual records to generate bulk certification proposals and show rule change impact. It is never called during registration/finalization runtime.
• Achievement Tracking: A top-level Achievement model records qualitative accomplishments (e.g., blackboard presentations).
• Recomputation Triggers: Background jobs and on-demand triggers keep the data fresh and guarantee correctness.
• Audit Trail: Certification provides the authoritative decision and audit (who, when, source, rule snapshot). The Record stays facts-only.

StudentPerformance::Record (ActiveRecord Model)

Materialized Performance Snapshot

The main fields and methods of StudentPerformance::Record are:

Behavior Highlights

• Enforces uniqueness per (lecture, user) via database constraint.
• Contains only factual data; interpretation is handled by Evaluator and teacher certification.
• Re-computation updates materialized values and computed_at.

Example Implementation

module StudentPerformance
  class Record < ApplicationRecord
    self.table_name = "student_performance_records"

    belongs_to :lecture
    belongs_to :user

    validates :lecture_id, uniqueness: { scope: :user_id }
  end
end

Usage Scenarios

• After coursework completion: A background job runs StudentPerformance::Service.new(lecture: ...).compute_and_upsert_all_records!. Alice's record is created with points_total_materialized: 58, percentage_materialized: 58. The record itself does not say if she passed.

• Teacher certification workflow: The teacher opens the Certification UI, which uses the Evaluator to generate proposals for all students. The teacher reviews and creates Certification rows (pending/passed/failed). Manual edge cases are set with source: :manual.

• Registration runtime: Bob tries to register for the exam. The system:

  1. Recomputes Bob's record just-in-time to ensure facts are current
  2. Checks if Bob has a Certification with status: :passed
  3. Allows or blocks registration based on certification status

• Finalization runtime: Before materializing the exam roster, the system checks that all confirmed registrants have Certification with status: :passed. Any missing/pending/failed certifications block finalization and trigger remediation UI.

Achievement (ActiveRecord Model)

Qualitative Student Accomplishments (Assessable Type)

Key Fields & Associations

Value Types

Behavior Highlights

• Assessable Integration: Each Achievement has one Assessment::Assessment record where assessable_type = "Achievement" and assessable_id = achievement.id
• Participation Seeding: When created, participations are seeded for all students in the lecture roster
• Tutor Grading: Tutors mark achievement completion via existing Assessment::Participation editing UI:
  • Boolean: Check/uncheck "Completed" → sets grade_value: "Pass"/"Fail"
  • Numeric: Enter count → sets grade_value: <count>
  • Percentage: Enter percentage → sets grade_value: <percentage>
• No Tasks/Submissions: Achievements do not use Assessment::Task (no per-task breakdown) and do not require file uploads (requires_submission: false)
• Eligibility Checking: StudentPerformance::Service reads participation grade_value to determine if student meets threshold
• Deletion Protection: Cannot delete achievement if referenced by any rule (dependent: :restrict_with_error). Database FK constraint provides additional layer (on_delete: :restrict)

Example Implementation

class Achievement < ApplicationRecord
  include Assessment::Assessable

  belongs_to :lecture
  has_many :rule_achievements,
           class_name: "StudentPerformance::RuleAchievement",
           dependent: :restrict_with_error

  enum value_type: { boolean: 0, numeric: 1, percentage: 2 }

  validates :lecture_id, :value_type, :title, presence: true
  validates :threshold, numericality: { greater_than: 0 }, if: -> { numeric? || percentage? }
  validates :threshold, absence: true, if: :boolean?

  after_create :create_assessment_infrastructure

  def create_assessment_infrastructure
    ensure_assessment!(
      title: title,
      requires_points: false,
      requires_submission: false
    )
    seed_participations_from_roster!
  end

  def seed_participations_from_roster!
    # Override from Assessment::Assessable concern
    # Achievement roster = all lecture students
    assessment.seed_participations_from!(user_ids: lecture.students.pluck(:id))
  end

  def student_met_threshold?(user)
    participation = assessment.participations.find_by(user: user)
    return false unless participation&.grade_value.present?

    case value_type
    when "boolean"
      participation.grade_value == "Pass"
    when "numeric"
      participation.grade_value.to_i >= threshold
    when "percentage"
      participation.grade_value.to_f >= threshold
    end
  end
end

Usage Scenarios

• Teacher creates achievement: Navigate to Lecture → Assessments → New Assessment → select "Achievement". Enter title ("Blackboard Presentation"), choose value_type ("boolean"). System creates Achievement + Assessment + Participations for all students.

• Tutor marks completion: In tutorial roster view, tutor sees participation list for "Blackboard Presentation" achievement. Checks box next to Emma's name → participation.grade_value = "Pass".

• Eligibility computation: StudentPerformance::Service calls achievement.student_met_threshold?(emma) which checks if Emma's participation has grade_value: "Pass".

StudentPerformance::Rule (ActiveRecord Model)

Eligibility Criteria Configuration

Key Fields & Associations

Behavior Highlights

• Stored as a database record (not just JSONB config) for better querying and validation
• One lecture can have one active rule at a time
• References multiple achievements via join table (student_performance_rule_achievements)
• Database-level integrity prevents deletion of achievements still referenced by rules
• Enforces mutual exclusivity of percentage vs absolute point thresholds
• Points are aggregated from all assignments of the lecture (no filtering by type or archived status)

Example Implementation

module StudentPerformance
  class Rule < ApplicationRecord
    self.table_name = "student_performance_rules"

    belongs_to :lecture
    has_many :rule_achievements,
             class_name: "StudentPerformance::RuleAchievement",
             dependent: :destroy
    has_many :required_achievements,
             through: :rule_achievements,
             source: :achievement

    validates :lecture_id, presence: true
    validates :min_percentage, numericality: { greater_than_or_equal_to: 0, less_than_or_equal_to: 100 }, allow_nil: true
    validates :min_points_absolute, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
    validate :percentage_or_absolute_not_both

    private

    def percentage_or_absolute_not_both
      if min_percentage.present? && min_points_absolute.present?
        errors.add(:base, "Cannot specify both percentage and absolute point threshold")
      end
    end
  end
end

module StudentPerformance
  class RuleAchievement < ApplicationRecord
    self.table_name = "student_performance_rule_achievements"

    belongs_to :rule, class_name: "StudentPerformance::Rule"
    belongs_to :achievement

    validates :rule_id, uniqueness: { scope: :achievement_id }
    validates :position, presence: true

    acts_as_list scope: :rule  # For ordering in UI
  end
end

Usage Scenarios

• Professor sets up rule: Teacher first creates achievements:

  presentation = Achievement.create!(lecture: linear_algebra, title: "Blackboard Presentation", value_type: :boolean)
  attendance = Achievement.create!(lecture: linear_algebra, title: "Lab Attendance", value_type: :numeric, threshold: 12)
  

  Then creates rule and associates achievements:

  rule = StudentPerformance::Rule.create!(lecture: linear_algebra, min_percentage: 50)
  rule.required_achievements << [presentation, attendance]
  

• Mid-semester adjustment: Professor realizes 50% is too strict, updates: rule.update!(min_percentage: 45). System triggers recomputation for all students.

• Adding achievement to rule: Professor adds new requirement: rule.required_achievements << bonus_achievement. Join table automatically creates relationship.

• Preventing achievement deletion: Teacher tries to delete achievement used in rule: presentation.destroy raises ActiveRecord::InvalidForeignKey. UI shows: "Cannot delete - used in 2 performance rules".

• Service uses rule: The computation service loads the active rule: rule = StudentPerformance::Rule.find_by(lecture: lecture, active: true) and accesses rule.required_achievements for evaluation. Points are aggregated from all lecture assignments.

StudentPerformance::Service (Service Object)

Performance Computer

Public Interface

Behavior Highlights

• Batch or targeted: Can compute for all users or a specific subset.
• Idempotent: Running twice with the same inputs produces the same factual record.
• Factual updates only: The service is responsible for creating/updating the materialized facts, not for interpreting them.

Recomputation Triggers

The service is invoked in several scenarios to keep performance records accurate:

1. After coursework grading: A background job can trigger a full recomputation.
2. After achievement changes: When tutors record or correct lecture achievements for a user.
3. Just-in-Time: The Registration::Policy triggers a recomputation for a single user at the moment of an exam registration attempt to guarantee 100% correctness.
4. On-demand by staff: Manual trigger via an admin interface for debugging or corrections.

Example Implementation

module StudentPerformance
  class Service
    def initialize(lecture:)
      @lecture = lecture
      @rule = lecture.student_performance_rule
    end

    def compute_and_upsert_record_for(user)
      points_data = aggregate_points(user)

      met_ids = @rule.required_achievements.select do |achievement|
        achievement.student_met_threshold?(user)
      end.map(&:id)

      record_data = {
        lecture_id: @lecture.id,
        user_id: user.id,
        points_total_materialized: points_data[:total],
        points_max_materialized: points_data[:max],
        percentage_materialized: points_data[:percentage],
        achievements_met_ids: met_ids,
        computed_at: Time.current
      }

      StudentPerformance::Record.upsert(record_data, unique_by: [:lecture_id, :user_id])
      StudentPerformance::Record.find_by(lecture_id: @lecture.id, user_id: user.id)
    end

    def compute_and_upsert_all_records!
      @lecture.students.find_each do |user|
        compute_and_upsert_record_for(user)
      end
    end

    private

    def aggregate_points(user)
      # Implementation aggregates assessment points based on rule configuration
      # Returns hash with :total, :max, :percentage
    end
  end
end

StudentPerformance::Evaluator (Service Object)

Teacher-Facing Proposal Generator

Public Interface

Behavior Highlights

• Teacher-only tool: Used in Certification UI and rule editing workflows
• No runtime gating: Never called by Registration::Policy during registration/finalization
• Proposal generator: Outputs are suggestions for teachers, not authoritative decisions
• Rule change preview: Shows impact when teacher edits thresholds (50% → 45%)

Usage Contexts

Where Evaluator IS used:

• Bulk Certification UI: "Generate proposals for all students"
• Rule Edit Modal: "Preview: 12 students would change from failed → passed"
• Teacher Dashboard: "23 students currently meet requirements"

Where Evaluator is NOT used:

• Student registration attempts (Policy checks Certification directly)
• Finalization guards (Policy requires Certification=passed)
• Any automated student-facing flows

Example Implementation

module StudentPerformance
  class Evaluator
    Result = Struct.new(:proposed_status, :details, keyword_init: true)

    def initialize(rule)
      @rule = rule
    end

    def evaluate(record)
      return Result.new(proposed_status: :failed, details: {}) unless record

      req_pts = required_points(@rule)
      meets_points = req_pts.nil? || record.points_total_materialized.to_i >= req_pts
      meets_achievements = includes_all?(
        record.achievements_met_ids,
        @rule.required_achievements.pluck(:id)
      )
      proposed = (meets_points && meets_achievements) ? :passed : :failed

      Result.new(
        proposed_status: proposed,
        details: {
          current_points: record.points_total_materialized,
          required_points: req_pts,
          current_achievement_ids: record.achievements_met_ids,
          required_achievement_ids: @rule.required_achievements.pluck(:id)
        }
      )
    end

    def bulk_evaluate(records)
      records.map { |record| [record, evaluate(record)] }.to_h
    end

    private

    def required_points(rule)
      return rule.min_points_absolute if rule.min_points_absolute.present?
      return nil unless rule.min_percentage.present?

      total = rule.lecture.assignments.sum(:max_points)
      (total * rule.min_percentage / 100.0).ceil
    end

    def includes_all?(have_ids, need_ids)
      return true if need_ids.blank?
      have = Array(have_ids).map(&:to_i).to_set
      need = Array(need_ids).map(&:to_i).to_set
      have >= need
    end
  end
end

StudentPerformance::Certification (ActiveRecord Model)

Teacher-declared pass/fail with audit

Main fields & associations

Uniqueness: one certification per (lecture_id, user_id).

Behavior highlights

• Default status: New certifications created as pending during bulk generation.
• Bulk proposal workflow: Teacher uses Evaluator UI to generate proposals; reviews and accepts/modifies; creates Certification rows with source: :computed.
• Manual overrides: Teacher can create/update certifications with source: :manual for special cases (medical exemption, etc.).
• Pre-flight validation (completeness check):
  • Registration phase: When campaign with registration-phase student_performance policy is saved, warn if certifications are missing. On campaign open, hard-fail if any certifications are missing/pending.
  • Finalization phase: When campaign with finalization-phase student_performance policy finalizes, hard-fail if any confirmed registrants have missing/pending/failed certifications. Show remediation UI.
• Auto-reject at finalization: Students with status: :failed are automatically moved to rejected status during finalization (if finalization-phase policy exists).
• Rule change handling: When teacher edits rule thresholds, show diff modal with:
  • Computed certifications that would flip (failed → passed or vice versa)
  • Manual certifications that conflict with new proposal
  • Teacher reviews and applies changes manually via modal
  • No automatic updates to Certification table; teacher must confirm

Example (conceptual)

module StudentPerformance
  class Certification < ApplicationRecord
    self.table_name = "student_performance_certifications"

    enum status: { pending: 0, passed: 1, failed: 2 }
    enum source: { computed: 0, manual: 1 }

    belongs_to :lecture
    belongs_to :user
    belongs_to :certified_by, class_name: "User", optional: true
    belongs_to :rule, class_name: "StudentPerformance::Rule", optional: true

    validates :lecture_id, uniqueness: { scope: :user_id }
    validates :certified_by, presence: true, unless: :pending?
    validates :certified_at, presence: true, unless: :pending?

    def self.passed?(lecture:, user:)
      find_by(lecture: lecture, user: user)&.passed? || false
    end
  end
end

Integration with Registration::Policy

Architecture Overview

The integration follows a clear separation of concerns:

StudentPerformance::Record (materialized data layer)

• Stores what the student has achieved (points, achievements).
• Is recomputed on demand to ensure freshness.

StudentPerformance::Certification (authoritative decision layer)

• Stores teacher-declared pass/fail status per student.
• Required to be complete before registration/finalization phases can start.
• Policy checks this table at runtime, never calls Evaluator.

Registration::Policy (gating layer)

• Enforces data prerequisites: certifications must be complete before phase starts.
• Runtime evaluation: checks Certification.status == :passed for each student.
• Never computes or proposes; just reads authoritative certification data.

StudentPerformance::Service (computation layer)

• Aggregates assessment points and checks achievements.
• Creates or updates the factual StudentPerformance::Record.
• Used for background updates and teacher dashboards, not runtime gating.

Policy Configuration

When a teacher wants student performance gating, they add a Registration::Policy record that references the lecture whose active rule applies:

campaign.registration_policies.create!(
  kind: :student_performance,
  phase: :finalization, # or :registration or :both for completeness checks at both stages
  active: true,
  position: 1,
  config: { "lecture_id" => 42 }
)

The policy queries StudentPerformance::Rule.find_by(lecture_id: 42, active: true) to get the actual criteria for UI display, but enforcement is done via Certification table lookups.

Pre-flight Validation (Data Completeness)

Unlike other policy types, student_performance policies require data preparation before the phase starts:

Registration phase policy:

• On campaign save: Warn if any lecture students lack a Certification (any status)
• On campaign open: Hard-fail if any lecture students lack a Certification or have status: :pending
• Runtime (student registers): Check Certification.status == :passed for that student

Finalization phase policy:

• On finalize trigger: Hard-fail if any confirmed registrants lack a Certification or have status: :pending
• Show remediation UI for teacher to resolve pending → passed/failed
• Auto-reject students with status: :failed
• Only materialize students with status: :passed

Config Field Reference

Why This Design?

Single source of truth: The StudentPerformance::Rule model defines what "sufficient performance" means. Registration policies just check "does this student have sufficient performance for lecture X?"

Benefits:

1. No duplication: Criteria defined once in StudentPerformance::Rule
2. Consistent across exams: Main exam and retake exam both reference the same performance requirements
3. Easy updates: Professor changes rule.update!(min_percentage: 45) and all exam campaigns automatically use new threshold
4. Clear separation: Rule defines performance criteria, policy gates registration based on those criteria

Example: A lecture has one StudentPerformance::Rule (50% points + presentation). Multiple exam campaigns (midterm, final, retake) all have Registration::Policy records with kind: :student_performance, config: { lecture_id: 42 }. All reference the same rule.

Policy Config Reference

Exam eligibility policies (Registration::Policy with kind: :student_performance) store only a minimal JSONB config:

{ "lecture_id": 42 }

All threshold and achievement criteria live in StudentPerformance::Rule (regular columns, associations). Changing a threshold (e.g. 50 → 45) is done by updating the rule record via a diff modal, not the policy config. The JSONB usage rationale (generic policy kinds need flexible keyed configs) is documented centrally in the Registration chapter; this chapter only notes the minimal linkage.

Runtime Evaluation

Once certifications are complete and the phase is open, evaluation is simple:

# Pseudo-code for Registration::Policy#evaluate(user) when kind == :student_performance
def eval_student_performance(user)
  lecture = Lecture.find(config["lecture_id"])

  cert = StudentPerformance::Certification.find_by(lecture: lecture, user: user)

  if cert&.passed?
    pass_result(:certification_passed)
  else
    fail_result(:certification_not_passed, "Lecture performance certification not passed")
  end
end

No Evaluator calls, no Service calls at registration time. Just a simple table lookup.

Flowchart: Student Performance Policy Flow

flowchart TD
  Start([Teacher adds student_performance policy]) --> Phase{Which phase?}

  Phase -- registration --> RegSetup[Campaign save: warn if certs incomplete]
  RegSetup --> RegOpen[Campaign open: fail if certs missing/pending]
  RegOpen --> RegRuntime[Student registers]
  RegRuntime --> CertCheck1[Check Certification.status]
  CertCheck1 -- passed --> Allow[Allow registration]
  CertCheck1 -- failed/missing --> Block[Block registration]

  Phase -- finalization --> FinSetup[Students register freely]
  FinSetup --> FinTrigger[Teacher clicks finalize]
  FinTrigger --> CertCheck2{All confirmed have certs?}
  CertCheck2 -- missing/pending --> Remediate[Show remediation UI]
  CertCheck2 -- all resolved --> AutoReject[Auto-reject failed certs]
  AutoReject --> Materialize[Materialize passed certs]

  Phase -- both --> BothReg[Registration phase flow]
  BothReg --> BothFin[+ Finalization phase flow]

Complete Example Walkthrough

Setup Phase:

1. Professor creates Linear Algebra lecture with weekly homework assignments
2. Professor creates achievements:

   presentation = Achievement.create!(
     lecture: linear_algebra,
     title: "Blackboard Presentation",
     value_type: :boolean
   )
   attendance = Achievement.create!(
     lecture: linear_algebra,
     title: "Lab Attendance",
     value_type: :numeric,
     threshold: 12
   )
   

3. Professor creates performance rule (ONCE for the lecture):

   rule = StudentPerformance::Rule.create!(
     lecture: linear_algebra,
     min_percentage: 50,
     active: true
   )
   rule.required_achievements << [presentation, attendance]
   

Computation Phase:

1. Semester progresses, students submit homework, tutors grade.
2. After final homework deadline, a background job runs:

   StudentPerformance::Service.new(lecture: linear_algebra).compute_and_upsert_all_records!
   

3. System creates StudentPerformance::Record entries:
   • Alice: 58/100 points (58%), achievements_met_ids: [1, 2]
   • Bob: 42/100 points (42%), achievements_met_ids: []
   • Carol: 65/100 points (65%), achievements_met_ids: [1]

Certification Phase:

1. Professor opens Certification UI, clicks "Generate Proposals"
2. Evaluator runs for all students, showing:
   • Alice: proposed_status: :passed (has points + achievements)
   • Bob: proposed_status: :failed (insufficient points)
   • Carol: proposed_status: :failed (missing attendance achievement)
3. Professor reviews and bulk-creates certifications:

   # Alice: accept proposal
   StudentPerformance::Certification.create!(
     lecture: linear_algebra, user: alice,
     status: :passed, source: :computed,
     certified_by: professor, certified_at: Time.current,
     rule: rule
   )
   
   # Bob: accept proposal
   StudentPerformance::Certification.create!(
     lecture: linear_algebra, user: bob,
     status: :failed, source: :computed,
     certified_by: professor, certified_at: Time.current,
     rule: rule
   )   # Carol: manual override (medical exemption for attendance)
   StudentPerformance::Certification.create!(
     lecture: linear_algebra, user: carol,
     status: :passed, source: :manual,
     certified_by: professor, certified_at: Time.current,
     note: "Medical exemption for attendance requirement"
   )
   

Campaign Setup:

4. Professor sets up exam campaign for final exam
5. Professor adds registration policy:

   policy = campaign.registration_policies.create!(
     kind: :student_performance,
     phase: :both,
     config: { "lecture_id" => linear_algebra.id }
   )
   

6. Campaign save: system checks all students have certifications (all have status, so warning clears)
7. Professor clicks "Open Registration": system verifies no pending certifications remain (all passed/failed, so opens successfully)

Registration Phase:

8. Alice attempts registration:
   • Policy evaluates: finds Certification with status: :passed
   • Registration succeeds
9. Bob attempts registration:
   • Policy evaluates: finds Certification with status: :failed
   • Registration blocked with message
10. Carol attempts registration:
    • Policy evaluates: finds Certification with status: :passed
    • Registration succeeds (manual override respected)

Finalization Phase:

11. Professor clicks "Finalize Campaign"
12. System checks finalization policies:
    • Alice: Certification=passed ✓
    • Carol: Certification=passed ✓
    • (Bob never registered, so not checked)
13. System materializes exam roster with Alice and Carol

Policy Evaluation Guarantees

The integration provides several guarantees:

1. Data Completeness: Pre-flight checks ensure certifications exist before phase opens
2. Simple Runtime: Policy just checks Certification table (no computation during registration)
3. Auditability: Certification stores who decided what and when
4. Manual Override Support: Teachers can override via source: :manual
5. Idempotency: Repeated checks with same certification data yield same result

Multiple Policies

A campaign can have multiple policies that must all pass:

# Example: Eligibility + enrollment deadline + course prerequisite
campaign.registration_policies.create!([
  { kind: :student_performance, position: 1, config: { ... } },
  { kind: :deadline, position: 2, config: { ... } },
  { kind: :course_prerequisite, position: 3, config: { ... } }
])

Policies are evaluated in position order. First failure stops evaluation and returns that failure to the user.

ERD

erDiagram
  LECTURE_PERFORMANCE_RECORD ||--|| LECTURE : "scoped to"
  LECTURE_PERFORMANCE_RECORD ||--|| USER : "tracks"
  LECTURE_PERFORMANCE_RULE ||--|| LECTURE : "configures"
  ACHIEVEMENT ||--|| LECTURE : "belongs to"
  LECTURE_PERFORMANCE_CERTIFICATION ||--|| LECTURE : "issued for"
  LECTURE_PERFORMANCE_CERTIFICATION ||--|| USER : "issued to"
  LECTURE_PERFORMANCE_CERTIFICATION }o--|| LECTURE_PERFORMANCE_RULE : "snapshot of"

Sequence Diagram

sequenceDiagram
  actor Teacher
  actor Student
  participant Rule as StudentPerformance::Rule
  participant Service as StudentPerformance::Service
  participant Record as StudentPerformance::Record
  participant Evaluator as StudentPerformance::Evaluator
  participant Cert as StudentPerformance::Certification
  participant Campaign as Registration::Campaign

  rect rgb(235, 245, 255)
  note over Teacher,Record: Stage 1: Rule Creation & Fact Computation
  Teacher->>Rule: create/update!(thresholds, achievements)
  Service->>Record: compute_and_upsert_all_records!(lecture)
  end

  rect rgb(255, 245, 235)
  note over Teacher,Cert: Stage 2: Teacher Certification (UI-driven)
  Teacher->>Evaluator: open Certification UI
  Evaluator->>Record: bulk_evaluate(all_records)
  Evaluator-->>Teacher: show proposals (passed/failed)
  Teacher->>Cert: bulk create/update (pending → passed/failed)
  Teacher->>Cert: manual overrides (source: manual)
  end

  rect rgb(245, 255, 245)
  note over Teacher,Campaign: Stage 3: Campaign Setup & Open
  Teacher->>Campaign: add student_performance policy (phase: registration)
  Campaign->>Cert: pre-flight: check all students have non-pending cert
  alt Missing/pending certs
    Campaign-->>Teacher: hard-fail: resolve X certifications
  end
  Campaign->>Campaign: status → open
  end

  rect rgb(235, 255, 235)
  note over Student,Campaign: Stage 4: Registration (runtime)
  Student->>Campaign: register
  Campaign->>Cert: check Certification.status == passed?
  alt Passed
    Campaign-->>Student: success
  else Failed/missing
    Campaign-->>Student: blocked
  end
  end

  rect rgb(255, 235, 235)
  note over Campaign,Cert: Stage 5: Finalization
  Campaign->>Service: recompute all facts (freshness)
  Campaign->>Cert: require passed for all confirmed
  alt Any failed
    Campaign->>Campaign: auto-reject those registrations
  end
  alt Any pending/missing
    Campaign-->>Teacher: hard-fail: remediation UI
  end
  Campaign->>Campaign: materialize allocation
  end

Proposed Folder Structure

app/
├── models/
│   ├── achievement.rb (top-level)
│   └── student_performance/
│       ├── record.rb
│       └── rule.rb
│
└── services/
  └── student_performance/
    └── service.rb

Key Files

• app/models/achievement.rb - Top-level qualitative accomplishments (used across features)
• app/models/student_performance/record.rb - Materialized performance status with recomputation support
• app/models/student_performance/rule.rb - Eligibility criteria configuration
• app/services/student_performance/service.rb - Performance computation logic with correctness guarantees

Database Tables

• achievements - Top-level assessable type for qualitative accomplishments (integrates with Assessment infrastructure)
• student_performance_records - Materialized per-user performance (facts only)
• student_performance_rules - Eligibility criteria configuration per lecture
• student_performance_rule_achievements - Join table linking rules to required achievements (ensures referential integrity)
• student_performance_certifications - Teacher certification (pending/passed/failed) with audit and rule snapshot

Grading Schemes

Problem Overview

After an exam is graded and all points are recorded, MaMpf needs to:

• Convert points to grades: Map raw points/percentages to grade values (e.g., German scale 1.0-5.0)
• Support flexible config: Absolute point thresholds or percentage-based bands
• Enable analysis: Show distribution statistics before applying scheme
• Allow adjustments: Let instructors tweak cutoffs based on difficulty
• Handle manual overrides: Respect individual grade adjustments for special cases
• Ensure idempotency: Re-applying same scheme produces same results
• Maintain audit trail: Track which scheme was applied when and by whom

Solution Architecture

We use a configurable scheme model with service-based application:

• Canonical Source: GradeScheme::Scheme stores scheme configuration per assessment
• Absolute Bands: JSON config defines grade bands with either absolute points or percentages
• Service-Based Application: GradeScheme::Applier iterates participations and computes grades
• Version Control: Hash-based versioning prevents duplicate applications
• Override Respect: Manual grades bypass scheme application
• Distribution Analysis: Service provides statistics for informed decision-making
• Integration Point: Updates Assessment::Participation.grade_value field

GradeScheme::Scheme (ActiveRecord Model)

Grade Mapping Configuration

The main fields and methods of GradeScheme::Scheme are:

Behavior Highlights

• Only one active scheme per assessment (enforced via validation)
• Config structure varies by kind (see "Scheme Configurations" section below)
• version_hash enables idempotency: applying identical config is a no-op
• Draft schemes (not applied) can be edited freely
• Applied schemes are immutable (create new version to change)

Example Implementation

module GradeScheme
  class Scheme < ApplicationRecord
    self.table_name = "grade_schemes"

    belongs_to :assessment, class_name: "Assessment::Assessment"
    belongs_to :applied_by, class_name: "User", optional: true

    enum kind: { absolute: 0 }

  validates :assessment_id, uniqueness: { scope: :active, if: :active? }
  validates :config, presence: true
  validate :config_matches_kind

  before_save :compute_hash, if: :config_changed?

  def applied?
    applied_at.present?
  end

  def compute_hash
    self.version_hash = Digest::MD5.hexdigest(config.to_json)
  end

  private

  def config_matches_kind
    case kind.to_sym
    when :absolute
      # Check for either absolute points or percentage-based bands
      has_bands = config["bands"].is_a?(Array)
      errors.add(:config, "must have bands array") unless has_bands
      
      if has_bands
        first_band = config["bands"].first
        has_points = first_band&.key?("min_points")
        has_pct = first_band&.key?("min_pct")
        
        unless has_points || has_pct
          errors.add(:config, "bands must have either min_points/max_points or min_pct/max_pct")
        end
      end
    end
  end
  end
end

Usage Scenarios

• Creating a draft scheme: After an exam is graded, the professor creates: GradeScheme::Scheme.create!(assessment: exam_assessment, kind: :absolute, active: true, config: { bands: [...] }). The scheme is saved but applied_at remains nil.

• Analyzing distribution: Before applying, the professor requests distribution stats: GradeScheme::Applier.new(scheme).analyze_distribution. This returns { min: 15, max: 98, mean: 72, median: 74, percentiles: { 10 => 45, 25 => 60, ... } }.

• Adjusting cutoffs: Seeing the exam was harder than expected, the professor lowers cutoffs: scheme.update!(config: { bands: [...] }). The version_hash updates automatically.

• Applying scheme: The professor finalizes: GradeScheme::Applier.new(scheme).apply!(applied_by: professor). All participations get grade_value computed, scheme.applied_at is set.

• Preventing re-application: Someone tries to apply again: GradeScheme::Applier.new(scheme).apply!(applied_by: professor). The service checks version_hash, sees it matches, and returns early (idempotent).

Scheme Configurations

Absolute Cutoffs

Config structure (typical 60-point exam):

{
  "bands": [
    { "min_points": 54, "max_points": 60, "grade": "1.0" },
    { "min_points": 48, "max_points": 53, "grade": "1.3" },
    { "min_points": 42, "max_points": 47, "grade": "1.7" },
    { "min_points": 36, "max_points": 41, "grade": "2.0" },
    { "min_points": 33, "max_points": 35, "grade": "2.3" },
    { "min_points": 30, "max_points": 32, "grade": "3.0" },
    { "min_points": 27, "max_points": 29, "grade": "3.7" },
    { "min_points": 24, "max_points": 26, "grade": "4.0" },
    { "min_points": 0, "max_points": 23, "grade": "5.0" }
  ]
}

Field reference:

Grading example (60-point exam):

Percentage-Based Cutoffs

Config structure:

{
  "bands": [
    { "min_pct": 90, "max_pct": 100, "grade": "1.0" },
    { "min_pct": 80, "max_pct": 89.99, "grade": "1.3" },
    { "min_pct": 70, "max_pct": 79.99, "grade": "1.7" },
    { "min_pct": 60, "max_pct": 69.99, "grade": "2.0" },
    { "min_pct": 55, "max_pct": 59.99, "grade": "2.3" },
    { "min_pct": 50, "max_pct": 54.99, "grade": "3.0" },
    { "min_pct": 45, "max_pct": 49.99, "grade": "3.7" },
    { "min_pct": 40, "max_pct": 44.99, "grade": "4.0" },
    { "min_pct": 0, "max_pct": 39.99, "grade": "5.0" }
  ]
}

Field reference:

Grading example (same students, 60-point exam):

Interactive Curve Generation (Frontend Convenience)

Comparison of UI approaches:

Approach 1: Two-Point Auto-Generation

Workflow:

1. Teacher opens grading UI and sees histogram of all student scores
2. Teacher selects "Auto-generate from two points" mode
3. Teacher drags two markers on the histogram:
   • Excellence threshold: "54 points and above get 1.0"
   • Passing threshold: "30 points and above get 4.0 (pass)"
4. Frontend calculates linear interpolation for intermediate grades
5. Frontend displays preview: "54-60→1.0, 48-53→1.3, 42-47→1.7, ..."
6. Teacher can manually adjust any band boundary if desired (see below)
7. Frontend sends final absolute config to backend

Example JavaScript helper:

function generateLinearBands(excellentPts, passingPts, maxPts, gradeSteps) {
  const range = excellentPts - passingPts;
  const stepSize = range / (gradeSteps.length - 1);
  
  const bands = gradeSteps.map((grade, index) => {
    const minPts = Math.round(passingPts + (stepSize * index));
    const maxPts = index === 0 ? maxPts : 
                   Math.round(passingPts + (stepSize * (index + 1)) - 1);
    return { min_points: minPts, max_points: maxPts, grade };
  });
  
  // Add fail band below passing threshold
  bands.push({ min_points: 0, max_points: passingPts - 1, grade: "5.0" });
  
  return bands.sort((a, b) => b.min_points - a.min_points);
}

// Usage
const bands = generateLinearBands(54, 30, 60, 
  ["1.0", "1.3", "1.7", "2.0", "2.3", "3.0", "3.7", "4.0"]
);
// Send to backend: { kind: "absolute", config: { bands } }

Approach 2: Full Manual Curve Drawing

Workflow:

1. Teacher opens grading UI and sees histogram
2. Teacher selects "Manual curve" mode
3. Teacher drags individual boundary markers for each grade:
   • Drag "1.0/1.3 boundary" to set where 1.0 ends and 1.3 begins
   • Drag "1.3/1.7 boundary" to adjust next boundary
   • ... (continues for all grades)
4. Frontend displays current band configuration
5. Frontend sends complete absolute config to backend

Approach 3: Hybrid (Recommended)

Workflow:

1. Teacher selects "Auto-generate from two points"
2. System generates initial bands via linear interpolation
3. Teacher can then manually adjust individual boundaries:
   • "Hmm, let me be more generous with 1.0"
   • Drags the 1.0 minimum from 54 down to 50
   • System either:
     • Option A: Auto-adjusts neighboring bands to fill gaps
     • Option B: Shows warning "Gap detected between 1.0 and 1.3"
4. Teacher previews grade distribution with adjusted boundaries
5. Frontend sends final absolute config to backend

Example of manual adjustment after auto-generation:

// Auto-generated
const initialBands = generateLinearBands(54, 30, 60, grades);
// [{ min: 54, max: 60, grade: "1.0" }, { min: 48, max: 53, grade: "1.3" }, ...]

// Teacher drags 1.0 boundary down to 50
function adjustBand(bands, gradeToAdjust, newMinPoints) {
  const index = bands.findIndex(b => b.grade === gradeToAdjust);
  bands[index].min_points = newMinPoints;
  
  // Auto-adjust next band to avoid gaps
  if (index < bands.length - 1) {
    bands[index + 1].max_points = newMinPoints - 1;
  }
  
  return bands;
}

const adjustedBands = adjustBand(initialBands, "1.0", 50);
// [{ min: 50, max: 60, grade: "1.0" }, { min: 46, max: 49, grade: "1.3" }, ...]

Recommended UI elements:

Interactive UI Workflow (Hybrid Approach)

flowchart TD
    Start([Teacher opens grading UI]) --> LoadData[Load all student scores from assessment]
    LoadData --> ShowHistogram[Display histogram of score distribution]
    
    ShowHistogram --> ChooseMode{Teacher chooses mode}
    
    ChooseMode -->|Two-Point Auto| TwoPoint[Select two-point auto-generation]
    ChooseMode -->|Manual Drawing| Manual[Select manual curve mode]
    
    TwoPoint --> DragMarkers[Drag two markers on histogram]
    DragMarkers --> CalcInterpolation[Frontend calculates linear interpolation]
    CalcInterpolation --> GenerateBands[Generate bands array with all grades]
    GenerateBands --> ShowPreview
    
    Manual --> DragBoundaries[Drag individual grade boundaries]
    DragBoundaries --> BuildManualBands[Build bands from boundary positions]
    BuildManualBands --> ShowPreview
    
    ShowPreview[Show preview with histogram overlay] --> DisplayStats[Display grade distribution stats]
    
    DisplayStats --> TeacherReview{Teacher satisfied?}
    
    TeacherReview -->|No - adjust| AdjustChoice{Adjustment type?}
    AdjustChoice -->|Tweak specific band| DragOneBoundary[Drag single boundary marker]
    AdjustChoice -->|Reset and retry| ResetButton[Click reset button]
    
    DragOneBoundary --> AutoAdjustNeighbor[Auto-adjust neighboring band to avoid gaps]
    AutoAdjustNeighbor --> UpdatePreview[Update preview with new distribution]
    UpdatePreview --> DisplayStats
    
    ResetButton --> TwoPoint
    
    TeacherReview -->|Yes| ValidateBands{Bands valid?}
    
    ValidateBands -->|No gaps/overlaps| BuildConfig[Build config JSON]
    ValidateBands -->|Issues found| ShowWarning[Show validation warning]
    ShowWarning --> TeacherReview
    
    BuildConfig --> SendToBackend[Send POST request to backend]
    SendToBackend --> BackendValidate[Backend validates config]
    
    BackendValidate --> SaveScheme[Save GradeScheme::Scheme record]
    SaveScheme --> Success([Scheme created successfully])
    
    style Start fill:#e1f5ff
    style Success fill:#d4edda
    style ShowHistogram fill:#fff3cd
    style ShowPreview fill:#fff3cd
    style BuildConfig fill:#ffeaa7
    style ShowWarning fill:#f8d7da

Future Extensions

GradeScheme::Applier (Service Object)

Grade Computer

Public Interface

Behavior Highlights

• Idempotent: Checks version_hash before applying; skip if already applied
• Manual override respect: Skips participations with manual_grade_override flag
• Transaction-safe: Uses database transaction for consistency
• Efficient: Single query to load all participations, batch updates
• Statistics: Analyzes distribution for informed decision-making

Scheme Application Workflow

High-level phases:

1. Phase 1: Point Entry — Teachers enter task points for each student; grade column remains empty
2. Phase 2: Distribution Analysis — View histogram, statistics, and percentiles of achieved points
3. Phase 3: Scheme Configuration — Set excellence/passing thresholds (Two-Point Auto) or manually define grade boundaries (Manual Curve)
4. Phase 4: Scheme Applied — Grades auto-computed; point edits trigger automatic grade recalculation

flowchart TD
    Start([Exam grading complete]) --> CreateScheme[Professor creates draft scheme]
    CreateScheme --> AnalyzeDist[Analyze distribution statistics]
    
    AnalyzeDist --> ViewStats[View: min, max, mean, median, percentiles]
    ViewStats --> InitialConfig[Set initial config bands]
    
    InitialConfig --> Preview[Preview grade distribution]
    Preview --> ReviewResults[Review: How many pass/fail?]
    
    ReviewResults --> Satisfied{Satisfied with<br/>distribution?}
    
    Satisfied -->|No - too harsh| LowerThreshold[Lower cutoff thresholds]
    Satisfied -->|No - too lenient| RaiseThreshold[Raise cutoff thresholds]
    
    LowerThreshold --> UpdateConfig[Update scheme config]
    RaiseThreshold --> UpdateConfig
    UpdateConfig --> Preview
    
    Satisfied -->|Yes| Apply[Apply scheme to all participations]
    Apply --> Transaction[Database transaction starts]
    
    Transaction --> CheckHash{version_hash<br/>already applied?}
    CheckHash -->|Yes| SkipAll[Skip - idempotent]
    CheckHash -->|No| IterateParticipations[Iterate all participations]
    
    IterateParticipations --> CheckOverride{Has manual<br/>override?}
    CheckOverride -->|Yes| SkipStudent[Skip this student]
    CheckOverride -->|No| ComputeGrade[Compute grade from points]
    
    ComputeGrade --> UpdateGrade[Update grade_value]
    UpdateGrade --> MoreStudents{More students?}
    SkipStudent --> MoreStudents
    
    MoreStudents -->|Yes| CheckOverride
    MoreStudents -->|No| MarkApplied[Mark scheme as applied]
    
    MarkApplied --> Commit[Commit transaction]
    SkipAll --> Done([Application complete])
    Commit --> Done
    
    style Start fill:#e1f5ff
    style Done fill:#d4edda
    style Apply fill:#fff3cd
    style Satisfied fill:#ffeaa7

Grade Computation Algorithm

flowchart TD
    Start([compute_grade_for participation]) --> GetPoints[Get points_total from participation]
    GetPoints --> GetMaxPoints[Get effective_total_points from assessment]
    
    GetMaxPoints --> InspectBand[Inspect first band in config]
    InspectBand --> CheckFormat{Band format?}
    
    CheckFormat -->|Has min_points| AbsoluteFlow[Use absolute points scheme]
    CheckFormat -->|Has min_pct| PercentageFlow[Use percentage scheme]
    CheckFormat -->|Neither| Fallback[Return grade 5.0 - malformed config]
    
    AbsoluteFlow --> SortAbsBands[Sort bands by min_points descending]
    SortAbsBands --> FindAbsBand[Find band where:<br/>points >= min_points AND<br/>points <= max_points]
    FindAbsBand --> AbsFound{Band found?}
    AbsFound -->|Yes| ReturnAbsGrade[Return band grade]
    AbsFound -->|No| Return50Abs[Return grade 5.0]
    
    PercentageFlow --> CalcPct[Calculate percentage:<br/>points / max_points * 100]
    CalcPct --> SortPctBands[Sort bands by min_pct descending]
    SortPctBands --> FindPctBand[Find band where:<br/>percentage >= min_pct AND<br/>percentage <= max_pct]
    FindPctBand --> PctFound{Band found?}
    PctFound -->|Yes| ReturnPctGrade[Return band grade]
    PctFound -->|No| Return50Pct[Return grade 5.0]
    
    ReturnAbsGrade --> End([Grade returned])
    Return50Abs --> End
    ReturnPctGrade --> End
    Return50Pct --> End
    Fallback --> End
    
    style Start fill:#e1f5ff
    style End fill:#d4edda
    style Fallback fill:#f8d7da
    style Return50Abs fill:#f8d7da
    style Return50Pct fill:#f8d7da
    style ReturnAbsGrade fill:#d4edda
    style ReturnPctGrade fill:#d4edda

Example Implementation

module GradeScheme
  class Applier
    def initialize(scheme)
      @scheme = scheme
      @assessment = scheme.assessment
    end

  def analyze_distribution
    participations = @assessment.participations.where(status: :graded)
    points = participations.pluck(:points_total)
    max_points = @assessment.effective_total_points

    {
      count: points.size,
      min: points.min,
      max: points.max,
      mean: points.sum.to_f / points.size,
      median: points.sort[points.size / 2],
      percentiles: calculate_percentiles(points),
      max_possible: max_points
    }
  end

  def apply!(applied_by:)
    return if already_applied?

    Assessment::Participation.transaction do
      participations = @assessment.participations.where(status: :graded)
      
      participations.each do |participation|
        next if participation.manual_grade_override?
        
        grade = compute_grade_for(participation)
        participation.update!(grade_value: grade)
      end

      @scheme.update!(applied_at: Time.current, applied_by: applied_by)
    end
  end

  def preview
    participations = @assessment.participations.where(status: :graded)
    
    participations.map do |p|
      {
        user_id: p.user_id,
        points: p.points_total,
        percentage: percentage_for(p),
        proposed_grade: compute_grade_for(p),
        current_grade: p.grade_value
      }
    end
  end

  private

  def already_applied?
    @scheme.applied? && @scheme.version_hash == @scheme.compute_hash
  end

  def compute_grade_for(participation)
    points = participation.points_total
    max_points = @assessment.effective_total_points
    
    # Determine if using absolute points or percentage-based
    first_band = @scheme.config["bands"].first
    
    if first_band.key?("min_points")
      apply_absolute_points_scheme(points)
    elsif first_band.key?("min_pct")
      percentage = percentage_for(participation)
      apply_percentage_scheme(percentage)
    else
      "5.0" # Fallback if config is malformed
    end
  end

  def percentage_for(participation)
    max = @assessment.effective_total_points
    return 0 if max.zero?
    (participation.points_total.to_f / max * 100).round(2)
  end

  def apply_absolute_points_scheme(points)
    bands = @scheme.config["bands"].sort_by { |b| -b["min_points"] }
    band = bands.find { |b| points >= b["min_points"] && points <= b["max_points"] }
    band ? band["grade"] : "5.0"
  end

  def apply_percentage_scheme(percentage)
    bands = @scheme.config["bands"].sort_by { |b| -b["min_pct"] }
    band = bands.find { |b| percentage >= b["min_pct"] && percentage <= b["max_pct"] }
    band ? band["grade"] : "5.0"
  end

  def calculate_percentiles(points)
    sorted = points.sort
    {
      10 => sorted[(sorted.size * 0.1).floor],
      25 => sorted[(sorted.size * 0.25).floor],
      50 => sorted[(sorted.size * 0.5).floor],
      75 => sorted[(sorted.size * 0.75).floor],
      90 => sorted[(sorted.size * 0.9).floor]
    }
  end
  end
end

Usage Scenarios

• Preview before applying: Professor wants to see results: preview = GradeScheme::Applier.new(scheme).preview. They review the proposed grades and see that 5 students would fail.

• Adjust and re-preview: Professor lowers the passing threshold: scheme.update!(config: { ... }), then previews again. Now only 2 students fail, which seems fair.

• Final application: Professor applies: GradeSchemeApplier.new(scheme).apply!(applied_by: professor). All 150 students get their grade_value set.

• Manual override: One student had exceptional circumstances. The tutor marks: participation.update!(manual_grade_override: true, grade_value: "2.0"). Future scheme applications will skip this record.

• Idempotent reapplication: System accidentally triggers apply again: GradeSchemeApplier.new(scheme).apply!(applied_by: professor). The service detects identical version_hash and returns immediately.

Integration with Assessment System

Relationship to Assessment::Gradable

The Assessment::Gradable concern already provides:

• grade_value field on Assessment::Participation
• Manual grade entry capability

Grading schemes add:

• Automated computation from points
• Configurable mapping logic
• Version control and audit trail
• Distribution analysis tools

When to Use

Usage Scenarios

• After exam grading: All task points are entered and Assessment::Participation.points_total values are computed. The professor creates a GradeScheme::Scheme to convert these points to final grades.

• Manual grade override: A student with exceptional circumstances gets participation.manual_grade_override = true and a direct grade entry. When the scheme is applied, this participation is skipped.

• Re-grading scenario: A mistake is found in one student's exam. The tutor corrects their task points. The points_total updates via callback. The professor could re-apply the scheme (with same config) to update just that grade, but the idempotency check would skip all unchanged participations.

ERD

erDiagram
    GRADE_SCHEME_SCHEME ||--|| ASSESSMENT : "applies to"
    GRADE_SCHEME_SCHEME }o--|| USER_APPLIED_BY : "applied by"
    ASSESSMENT ||--o{ PARTICIPATION : "has"
    PARTICIPATION ||--o| GRADE_VALUE : "computed by scheme"

Sequence Diagram

sequenceDiagram
    actor Professor
    participant Assessment as Assessment::Assessment
    participant Scheme as GradeScheme::Scheme
    participant Applier as GradeScheme::Applier
    participant Participation as Assessment::Participation

    rect rgb(235, 245, 255)
    note over Professor,Participation: Phase 1: Exam Grading Complete
    Assessment->>Assessment: all task points entered
    Assessment->>Participation: points_total computed for all students
    end

    rect rgb(255, 245, 235)
    note over Professor,Scheme: Phase 2: Scheme Configuration
    Professor->>Scheme: create(kind: absolute, config: {...})
    Professor->>Applier: analyze_distribution
    Applier->>Participation: aggregate points statistics
    Applier-->>Professor: show distribution (mean, percentiles)
    Professor->>Scheme: update(config: adjusted_bands)
    end

    rect rgb(245, 255, 245)
    note over Professor,Participation: Phase 3: Preview & Apply
    Professor->>Applier: preview
    Applier->>Participation: compute proposed grades
    Applier-->>Professor: show grade preview
    Professor->>Applier: apply!(applied_by: professor)
    Applier->>Applier: check version_hash (idempotency)
    loop for each participation
        alt not manual override
            Applier->>Participation: update(grade_value: computed_grade)
        else manual override
            Applier->>Participation: skip
        end
    end
    Applier->>Scheme: update(applied_at, applied_by)
    end

Proposed Folder Structure

app/
└── models/
    └── grade_scheme/
        ├── scheme.rb
        └── applier.rb

Key Files

• app/models/grade_scheme/scheme.rb - Versioned scheme configuration
• app/models/grade_scheme/applier.rb - Grade computation and application logic

Database Tables

• grade_schemes - Scheme configurations with version control

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

Allocation Algorithm Details

Purpose

This chapter details the algorithm for allocating users to Registration::Items (tutorials, talks, etc.) based on ranked preferences while respecting item capacities.

The initial implementation uses a Min-Cost Flow algorithm for its speed and simplicity. The system is designed with a pluggable service interface, allowing a more powerful CP-SAT solver to be used in the future when advanced constraints are needed.

The Strategy Pattern Approach

The system uses a Strategy Pattern to separate the high-level allocation process from the low-level solver implementation. A single service entry point is exposed:

Registration::AllocationService.new(campaign, strategy: :min_cost_flow).allocate!

This allows different solver strategies to be added (e.g., strategy: :cp_sat) without changing any calling code.

Performance

Typical wall time for a campaign with 1,000 users, 50 items, and 3–10 preferences each:

Conclusion: Min-Cost Flow is more than sufficient for the initial scope and scales well. Even with 10,000 users, it remains sub-second.

Modeling Details (Min-Cost Flow)

Graph Components

• Source (S): The starting point for all "flow" (users).
• User Nodes (U): One node for each participating user.
• Item Nodes (I): One node for each available Registration::Item.
• Dummy Node (D): An optional node representing the "unassigned" state.
• Sink (T): The final destination for all flow.

Graph Arcs (Edges)

• S → u: For each user u, an arc with capacity 1 and cost 0.
• u → i: For each stated preference, an arc from user u to item i with capacity 1 and cost equal to the preference_rank.
• i → T: For each item i, an arc with capacity equal to item.capacity and cost 0.
• u → D: (If allowing unassigned) An arc from each user u to the dummy node D with capacity 1 and a high penalty cost.
• D → T: (If allowing unassigned) An arc from D to T with capacity equal to the total number of users.

This model guarantees that exactly one unit of flow per user leaves the source, ensuring each user is assigned to at most one real item.

Cost Calibration

• Preference Rank: The cost is the rank itself (1, 2, 3...).
• Fallback Cost: For "fill unlisted items" mode, the cost is max_rank + 2.
• Penalty Cost: The cost for the "unassigned" dummy path is a large constant (e.g., 10_000) to ensure it's only used as a last resort.

Unassigned semantics and defaults

• Defaults we use in tutorial campaigns:
  • fill_unlisted: true at campaign level, no per-student opt-in. This adds edges from each user to all eligible, unranked items at cost max_rank + 2, ensuring a high chance of receiving a seat even beyond the ranked list.
  • allow_unassigned: true with a large dummy penalty. This guarantees feasibility; the dummy path is used only if every eligible item is saturated.
• After allocation and upon close-out/finalization, any remaining pending registrations must be normalized to rejected. A user is considered "assigned" if they have exactly one confirmed registration in the campaign; otherwise they are "unassigned".
• The "unassigned" cohort is derived data: users who participated in the campaign but ended up with no confirmed registration. No extra tables are required.

Service Implementation (Strategy Pattern Skeleton)

# filepath: app/services/registration/allocation_service.rb
module Registration
    class AllocationService
        def initialize(campaign, strategy: :min_cost_flow, **opts)
            @campaign = campaign
            @strategy = strategy
            @opts = opts
        end

    def allocate!
            solver =
                case @strategy
                when :min_cost_flow
                    Registration::Solvers::MinCostFlow.new(@campaign, **@opts)
                # when :cp_sat then Registration::Solvers::CpSat.new(@campaign, **@opts)
                else
                    raise ArgumentError, "Unknown strategy #{@strategy}"
                end
            solver.run
        end
    end
end

# Solvers are placed in their own module for organization.
module Registration
    module Solvers
    class MinCostFlow
            BIG_PENALTY = 10_000

            def initialize(campaign, fill_unlisted: false, allow_unassigned: true)
                @campaign = campaign
                @fill_unlisted = fill_unlisted
                @allow_unassigned = allow_unassigned
                @prefs = campaign.user_registrations.where.not(preference_rank: nil)
                                                                                        .includes(:registration_item)
                @users = @prefs.map(&:user_id).uniq
                @items = campaign.registration_items.includes(:registerable)
                @prefs_by_user = @prefs.group_by(&:user_id)
                @max_rank = (@prefs.map(&:preference_rank).max || 1)
                @fallback_cost = @max_rank + 2
            end

            def run
                return finalize_empty if @users.empty?
                build_and_solve
            end

            private

            def finalize_empty
                @campaign.update!(status: 'completed')
            end

            def build_and_solve
                mcf = ORTools::SimpleMinCostFlow.new

                source = 0
                user_offset = 1
                item_offset = user_offset + @users.size
                sink_real = item_offset + @items.size
                dummy_node = sink_real + 1 if @allow_unassigned
                sink_final = @allow_unassigned ? dummy_node + 1 : sink_real

                idx_user = {}
                idx_item = {}

                @users.each_with_index { |uid, i| idx_user[uid] = user_offset + i }
                @items.each_with_index { |item, i| idx_item[item.id] = item_offset + i }

                mcf.set_node_supply(source, @users.size)
                mcf.set_node_supply(sink_final, -@users.size)
                (user_offset...item_offset).each { |n| mcf.set_node_supply(n, 0) }
                (item_offset...sink_real).each { |n| mcf.set_node_supply(n, 0) }
                if @allow_unassigned
                    mcf.set_node_supply(sink_real, 0)
                    mcf.set_node_supply(dummy_node, 0)
                end

                @users.each do |uid|
                    mcf.add_arc_with_capacity_and_unit_cost(source, idx_user[uid], 1, 0)
                end

                @prefs.each do |reg|
                    mcf.add_arc_with_capacity_and_unit_cost(
                        idx_user[reg.user_id],
                        idx_item[reg.registration_item_id],
                        1,
                        reg.preference_rank.to_i <= 0 ? 1 : reg.preference_rank.to_i
                    )
                end

                if @fill_unlisted
                    @users.each do |uid|
                        listed = (@prefs_by_user[uid] || []).map(&:registration_item_id)
                        (@items.map(&:id) - listed).each do |iid|
                            mcf.add_arc_with_capacity_and_unit_cost(
                                idx_user[uid],
                                idx_item[iid],
                                1,
                                @fallback_cost
                            )
                        end
                    end
                end

                @items.each do |item|
                    cap = [item.registerable.capacity.to_i, 0].max
                    mcf.add_arc_with_capacity_and_unit_cost(
                        idx_item[item.id],
                        (@allow_unassigned ? sink_real : sink_final),
                        cap,
                        0
                    )
                end

                if @allow_unassigned
                    mcf.add_arc_with_capacity_and_unit_cost(dummy_node, sink_final, @users.size, 0)
                    @users.each do |uid|
                        mcf.add_arc_with_capacity_and_unit_cost(idx_user[uid], dummy_node, 1, BIG_PENALTY)
                    end
                end

                status = mcf.solve
                return fail_solver unless status == ORTools::SimpleMinCostFlow::OPTIMAL

                apply_solution(mcf, idx_user, idx_item, dummy_node)
            end
        end
    end
end

Graph Diagram (Placeholder)

graph LR
	S((S)) --> U1((User1))
	S --> U2((User2))
	U1 --> I1[(ItemA)]
	U1 --> I2[(ItemB)]
	U2 --> I2
	I1 --> T((T))
	I2 --> T
	U1 --> D((Dummy))
	U2 --> D
	D --> T

Examples & Demos

Unified End-to-End Demo (Phases 0–12)

This demo walks through a complete semester lifecycle, from setup to final reporting. It assumes the models and services from the architectural documentation are implemented.

# --- Phase 0: Semester Setup ---
# Create lecture
lecture = FactoryBot.create(:lecture_with_sparse_toc, "with_title",
                            title: "Linear Algebra I")

# Create users simulating mixed email domains (valid + invalid)
domains = %w[student.uni.edu uni.edu gmail.com]
users = (1..12).map do |i|
  FactoryBot.create(:confirmed_user,
                    email: "user#{i}@#{domains[i % domains.size]}",
                    name: "User #{i}")
end

# Create tutorials
tutorials = (1..3).map do |n|
  FactoryBot.create(:tutorial, lecture: lecture, title: "Tutorial #{n}", capacity: 10)
end

# --- Phase 1: Tutorial Registration ---
tut_campaign = Registration::Campaign.create!(
  campaignable: lecture,
  title: "Tutorial Registration WS 2024/25",
  allocation_mode: :preference_based,
  registration_deadline: 10.days.from_now
)

# Create registration items for each tutorial
tutorials.each do |tut|
  tut_campaign.registration_items.create!(registerable: tut)
end

# Add institutional email policy
tut_campaign.registration_policies.create!(
  kind: :institutional_email,
  position: 1,
  active: true,
  config: { "allowed_domains" => ["uni.edu", "student.uni.edu"] }
)

tut_campaign.update!(status: :open)

# Users submit ranked preferences.
# In a real UI, the controller would use `evaluate_policies_for(user)` before
# allowing a submission.
eligible_submitters = users.select do |u|
  tut_campaign.evaluate_policies_for(u).pass
end
ri_map = tut_campaign.registration_items.index_by(&:registerable_id)

eligible_submitters.each do |user|
  shuffled = tutorials.shuffle
  shuffled.each_with_index do |tut, rank|
    Registration::UserRegistration.create!(
      user: user,
      registration_campaign: tut_campaign,
      registration_item: ri_map[tut.id],
      status: :pending,
      preference_rank: rank + 1
    )
  end
end

# --- Phase 2: Tutorial Allocation ---
# Close registration and run allocation algorithm
tut_campaign.update!(registration_deadline: Time.current - 1.second)
tut_campaign.allocate_and_finalize!

# --- Phase 3: Roster Materialization ---
# Materialization happens automatically within `allocate_and_finalize!`
puts "\nTutorial Rosters After Materialization:"
tutorials.each do |tut|
  # Assuming a `roster_user_ids` method exists on the registerable
  puts "  #{tut.title}: #{tut.roster_user_ids.size} students"
end

# --- Phase 4: Roster Maintenance ---
# Move one student from Tutorial 1 to Tutorial 2
from_tut = tutorials.first
to_tut = tutorials.second
student_to_move_id = from_tut.roster_user_ids.first

if student_to_move_id
  # Assuming a Roster Maintenance service exists
  puts "Moved student #{student_to_move_id} from #{from_tut.title} to #{to_tut.title}"
end

# --- Phase 5: Coursework Assessments ---
# Create two homework assignments with tasks
hw1 = FactoryBot.create(:assignment, lecture: lecture, title: "Homework 1")
hw1_assessment = FactoryBot.create(:assessment, assessable: hw1, title: "Homework 1")
(1..3).each { |i| hw1_assessment.tasks.create!(title: "Problem #{i}", max_points: 10) }

hw2 = FactoryBot.create(:assignment, lecture: lecture, title: "Homework 2")
hw2_assessment = FactoryBot.create(:assessment, assessable: hw2, title: "Homework 2")
(1..3).each { |i| hw2_assessment.tasks.create!(title: "Problem #{i}", max_points: 10) }

# Seed participations from tutorial rosters
lecture_students = users.select { |u| u.email.ends_with?("uni.edu") || u.email.ends_with?("student.uni.edu") }
[hw1_assessment, hw2_assessment].each do |assessment|
  lecture_students.each do |student|
    FactoryBot.create(:participation, assessment: assessment, user: student)
  end
end

# Simulate grading with random points
[hw1_assessment, hw2_assessment].each do |assessment|
  assessment.participations.find_each do |part|
    total_points = 0
    assessment.tasks.each do |task|
      points = rand((task.max_points * 0.4)..task.max_points)
      FactoryBot.create(:task_point, participation: part, task: task, points: points)
      total_points += points
    end
    part.update!(points_total: total_points, status: :graded)
  end
end

# --- Phase 6: Achievement Tracking ---
# Award achievements to first three eligible students
eligible_submitters.first(3).each do |u|
  FactoryBot.create(:achievement,
    lecture: lecture,
    user: u,
    kind: "blackboard_explanation",
    achievable: lecture
  )
end
puts "\nAchievements awarded to #{eligible_submitters.first(3).map(&:name).join(', ')}"

# --- Phase 7: Student Performance Materialization ---
# Configure eligibility rule
rule = StudentPerformance::Rule.find_or_create_by!(lecture: lecture)
rule.update!(
  min_points: 30, # 50% of 60 total points
  required_achievements: { "blackboard_explanation" => 1 },
  assessment_types: ["Assignment"]
)

# Compute performance facts for all students (e.g., via a background job)
service = StudentPerformance::Service.new(lecture)
service.compute_and_upsert_all_records!

puts "\nPerformance records computed for #{lecture_students.size} students"

# --- Phase 8: Exam Registration ---
# Create an exam belonging to the lecture
exam = FactoryBot.create(:exam,
  lecture: lecture,
  title: "Hauptklausur",
  date: 4.weeks.from_now,
  capacity: 100
)

# The lecture (campaignable) hosts the exam registration campaign
exam_campaign = lecture.registration_campaigns.create!(
  title: "Hauptklausur Registration",
  allocation_mode: :first_come_first_served,
  registration_deadline: 2.weeks.from_now,
  status: :open
)

# The exam is the sole registerable item
exam_campaign.registration_items.create!(registerable: exam)

puts "\nExam campaign created: #{exam_campaign.title} (deadline: #{exam_campaign.registration_deadline})"

# --- Phase 8: Teacher Certification ---
# Generate eligibility proposals using the Evaluator
evaluator = StudentPerformance::Evaluator.new(rule)
proposals = {}

lecture_students.each do |student|
  record = StudentPerformance::Record.find_by(lecture: lecture, user: student)
  result = evaluator.evaluate(record)
  proposals[student.id] = result.status
end

puts "\nProposals generated: #{proposals.values.count(:passed)} passed, #{proposals.values.count(:failed)} failed"

# Teacher reviews and bulk-accepts proposals
teacher = users.first # Assuming first user is the teacher
lecture_students.each do |student|
  StudentPerformance::Certification.create!(
    user: student,
    lecture: lecture,
    record: StudentPerformance::Record.find_by(lecture: lecture, user: student),
    rule: rule,
    status: proposals[student.id],
    certified_at: Time.current,
    certified_by: teacher
  )
end

eligible_count = StudentPerformance::Certification.where(lecture: lecture, status: :passed).count
puts "Certifications created: #{eligible_count} students certified as passed"

# Override one failed student (e.g., medical certificate)
failed_cert = StudentPerformance::Certification.find_by(lecture: lecture, status: :failed)
if failed_cert
  failed_cert.update!(
    status: :passed,
    note: "Medical certificate provided",
    certified_at: Time.current,
    certified_by: teacher
  )
  puts "Manual override: Student #{failed_cert.user.name} status changed to passed"
end

# --- Phase 9: Exam Registration Campaign ---
# Create exam belonging to the lecture
exam = FactoryBot.create(:exam, lecture: lecture, capacity: 100)

# The lecture (campaignable) hosts the exam registration campaign
exam_campaign = Registration::Campaign.create!(
  campaignable: lecture,
  title: "Hauptklausur Registration",
  allocation_mode: :first_come_first_served,
  registration_deadline: 2.weeks.from_now
)
# The exam is the sole registerable item
exam_item = exam_campaign.registration_items.create!(registerable: exam)

# Add policies: student performance + institutional email
exam_campaign.registration_policies.create!(
  kind: :student_performance,
  position: 1,
  active: true,
  config: { "lecture_id" => lecture.id }
)
exam_campaign.registration_policies.create!(
  kind: :institutional_email,
  position: 2,
  active: true,
  config: { "allowed_domains" => ["uni.edu", "student.uni.edu"] }
)
# --- Phase 9: Exam Registration Campaign ---
# Create exam first
exam = FactoryBot.create(:exam, lecture: lecture, capacity: 100)

# Create registration campaign
exam_campaign = Registration::Campaign.create!(
  campaignable: exam,
  title: "Final Exam Registration",
  allocation_mode: :first_come_first_served,
  registration_deadline: 2.weeks.from_now,
  status: :draft
)
exam_item = exam_campaign.registration_items.create!(registerable: exam)

# Add policies: student performance + institutional email
exam_campaign.registration_policies.create!(
  kind: :student_performance,
  position: 1,
  active: true,
  phase: :registration,
  config: { "lecture_id" => lecture.id }
)
exam_campaign.registration_policies.create!(
  kind: :institutional_email,
  position: 2,
  active: true,
  phase: :registration,
  config: { "allowed_domains" => ["uni.edu", "student.uni.edu"] }
)

# Pre-flight check: verify certification completeness before opening
all_certified = lecture_students.all? do |student|
  cert = StudentPerformance::Certification.find_by(lecture: lecture, user: student)
  cert.present? && cert.status.in?([:passed, :failed])
end

if all_certified
  exam_campaign.update!(status: :open)
  puts "\nExam campaign opened (all students certified)"
else
  puts "\nCampaign opening blocked: incomplete certifications"
  exit
end

# Eligible students register for exam. Policy checks Certification status.
puts "\nExam Registration Process:"
lecture_students.each do |user|
  result = exam_campaign.evaluate_policies_for(user, phase: :registration)
  if result.pass
    puts "  - Student #{user.name}: Eligible (certification: passed). Registering..."
    Registration::UserRegistration.create!(
      user: user,
      registration_campaign: exam_campaign,
      registration_item: exam_item,
      status: :confirmed
    )
  else
    cert = StudentPerformance::Certification.find_by(lecture: lecture, user: user)
    puts "  - Student #{user.name}: Ineligible. Certification status: #{cert&.status || 'missing'}"
  end
end

# Finalize campaign (materializes exam roster after re-checking certifications)
exam_campaign.finalize!
puts "\n#{exam_campaign.user_registrations.confirmed.count} students registered for exam"

# --- Phase 10: Exam Grading ---
# Create assessment for exam
exam_assessment = FactoryBot.create(:assessment, assessable: exam, title: "Final Exam")
task1 = exam_assessment.tasks.create!(title: "Problem 1", max_points: 40)
task2 = exam_assessment.tasks.create!(title: "Problem 2", max_points: 30)
task3 = exam_assessment.tasks.create!(title: "Problem 3", max_points: 30)

# Seed participations from exam roster
exam_campaign.user_registrations.confirmed.each do |reg|
  FactoryBot.create(:participation, assessment: exam_assessment, user: reg.user)
end

# Simulate grading
exam_assessment.participations.find_each do |part|
  points = rand(40..100)
  part.update!(points_total: points)
end

# Create and apply grade scheme
exam_scheme = GradeScheme::Scheme.create!(
  title: "Final Exam Grading",
  bands: [
    { "min_points" => 90, "grade" => "1.0" },
    { "min_points" => 80, "grade" => "2.0" },
    { "min_points" => 70, "grade" => "3.0" },
    { "min_points" => 60, "grade" => "4.0" },
    { "min_points" => 0, "grade" => "5.0" }
  ]
)
# Assuming an applier service exists
# GradeScheme::Applier.new(exam_assessment, exam_scheme).apply!

puts "\nExam graded (conceptual)."

# --- Phase 11: Late Adjustments ---
# Simulate late homework grade change
late_part = hw1_assessment.participations.first
old_points = late_part.points_total
late_part.update!(points_total: old_points + 5)
puts "\nLate adjustment: Student #{late_part.user.name} HW1 points: #{old_points} → #{late_part.points_total}"

# The change triggers record recomputation and marks certification as stale
service.compute_and_upsert_record_for(late_part.user)
cert = StudentPerformance::Certification.find_by(lecture: lecture, user: late_part.user)
puts "  - Performance record recomputed"
puts "  - Certification marked for review (teacher must re-certify before next campaign)"

# Teacher must review and re-certify
# In real workflow, teacher would see "Certification Stale" warning in UI
# and must manually review before opening new campaigns

# --- Phase 12: Reporting & Export ---
puts "\n=== Final Report ==="
puts "Lecture: #{lecture.title}"
puts "Total students in course: #{lecture_students.size}"
puts "Tutorial registrations: #{tut_campaign.user_registrations.confirmed.count}"
puts "Exam registered: #{exam_campaign.user_registrations.confirmed.count}"

Key Observations

This demo illustrates:

1. Complete Lifecycle: All phases from setup to reporting.
2. Three-Layer Architecture:
   • Records store factual performance data (points, achievements)
   • Evaluator generates eligibility proposals (computational layer)
   • Certifications capture teacher decisions (authoritative layer)
3. Pre-Flight Checks: Campaigns cannot open without complete certifications, ensuring policy consistency.
4. No Runtime Recomputation: Exam registration looks up pre-existing Certifications instead of computing eligibility on-the-fly.
5. Roster Management: Materialization populates tutorial and exam rosters from confirmed registrations.
6. Late Adjustments: Grade changes trigger record recomputation and mark certifications for teacher review, but existing certifications remain valid until manually updated.
7. Composable Policies: The exam campaign combines student_performance and institutional_email policies seamlessly, with phase-aware evaluation.
8. Teacher Control: Teachers explicitly review and certify all eligibility decisions, maintaining accountability and enabling manual overrides.

Integrity & Invariants

This chapter documents the key invariants and integrity constraints that ensure system correctness throughout the semester lifecycle.

1. Registration & Allocation

Database Constraints

# One confirmed submission per user per campaign
add_index :registration_submissions,
          [:registration_campaign_id, :user_id],
          unique: true,
          where: "status = 'confirmed'",
          name: "idx_unique_confirmed_submission"

# Unique preference ranks per user per campaign
add_index :registration_submissions,
          [:user_id, :registration_campaign_id, :preference_rank],
          unique: true,
          where: "preference_rank IS NOT NULL",
          name: "idx_unique_preference_rank"

Application-Level Invariants

2. Rosters & Materialization

Core Invariants

Reconciliation

Background job periodically checks:

• Roster user count vs. capacity limit
• Orphan roster entries (user deleted but still in roster)

3. Assessments & Grading

Database Constraints

# One participation per (assessment, user)
add_index :assessment_participations,
          [:assessment_id, :user_id],
          unique: true,
          name: "idx_unique_participation"

# One task point per (participation, task)
add_index :assessment_task_points,
          [:participation_id, :task_id],
          unique: true,
          name: "idx_unique_task_point"

# Foreign key integrity
add_foreign_key :assessment_tasks, :assessments
add_foreign_key :assessment_task_points, :assessment_tasks, column: :task_id
add_foreign_key :assessment_task_points, :assessment_participations, column: :participation_id

Application-Level Invariants

4. Student Performance & Certification

Database Constraints

# One performance record per (lecture, user)
add_index :student_performance_records,
          [:lecture_id, :user_id],
          unique: true,
          name: "idx_unique_performance_record"

# One certification per (lecture, user)
add_index :student_performance_certifications,
          [:lecture_id, :user_id],
          unique: true,
          name: "idx_unique_certification"

# Foreign key integrity
add_foreign_key :student_performance_certifications,
                :student_performance_records,
                column: :record_id,
                optional: true
add_foreign_key :student_performance_certifications,
                :student_performance_rules,
                column: :rule_id,
                optional: true

Application-Level Invariants