The brief: a courier and parcel-tracking API

You have learnt Spring module by module — the container, REST, JPA in depth, security, concurrency, testing, architecture, deployment. The capstone is where it stops being a list of features and becomes one real thing, built end to end: Dakiya, a courier and parcel-tracking API. Over five lessons you assemble it to a standard you could put in front of a real logistics company — every layer, secured, concurrency-safe, tested, deployed. This lesson is the brief: what Dakiya is, what it must do, and the standard it is built to.

What we are building

Dakiya is the backend a courier company runs on — a REST API (no UI; the clients are a mobile app for delivery riders, a web portal for partners, and internal staff tools). Its domain:

• Parcels — the packages: a tracking code, recipient, destination, and a status that moves through a lifecycle (booked → in transit → delivered, or cancelled).
• Hubs — sorting centres a parcel passes through.
• Riders — who carry parcels on the last leg.
• Partners — businesses that book parcels and track their own shipments.

Around that data, Dakiya exposes REST endpoints to book parcels, update their status as they move, and track them; secures those endpoints so partners see only their own parcels and only staff can change a status; handles the concurrency of many riders updating parcels at once; and is tested and deployed over HTTPS.

Why a courier API is the right capstone

A courier-tracking API exercises Spring's whole surface with real stakes:

• Rich relational data — parcels, hubs, riders, partners, status history — so the JPA layer (relationships, queries, the persistence context, performance) matters.
• A real REST API — the whole rest-apis module: DTOs, validation, error handling, status codes, pagination, versioning — because clients (a mobile app, partners) depend on the contract.
• Genuine security — partners must see only their own parcels (object-level authorisation), only staff may change status, authentication for every client — a real IDOR risk if done wrong.
• Real concurrency — many riders updating parcel statuses simultaneously is exactly the lost-update scenario the concurrency module fixed with optimistic locking.
• Reporting and performance — "parcels per hub", "in-transit count" as aggregation, and list endpoints that must not N+1.
• Production concerns — health checks a load balancer polls, secrets, HTTPS, a real database.

Every module of the course has a job in Dakiya — which is the point of a capstone: build something whole enough that the pieces must fit together.

The requirements — the standard it is built to

Not "make it work" but "build it the way the course taught". The requirements, each tracing to a module:

1. Clean layering. Controllers thin (HTTP only), business logic in services, persistence in repositories — logic in the right layer.
2. A trustworthy API contract. DTOs at the boundary (never entities), validated input, consistent ProblemDetail errors, correct status codes, paginated lists.
3. The data layer done well. Sensible entities and relationships (LAZY, correct on_delete-equivalent cascade choices), no N+1 (fetch joins where needed), queries that fetch only what is needed.
4. Proper security. Authentication for all clients; role-based authorisation (staff vs partner vs rider); and object-level access so a partner sees only their own parcels — the IDOR-safe way.
5. Concurrency safety. Parcel status updates are safe under concurrent access (optimistic locking with @Version); money/critical writes are transactional.
6. Tested. The risky paths — status transitions, authorisation, validation, concurrency — have tests (unit, slice, integration), weighted to failures.
7. Deployable. prod profile, real PostgreSQL with Flyway, secrets from the environment, health checks, HTTPS — check-clean and verified live.

The test for "done" is the course's throughout: could this be handed to a real courier company, and would it hold up under real load and real attackers?

How the five lessons go

We build in the order a careful engineer works — design first, then the core, then security and tests, then hardening and deploy:

• Design (next lesson): model the domain (parcels, hubs, riders, partners, status lifecycle) and design the API (endpoints, DTOs, the contract) before writing logic — the types and the contract are the design.
• Build: the core flows — book a parcel, update its status, track it — with thin controllers, services holding the logic, and efficient queries.
• Secure and test: authentication and layered authorisation (including partner-scoped access), and a test suite covering the risky paths.
• Harden and deploy: concurrency-safe status updates (optimistic locking), then the production checklist to a live, HTTPS, PostgreSQL deployment.

Design-first is not ceremony: in a Spring app the domain model and the API contract are the architecture, and getting them right makes the rest fall into place. That is the lesson the capstone is meant to land.

Before you start

You have been building Dakiya's pieces through the course — the Parcel entity, the controller with DTOs and validation, the security config, the repositories. If you built along, you are most of the way there; the capstone assembles the remaining domain (hubs, riders, partners, the status lifecycle) and raises the whole thing to the finished standard. If you only read, now is the time to build it for real — and run it, because the course's discipline throughout has been that code is run, not just written. The next lesson starts where every Spring project should: the domain model and the API design.

Check your work

What Dakiya is. A courier and parcel-tracking REST API: parcels (with a status lifecycle), hubs, riders, partners — book, update status, track — with security, concurrency safety, tests, and a real deployment. No UI; clients are a mobile app, a partner portal, staff tools.

Why a courier API. It exercises Spring's whole surface with real stakes — rich relational data, a real REST contract, genuine security (object-level, IDOR risk), real concurrency (status updates), reporting/ performance, and production concerns.

The seven requirements. Clean layering; trustworthy API contract (DTOs, validation, errors, pagination); data layer done well (relationships, no N+1); proper security (auth + roles + object-level); concurrency safety (@Version, transactions); tested risky paths; deployable (prod, Postgres+Flyway, secrets, HTTPS). Each traces to a module.

Build order. Design → build → secure & test → harden & deploy.

Practice

1. List Dakiya's core entities and, for each, one sentence on what it holds and which module its handling comes from.
2. For each of the seven requirements, name the course module it comes from — a map of what the capstone exercises.
3. Sketch the entities and relationships (parcel-hub-rider-partner, status lifecycle) on paper before the design lesson; you will compare.
4. Decide which Dakiya endpoints are for which client (rider app, partner portal, staff) and what access each needs.
5. Name one concrete place in Dakiya where each of these could go wrong: an N+1, an IDOR, and a lost update.
6. If you built along, list what you already have versus what the capstone still needs to assemble.

Official documentation

• Spring — Building a RESTful Web Service (guide) — Assembling a REST API end to end.
• Spring Boot — Reference documentation — The reference for every piece Dakiya uses.
• Spring — Guides — Short official guides for each capability.

Next: designing the domain and the API.