Across ten modules we have built Ribalta's electric bike network layer by layer. First an endpoint that returned four in-memory stations; then Spring's container and its beans; the REST contract with its DTOs and its errors; persistence on PostgreSQL with Flyway; security with JWT and per-datum rules; the tests; operability; deployment; and finally observability, judgement and cleanliness. Every lesson added a piece and almost always looked towards the next one.

We have never looked at CicloUrbana whole. This lesson does: the complete architecture in one diagram, the real repository structure, the journey of a single request from the load balancer to the metric — citing at every step where it was studied —, the map of what each module built, the design decisions with their alternatives and trade-offs, the final pom.xml and configuration, how to get the project running from scratch and where to take it next. If you have followed the course, you will recognise everything here; what is new is seeing it all together.

1. The final architecture
2. The complete repository
3. The journey of a request: POST /api/v1/rentals
4. Course map: what each module built
5. Design decisions and their alternatives
6. The final pom.xml
7. The final configuration
8. Getting the project running from scratch
9. An end-to-end walkthrough with .http requests
10. Final go-live checklist
11. Where to take this project next
12. Common Mistakes and Tips
13. Exercises

Four observations about the drawing, because a diagram without a reading is decoration.

The application is a single deployable. The five blocks inside are not services: they are layers and modules within the same process. It is the modular monolith from 07-05, and the arrows between them are method calls, not network calls.

The dependencies point inwards and downwards. Filters → controllers → services → repositories → database. No arrow goes up. It is the dependency rule from 10-01, verified automatically with the ArchUnit rules from 10-03.

Observability is a sidecar, not a layer. It is not on the request path: the application publishes metrics, logs and traces, and others collect them. If Prometheus goes down, CicloUrbana keeps working.

The only thing that can take the service down is PostgreSQL. The Redis cache degrades to Caffeine, the gateway has a circuit breaker and a deferred-charge fallback, and the rest is optional. That asymmetry is deliberate and is why the readiness probe does query the database and the liveness one does not.

Two things deserve attention. src/test is an exact mirror of src/main, which lets you reach package-private members without opening up the production class and keeps the tree navigable. And the *Test / *IT split is not cosmetic: Surefire runs the former in ./mvnw test in seconds, and Failsafe runs the latter in ./mvnw verify against a real PostgreSQL.

Marta opens the app at the "Main Square" station, picks a bike and taps "rent". This is what happens.

The step-by-step detail, with its lesson:

What you see when you put it together. Steps 9 and 10 are done by the same proxy, which is why the self-invocation trap takes down the transaction and the permission check at the same time. Step 14 is not a stylistic detail: with open-in-view: false it is the only way for the response to be built without a LazyInitializationException. And steps 16 to 18 are the reason Marta gets her 201 in tens of milliseconds while the charge takes almost two seconds on another thread.

Every architecture decision buys something and pays something. These are CicloUrbana's six main ones, with what they cost.

And two minor decisions that illustrate the same way of thinking. open-in-view: false buys you that no query is fired during serialisation, and pays with the obligation to map to a DTO inside the transaction — which, incidentally, reinforces a practice we wanted anyway. Deny by default buys you that an oversight produces a visible 403 instead of an open endpoint, and pays with every new route requiring an explicit rule.

None of these six is universally correct. What makes them defensible is that they were taken with the trade-off in plain sight and were written down.

The accumulated dependencies, grouped by the module that introduced them. The version column is the important information: only the ones the Spring Boot BOM does not manage carry their own version, and they are exactly the ones you have to review by hand on every upgrade.

And the part of the pom.xml that really deserves careful reading, because it is the part that breaks the build on a concrete problem:

The six plugins are not ornaments: each one breaks the build on a concrete problem — an unmapped field, a failed integration test, unformatted code, a high-severity vulnerability. It is the underlying idea of 10-01: moving the check out of a person's head and into the build.

And the per-environment differences, which are the only thing that changes:

