GET/en/projects/driving-school
A management system for Italian driving schools: students, instructors, lessons, exams and payments, for several schools on one installation.
The idea comes from the years I worked at a driving school. It was meant to be both a product and a study project, and it stayed the latter: the development environment of the Motorizzazione, the Italian licensing authority, is open only to software companies.
Several schools share the same installation, and the same person can be an instructor at one school and a student at another. The goal was to keep each school’s data apart, and the boundaries between the parts of the domain, while the project grew.
It started with some classmates from my ITS course, and I carried it on alone. The design, the goals and the choices are mine; I wrote the code with the help of Claude Code.
A single application, split into modules by area of the domain. Each module declares what it depends on and what it exposes, and Spring Modulith checks it in a test: an undeclared dependency makes it fail.
Highlighted: scheduling, the lessons module. The lines join it to the modules it depends on.
common holds what every module needs: security, audit, events.
Highlighted: scheduling, the lessons module, with the modules it depends on.
scheduling
depends on
The other modules: auth, exam, finance, quiz.
common holds what every module needs: security, audit, events.
A week’s agenda, from the client to the database. Every school lives in the same database, so each layer checks that the request stays inside its school, and stops it if it doesn’t.
GET /
X-School-Id the school being worked on, next to the token
security Spring Security
403 no active membership in that school
controller REST endpoint
403 the user isn’t a member of the school in the path
service scheduling module
404 path and header name different schools
repository Spring Data JPA
WHERE school_
Postgre
the agenda index starts with the school, so each school reads only its own part
Closing a lesson creates a charge, writes the audit log and notifies the student. Scheduling used to call finance; now it publishes an event and finance listens, so the lessons module no longer depends on the payments one.
before
scheduling lessons
exam exams
finance charges
scheduling and exam depend on finance
after
scheduling event: lesson completed
exam event: exam enrolment
finance charges
scheduling and exam import nothing from finance
The event is saved in the same transaction as the lesson, in Spring Modulith’s registry, which lives in the same PostgreSQL: no broker. If a listener fails, a job republishes the event, so delivery is at least once.
one transaction
lesson completed scheduling module
event in the registry, one row per listener
commit: both or neither
finance listener
1 already done? a charge from this event already exists: stop
2 create the charge a unique index on the source event allows only one
3 constraint violated if it’s that index, another delivery got there first: ignore it
common listener
writes the audit log
common listener
notifies the student
after the commit, each listener runs in its own transaction
scheduled job reads the registry
republishes the events a listener didn’t complete
one transaction
lesson completed scheduling module
event in the registry, one row per listener
commit: both or neither
finance listener, in its own transaction
already done? 1 a charge from this event already exists: stop
create the charge 2 a unique index on the source event allows only one
constraint violated 3 if it’s that index, another delivery got there first: ignore it
The other two listeners write the audit log and notify the student, each in its own transaction.
scheduled job Republishes the events a listener didn’t complete.
Two students can book the same slot at the same moment. Optimistic locking settles it: the slot has a version column, and the write goes through only if the version is still the one that was read.
Student A
Student B
reads the slot
books: UPDATE … WHERE version = 7
outcome
application. No overlapping times, for the instructor or for the student.
database. A partial unique index: one active booking per slot.
concurrency. A version column on the slot: whoever writes second gets 409.
No server-side retry: the slot belongs to someone else by now, and the choice goes back to the student.
The other choices, and why.
ADR 001 Accepted
ADR 002 Accepted
ADR 003 Accepted
What was wrong, and how it is now.
A payment with no allocation covers the open charges, oldest first. To know what was left on each, I asked the database for the amount already paid, one charge at a time: an N+1. Now a single query fetches all the sums before the loop, and a test counts the calls.
The refresh token rotates on every use, and a reused one is a sign of theft: I revoke all of the user’s tokens and answer 401. An integration test found that the revocation didn’t stick.
In the first version the tests ran on H2. But the schema uses PostgreSQL enum types and partial unique indexes, and those indexes are exactly what stops double bookings and double charges: now the integration tests run on a real PostgreSQL, in a container.
As long as the module boundaries were a convention, I kept to them less than I thought: the first Spring Modulith check found cycles I hadn’t seen. Events remove a dependency, but delivery becomes at-least-once, and every listener has to handle the same event more than once.