Course seat management

[g-bar]

This PR implements most of the functionality required for the education plan: https://github.com/openbraininstitute/PMO/issues/96

Courses Provisioning

Relationships

                        ┌─────────────┐
                        │ Institution │
                        └──────┬──────┘
                               │ 1
                               │
                               *
┌─────────────┐         ┌─────────────┐
│ Virtual Lab │1──────1 │ Course                                                    │
└─────────────┘         └──────┬──────┘
                               │ 1
                               │
                               *
                        ┌─────────────┐
                        │    Seat     │
                        └──────┬──────┘
                               │ 0..1
                               │
                               1
┌─────────────┐         ┌─────────────┐
│   Project   │1───────1│  Enrolment  │
└─────────────┘         └─────────────┘

Course Lifecycle

Provisioning

1. OBI admin creates a virtual lab belonging to obi-virtual-lab.
   POST /virtual-labs
2. OBI admin creates a template project for that virtual lab.
   POST /virtual-labs/{vlab_id}/projects
3. OBI admin creates a course pointing to the virtual lab and template project.
   POST /courses
4. OBI admin sets start_date, last_drop_date, and end_date.
   PATCH /courses/{course_id}
5. OBI admin activates the course (all dates must be set).
   POST /courses/{course_id}/activate
6. OBI admin invites faculty as virtual lab admin.
   POST /virtual-labs/{vlab_id}/invites
7. OBI admin provisions seats (only active courses can be provisioned).
   POST /seats/provision

Enrolment

1. Faculty assigns available seats to students (identified by student id + email).
   POST /seats/courses/{course_id}/assign
   This creates an enrolment and a project per student and sends an invite email.

2. Student claims the enrolment, storing their user_id.
   POST /courses/{course_id}/claim

3. On login (after start_date, before end_date), the student's enrolment is activated (added to KC groups).
   POST /courses/activate-enrolments

Dropping

Faculty can drop a student and recover the seat if all conditions are met:

• seat.previously_dropped == False
• now < course.last_drop_date
• The student's project has spent fewer than 50 credits.

POST /seats/courses/{course_id}/drop

When dropped, the student's project budget is depleted and the student is removed from KC groups (vlab and project).

Course Expiry

A daily cronjob checks courses whose end_date has passed, drops every remaining student, and depletes all credits from all projects and the virtual lab.

[pgetta]

Great work Gil!

I've added some comments and questions.

[pgetta]

Thank you Gil.

I'm good with the change, but I'll let you finish the discussion with @bilalesi.

As for the institutions - we can revise that later, either future use cases will confirm they are needed or we just refactor and delete them.

[bilalesi]

Great work @g-bar,

about your question about the ledger:
think of it like an "undo notebook." when the use case is doing a bunch of steps, creating a Keycloak group, setting up accounting, create seat, ..., each step pushes an undo action onto the ledger. If something blows up halfway, the ledger runs all those undos in reverse (last one first), so you don't end up with half-created stuff floating around

the pattern can be applied to any use cases, you just need to figure out how you order, function implementation, and either throw directly/postpone, this make the mental model and steps of creation very clear both for us and the machine, the other nice thing about the ledger is to have domain errors with the translator which can be very helpful in debugging

still have few comments/questions but it can be in another improvement PR/chat

[bilalesi]

i would also suggest to see the ledger and compensation tools,
the tool is allow you to create actions and reverse actions, all managed by the ledger (virtual lab creation)
here the catch path only soft-deletes the project and does not reverse/deplete the granted credits

[g-bar]

I refactored this to use the ledger now I create the project, init accounting, fund project, create an enrolment and assign a seat using the ledger to roll back failed ops, all while not committing anything to the db until after all iterations are done to avoid releasing the seats prematurely.

[bilalesi]

this is also best use case for the ledger pattern

[g-bar]

this one not quite, the create_course doesnt create a virtual lab, it merely points to an existing virtual lab created previously.

there is nothing to clean up in case of failure, merely the course row doesnt'get created the virtual lab and project remain valid.

[bilalesi]

the endpoint can create a project even the funding was not successful, is that okey ?

[g-bar]

same as above, the project doesn't get created here.

[github-actions]

/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/safety/auth/main.py:6: AuthlibDeprecationWarning: authlib.jose module is deprecated, please use joserfc instead.
It will be compatible before version 2.0.0.
from authlib.jose import jwt

poetry audit report

Loading...
Scanning 109 packages...

• starlette installed 0.52.1 affected <1.0.1 CVE CVE-2026-48710

1 vulnerabilities found in 1 packages