Step 3 deserves a comment: ./mvnw verify starts an ephemeral PostgreSQL with Testcontainers and applies the nine migrations to it before running the *IT classes. If that command passes on your machine, the project is healthy from top to bottom.

And the three checks that close the walkthrough, which are the ones that prove the module 9 observability really works:

If all three return data, the three signals are connected: the metric detects, the trace locates and the log explains.

Point 13 did not appear in any lesson and is one of the most expensive to get wrong: a backup that has never been restored is not a backup, it is a hope. And point 15 repeats the warning from module 5: everything built in this course is a teaching starting point and needs professional review before being exposed to the internet.

CicloUrbana is finished as course material, not as a product. These seven extensions are ordered by difficulty and each one combines lessons you already know.

About number 7, which is the one most people want to do first: it is last on the list for a reason. Splitting the system into two processes turns a local transaction into a saga with compensations, a stack trace into an investigation across two deployments, and a method call into a network call that can fail. Do it only when you have distributed tracing working and a concrete reason — independent scaling or an independent team — not as a stylistic exercise.

And a recommendation about method: for any of the seven, start by writing the test for the behaviour you want, then the migration if it touches the schema, and leave the controller for last. It is the order that throws the least code away.

Believing the diagram is the architecture. The diagram in section 1 is a view; the real architecture is what the code's dependencies do. That is why the ArchUnit rules exist: they are the only diagram that cannot lie.

Copying the whole pom.xml into a new project. It brings Redis, ShedLock, Resilience4j and Testcontainers into a project that may not need them, and every dependency is maintenance and vulnerability surface. Start with web, data-jpa and test, and add when something hurts.

Always bringing up the entire observability stack locally. Prometheus, Grafana, Loki, Tempo and the Collector consume memory and startup time. Day to day, the application and PostgreSQL are enough; the full stack goes up when you are working on observability.

Forgetting that the .env is not in the repository. It is the first thing that breaks for whoever clones the project for the first time. A versioned .env.example with the keys and without the values saves each new person that half hour.

Tip: walk through section 3 with a debugger. Putting a breakpoint in RentalService.start and climbing the call stack up to the filter is the exercise that consolidates the whole course best: you see, on a single screen, the proxy, the transaction, the SecurityContext and the MDC.

Tip: keep the decision log. The table in section 5 — decision, alternative, reason, trade-off — is the document you will be most grateful for a year from now, and the only one that answers "why is it built like this?".

Tip: measure before extending. Any of the seven extensions in section 11 changes the load profile. Save today's k6 baseline: it will be the reference for knowing whether the extension cost anything.

In production, at 09:12, the mobile app starts receiving 500s on POST /api/v1/rentals. The error body is a ProblemDetail with "code": "INTERNAL_ERROR" and a traceId. Describe, step by step and with the project's concrete tools, how you would investigate the incident from that traceId to the root cause, stating which piece of which module you would use at each step and what you would rule out with each one.

Design extension number 4 from section 11: a citizen can book a specific bike for 10 minutes before picking it up; once that time has passed, the booking expires and the bike becomes available again. Specify the model change, the migration, the API contract, the concurrency control, the expiry task, the security rules, the metrics and the tests you would write.

A neighbouring city's council wants to reuse CicloUrbana. Their numbers: 40 stations (against 4), 300,000 rentals a month, two development teams and a new requirement — real-time integration with the public transport system. Analyse which decisions from section 5 would still be correct, which would need revisiting and in what order you would tackle the adaptation.

Solution 1

Step 1 — from the alert to the dashboard (09-04). Before touching the traceId, look at the RED row on the dashboard: is it a spike of errors or a trickle? Did it start with the 09:05 deployment? This distinguishes a systematic failure from a one-off, and decides whether to roll back right away.

Step 2 — the log for that exact request (09-05). In Loki: {app="ciclourbana", environment="prod"} | json | traceId = "...". It returns the complete story of the request, including the stack trace that was not sent to the client. Most incidents are closed right here, with the exception's name and the line.

Step 3 — the span cascade (09-06). In Tempo, the same trace. Here you get an answer the log does not give: where the time went and what failed. A red bar on the gateway span rules out the problem being ours; twenty identical select spans give away a new N+1; a 900 ms uninstrumented gap points at connection waiting or a GC pause.

Step 4 — ruling out resources (09-03). hikaricp.connections.pending, jvm.gc.pause and resilience4j.circuitbreaker.state at the instant of the failure. If pending is at 60, the problem is not the logic: something is holding connections — an HTTP call inside a transaction is suspect number one.

Step 5 — reproduce (06-05). With the cause identified, write the test that reproduces it before fixing anything. If the failure depends on real data, an *IT with Testcontainers and the exact state that triggers it.

Step 6 — decide (08-05). If the failure arrived with the 09:05 deployment, roll back first and diagnose afterwards: time to restore is a DORA metric and rolling back is a command. If it is an external problem, the decision is a business one — degrade, open the circuit breaker, wait — as in the case study in 09-06.

What the exercise teaches: the route goes from the general to the particular and from the cheap to the expensive. The metric costs a glance, the trace a click, the log a query, and the debugger half a morning. Starting with the debugger is the most common mistake.

Solution 2

Model. BikeStatus gains the value RESERVED. A Reservation(id, user, bike, station, createdAt, expiresAt, status) entity appears, with ReservationStatus { ACTIVE, USED, EXPIRED, CANCELLED }. The booking is an aggregate of its own and not a field on Bike, because it has a lifecycle, a history and rules of its own.

Migration V10__reservations.sql. A table with a sequence (allocationSize = 50, never IDENTITY, because of the batching from 09-01), foreign keys to users, bikes and stations, audit columns, a CHECK on the status, an index (expires_at) WHERE status = 'ACTIVE' — partial, a few dozen rows against millions — and a partial unique index that prevents two active bookings for the same user, the same technique as uk_rentals_user_in_progress. The enum of the status column on bikes widens its CHECK: a backward-compatible change.

Contract. POST /api/v1/reservations with { "bikeId": 12 } returns 201 with Location and ReservationResponse(id, plate, station, expiresAt, secondsRemaining). DELETE /api/v1/reservations/{id} cancels (204). And POST /api/v1/rentals optionally accepts a reservationId: if it is present, it consumes the booking instead of looking for a bike.

Concurrency. This is the delicate point. SELECT … FOR UPDATE on the bike with a 3 s timeout, a check that it is still AVAILABLE, and a change to RESERVED in the same transaction. Without the lock, two citizens book the same bike and one gets an unnecessary 409 when the system could have offered them another.

Expiry. ReservationExpirer, sibling of RentalExpirer: @Scheduled(fixedDelayString = "${ciclourbana.reservations.expirer.interval:PT30S}") with @SchedulerLock — three replicas, one execution —, the logic in a public, invocable method so it can be tested, an injected Clock and idempotency: marking an already-expired booking as expired changes nothing.

Security. @PreAuthorize("isAuthenticated()") to create; @PreAuthorize("hasAnyRole('OPERATOR','ADMIN') or @reservationSecurity.isOwner(#reservationId, principal)") to cancel and to query, with a new bean identical in shape to RentalSecurity. The listing filters in the query, never with @PostFilter.

Metrics. A Counter ciclourbana.reservations.created{station} and another ciclourbana.reservations.expired, with the station tag — four values — and never the user identifier. The expiry rate is the interesting business indicator: if it is high, the 10-minute window is either too short or too long.

Tests. A unit test of Reservation.expire() with Clock.fixed and of the exactly-ten-minutes edge case; a @DataJpaTest of the partial unique index — two active bookings for the same user must violate the constraint —; a security slice with two citizens crossing identifiers; and an *IT of the full book → rent → finish flow, plus another of book → wait → check it expired, with the clock under control.

The design decision you have to be able to defend: the booking is an aggregate of its own. Modelling it as two fields on Bike looks cheaper and makes the history impossible, complicates expiry and puts transient state into an entity that ought to be stable.

Solution 3

What remains correct without discussion. Flyway, DTOs, deny by default, @Transactional in the service, Testcontainers, structured logs and observability: these are decisions whose benefit grows with size rather than shrinking. MapStruct goes from optional to clearly worthwhile, because the number of DTOs multiplies.

What needs revisiting, with the reason.

The order of the adaptation, which is what the exercise is really asking:

1. Measure with the new data before touching anything. Load 40 stations and 300,000 rentals into pre and run the k6 scenario. Almost every one of the decisions above is settled by data, not opinions.
2. Indexes and queries. What degrades with volume degrades first, and it is the cheapest thing to fix.
3. Module boundaries before teams. With two teams, the conflict is not technical but one of code ownership: ArchUnit rules per module and explicit boundaries before dividing the work.
4. A distributed cache and a resized pool, with the load test as the judge.
5. The public transport integration last, because it introduces a new technology — messaging — and it is better done on a base that is already stable and measured.

What I would not do: split into microservices from the outset "because it is bigger now". Forty stations and seven rentals a minute are not a scale problem: they are an organisational problem, and that is solved with internal boundaries before separate processes.

CicloUrbana is complete and, for the first time, you have seen it whole. You have the final architecture in a diagram that can be read: a single deployable with internal modules, dependencies that always point inwards, observability as a sidecar rather than a layer, and a single dependency capable of taking the service down — PostgreSQL — which explains why the readiness probe queries it and the liveness one does not. You have the real repository structure, with packages by feature, the test tree as a mirror of the production one, the *Test/*IT split and everything that surrounds the code: Dockerfile, docker-compose, helm/, .github/workflows, observability/ and load/.

And you have the journey of a request told in twenty-one steps, from the load balancer to the metric, with the lesson behind each one. That walkthrough is the best summary of the course because everything appears in it: the filter that opens the span, the JWT that gets validated, the binding and validation of the DTO, the proxy that evaluates the permission and opens the transaction at the same point — hence self-invocation taking both down at once —, the pessimistic lock on the last bike at "Main Square", the mapping inside the transaction that makes open-in-view: false possible, the AFTER_COMMIT that moves the charge off the HTTP thread and the business metric that closes the cycle.

You also have the map of what each module built, the final pom.xml where you can see which versions the BOM manages and which have to be reviewed by hand, the consolidated configuration with the table of the only things that change between environments, the commands to get the project running from scratch and the .http collection that walks through registration, login, browsing, renting, invoicing and the check that one citizen cannot read another's rental — followed by the three queries that prove the metric, the log and the trace are joined by the same traceId.

And you have the two pieces that separate a course project from a product: the table of decisions with their trade-offs, the document that answers "why is it built like this?" a year from now, and the final checklist with its fifteen points, including the one no lesson had mentioned — a backup that has never been restored is not a backup — and the one repeated since module 5: this is a teaching starting point and it needs professional review before being exposed to the internet.

The project does not end here, and that is the idea. The seven extensions in section 11 are ordered by difficulty and each one tells you which lessons to combine, from the report with CSV export to extracting billing into its own service — last on the list, and with good reason. Building any of them on this foundation is the best way to make what you have learnt your own.

There is one lesson left, and it is the only one in the course that is not about CicloUrbana. Because knowing Spring Boot is not having finished a course: it is having begun to be able to read the documentation with judgement, tell an up-to-date resource from a confusing one, plan a major version upgrade without fear and choose what to learn next among twenty possible paths. Resources for Further Learning deals with that: the official documentation and how to read it, the source code as the best source, how to keep up with Spring's release cycle, the Java ecosystem, the books that are genuinely worth it, certifications with an honest assessment, the community, deliberate practice, the natural topics for the next step and a reasoned roadmap for the next six months.