It’s time to move from the foundations of Java and Object-Oriented Programming into real-world backend development.

In this course, you won’t just learn Spring Boot features or annotations. You will build a production-style backend application from the ground up, step by step, and learn professional backend development through the process.

The course follows the workflow of a real engineering team—from understanding requirements and creating technical designs, RFCs, and engineering tickets to implementation, testing, code review, deployment, and investigating production issues.

Throughout the course, the same application will continue to evolve. Instead of learning each new concept through isolated examples, you will see where it fits in a real system, why it is needed, and how it is applied in practice.

The goal of this course is not simply to complete a backend project.

The goal is to build the foundation you need as a backend engineer to think about, design, build, and maintain production-quality software.

Before any code exists, this module does the work a new backend engineer does in the first weeks on a team. You read the Product Manager's brief for the Order Management Backend and separate what it says from what you are tempted to assume, sort its requirements into functional behaviour and non-functional qualities, and turn the capabilities into User Stories with testable Acceptance Criteria. Then you learn the engineering context the system must fit, agree a Definition of Done, and break the work into the `BACKEND-101` to `BACKEND-128` backlog that the rest of the course implements, ordered by dependency, value and risk. The exercises produce the team's real working documents in your own `docs/` folder: a requirement review, Stories, a context document, a DoD review and a backlog plan.

The team, the project, the role of a backend engineer, and why behaviour comes before code.

In this course, we are not going to learn Java or Spring Boot features through a collection of isolated examples. Instead, we will build a real-world backend application and evolve that same application throughout the course.

You are not just a learner here. From this moment on, imagine that you have joined a software engineering team as a new **Backend Engineer**. Your team is about to build a new **Order Management Backend**.

The system will allow customers to browse products, place orders, make payments, view their order history and cancel eligible orders. Administrative users will be able to create and update products, deactivate products, manage inventory and view orders.

But we are not going to start by writing code. Professional software development usually does not begin with "new project, open the IDE, start coding". A more realistic process looks like this:

```mermaid
flowchart LR
    A["Business Problem"] --> B["Requirements"] --> C["Technical Discussion"] --> D["Design"] --> E["Engineering Tasks"]
    E --> F["Implementation"] --> G["Testing"] --> H["Review"] --> I["Deployment"] --> J["Operation"]
```

The purpose of this course is to let you experience that entire process in practice.

## The Project We Are Joining

Imagine that we work for a commerce company. The company already sells products, but now it wants a dedicated backend system for its ordering process, and our team's responsibility is to build that backend.

The initial version will support several core capabilities:

* product management
* inventory management
* order creation
* payment processing
* order history
* order cancellation
* administrative operations

Customer identity will come from the application's authentication mechanism. We are **not** building a separate customer-account management subsystem as part of this project.

As the course progresses, we will implement these capabilities gradually. Keep one important idea in mind:

> **We are not going to build the entire system at once.**

Professional software is usually delivered through small, reviewable, incremental changes. Our project will evolve the same way.

## Your Role

In this project, you are a **Backend Engineer**. That means your job is not limited to writing APIs. A backend engineer may need to:

* understand product requirements
* identify ambiguous requirements and ask clarifying questions
* design technical solutions
* define API contracts
* design database models
* implement business logic
* write tests
* review another engineer's code
* explain technical changes
* investigate production failures
* modify an existing system safely
* document technical decisions

Throughout the course, we will practise different parts of these responsibilities.

## Software Development Is More Than Writing Code

When learning programming, we often work with a simplified model: a problem goes in, we write code, and the code produces output. That model is useful for small programming exercises. Production software is different: there are many important decisions between the problem and the code.

Suppose a Product Manager says:

> A customer should be able to place an order.

That sounds simple. But as backend engineers, we should immediately start asking questions:

* Can an order contain multiple products? Can the same product appear more than once?
* What happens if inventory is insufficient? When should inventory decrease?
* Can a customer cancel an order? Can an unpaid order be cancelled? Can a paid one?
* What happens if payment succeeds but our database update fails?
* How do we calculate the final price? Should it come from the current product price, and what happens if that price changes later?

This is one of the major differences between software engineering and simply writing code. Writing the code is often the most straightforward part. The difficult part is:

> **Understanding exactly which problem needs to be solved and how the system should behave.**

## We Will Not Start With Spring Boot

This is a Java backend development course. Even so, the first few lessons will contain very little Spring Boot code, and that is intentional.

A framework is a tool. Spring Boot gives us capabilities such as HTTP controllers, dependency injection, configuration, database integration, validation and application lifecycle management. But Spring Boot cannot decide whether:

* the requirement has been understood correctly
* a responsibility belongs in the right component
* an API contract is well designed
* a business invariant has been identified
* a transaction is required
* a failure scenario has been handled correctly
* a change is risky
* a production incident has been investigated properly

Learning the framework is important, but knowing a framework and being a backend engineer are not the same thing. Throughout this course, we will develop both: backend engineering thinking and its implementation in Java and Spring Boot.

## Our Engineering Workflow

Throughout the course, we will follow a repeatable engineering workflow. A feature will usually move through a process similar to this:

```mermaid
flowchart TD
    A["Requirement"] --> B["Understand and clarify the problem"]
    B --> C["Technical design"]
    C --> D["RFC / ADR when needed"]
    D --> E["Break work into tickets"]
    E --> F["Implementation and testing"]
    F --> G["Pull request and code review"]
    G --> H["Merge"]
    H --> I["Deploy"]
    I --> J["Observe"]
```

Not every small change needs a full RFC. That is also an important engineering lesson: documentation should not exist to create bureaucracy. Its purpose is to improve thinking and communication where those things are valuable. Later, we will learn when a short engineering ticket is enough, when an ADR is appropriate and when a larger RFC is worth writing.

## RFCs and ADRs

You will see the term **RFC** throughout this course. RFC commonly stands for **Request for Comments**. In a software engineering team, an RFC can be a document in which an engineer explains a technical problem and proposes a solution so that other engineers can review it before implementation. An RFC might contain sections such as Problem, Context, Goals, Non-Goals, Proposed Design, Alternatives, Risks and Rollout Plan.

Not every company uses the same format. Some teams call these documents design documents, technical proposals or engineering proposals. The name is less important than the purpose:

> **Think about and discuss important technical decisions in a structured way before hiding those decisions inside code.**

We will write RFCs for our Order Management Backend when the problem justifies one.

Another term we will use is **ADR — Architecture Decision Record**. An ADR records a specific technical decision and the reasoning behind it, for example why we are using PostgreSQL, why we are using database migrations or why we chose a particular API error format.

An RFC may describe a larger technical proposal; an ADR usually focuses on preserving one important decision and its reasoning. Months later, when another engineer joins the project, they should not have to reverse-engineer the reason behind every architectural choice by reading code. They should be able to read the relevant ADR and understand the context.

## Engineering Tickets

After designing a solution, we will break the work into smaller engineering tasks:

```text
BACKEND-101 Bootstrap Order Management Backend
BACKEND-102 Configure PostgreSQL and Flyway
BACKEND-103 Model the Product Domain
BACKEND-104 Persist Products
BACKEND-105 Implement Product Administration
```

A useful ticket should not simply say "Build orders" or "Implement ordering system": with a scope that large, an engineer may not even know where to start. A well-written ticket creates a useful boundary around engineering work. Compare it with:

```markdown
BACKEND-112 Implement Order Creation Workflow

Create an order for an authenticated customer.

Acceptance Criteria:

- Order must contain at least one item.
- Every referenced product must exist.
- Requested quantity must be available.
- Order total must be calculated from server-side product prices.
- Invalid requests must return an appropriate API error.
```

The problem is now much clearer. Smaller engineering work is easier to review, test, roll back and parallelize, and it keeps risk small.

## Pull Requests Are Communication

Writing the code does not mean the work is finished. In a professional engineering team, a change usually goes through review: we create a **Pull Request**, commonly called a **PR**. A useful PR description might look like this:

```markdown
## What

Adds order cancellation support.

## Why

Customers need to cancel unpaid orders.

## Changes

- Added cancellation domain logic
- Restores consumed inventory
- Added cancellation API
- Added integration tests

## Testing

- Unit tests
- API integration tests

## Risks

Inventory restoration happens inside the order transaction.
```

A PR is not just a container for code. It is communication with the reviewer, who should be able to understand quickly what changed, why it changed, how it was tested and where the risks are. This is an extremely important skill in a real engineering career.

## Production Changes Everything

Running an application successfully on a local machine is not the end of software development. Production systems introduce additional questions:

* How will we know if the service is healthy?
* What happens when the database is unavailable, or when an external payment API times out?
* How do we find a failed request?
* What happens during deployment? Can a database migration break existing application instances?
* Can the same payment request be processed twice?
* What happens if two customers try to buy the final item simultaneously?

Questions like these are what make backend engineering interesting. We do not need to know every answer at the beginning of the course. In fact, we should not try to solve every possible future problem immediately. As the system evolves, new problems will naturally appear, and then we will learn and apply the appropriate solution.

## We Will Make Mistakes

We will not begin the course with a perfectly designed system, and real software rarely begins with perfect architecture either. We will make decisions. Later, new requirements will arrive, some assumptions may turn out to be wrong and some designs may need to change. We will even simulate a production incident.

That is not a failure of the course. That is software development: real systems evolve over time. A strong engineer's skill is not simply the ability to write the correct code on the first attempt. It is also:

> **The ability to change an existing system safely.**

## Our First Version Will Be a Modular Application

Our Order Management Backend will begin as a single backend application. Conceptually:

```text
Order Management Backend
├── Products
├── Inventory
├── Orders
└── Payments
```

Customer identity is supplied by the authentication system and used by application workflows, but we are not creating a separate Customer management capability.

We will not split it into microservices or add infrastructure such as Kafka or distributed caches before a real problem requires them; module 2 makes that decision explicitly. A system that satisfies its requirements with a simpler architecture is usually a better starting point.

## What We Will Build Toward

By the end of the course, our application will be much more than a collection of CRUD endpoints. We will build a backend with HTTP APIs, business logic, domain models, validation, PostgreSQL persistence, database migrations, transactions, authentication and authorization, external service integration, tests, logging, metrics, health checks, Docker, CI and deployment practices.

But we will not learn these as an arbitrary checklist. Each capability will appear because the project creates a reason for it:

* We will learn **PostgreSQL** because the application needs durable data.
* We will learn **transactions** because Order creation changes multiple pieces of database state that must remain atomic.
* We will learn **authentication and authorization** because one Customer must not be able to access another Customer's Orders.
* We will learn **timeouts and retries** because an external payment provider will not always respond perfectly.
* We will learn **observability** because when something fails in production, engineers need to understand what happened inside the system.

This distinction is important:

> **Problem first. Technology second.**

## Your Engineering Repository

As the course progresses, our repository may evolve into something like:

```text
order-management/
├── src/
│   ├── main/
│   └── test/
├── docs/
│   ├── rfcs/
│   ├── adr/
│   └── incidents/
├── Dockerfile
├── compose.yaml
└── README.md
```

`src/` contains application code, `docs/rfcs/` larger technical proposals, `docs/adr/` architecture decisions, and `docs/incidents/` will later contain production incident reviews. Engineering context becomes part of the repository alongside the code.

## A Backend Engineer Thinks in Behaviour

The questions we asked about "place an order" point to one habit we will practise throughout the course: when a feature request arrives, think about behaviour before implementation. "Customer can cancel an order" is not `order.setStatus(OrderStatus.CANCELLED);`. It raises questions first: which orders can be cancelled, whether inventory is restored, whether the same order can be cancelled twice, who may cancel it and what the API returns. Behaviour first, then design, then code.

## Think Like You Just Joined the Team

At this point, all we know is the high-level context: the company wants an Order Management Backend. An inexperienced developer might already open an IDE and create an `OrderController`. We are not going to do that. Our next responsibility is to understand the business requirement: who will use the system, what they should be able to do, which behaviours are mandatory or out of scope, which constraints exist and how success will be defined. Without that information, we might write code quickly and still build the wrong system.

## Practice Exercise 1: Questions Before Code

_Solutions: lesson 1.09._

Module 1 produces documents, not code, so start a workspace for them now: a folder of your own, for example `backend-course/`, with a `docs/` folder inside. The `order-management` repository itself starts in module 3.

The Product Manager adds one sentence: "Administrators should be able to deactivate a product." Create `docs/questions-deactivate-product.md` and write at least six questions you would want answered before anyone writes `product.deactivate()`. Cover who may do it, what happens to Customers browsing and ordering, what happens to existing Orders, whether it can be undone, and what happens if it is done twice. Do not answer them; this lesson is about noticing them.

## Practice Exercise 2: Which Document?

For each piece of information, choose where it belongs: a ticket, a Pull Request description, an RFC in `docs/rfcs/`, an ADR in `docs/adr/` or an incident review in `docs/incidents/`. Give one reason for each.

1. Why the team chose PostgreSQL over other databases.
2. A proposal for how the backend will call the Payment provider, with alternatives, risks and a rollout plan, for the team to review before anyone implements it.
3. "Reject Order items with a quantity below 1."
4. What this change does, how it was tested and what a reviewer should look at closely.
5. What happened last Tuesday when Payments failed for 40 minutes, and what the team will change.

## Practice Exercise 3: Review a Pull Request Description

A teammate opens a Pull Request with this description. Find what a reviewer cannot learn from it, using the What / Why / Changes / Testing / Risks shape from this lesson.

```markdown
## What

Cancellation.

## Changes

- Updated some files
- Fixed stuff in Inventory

## Testing

Works on my machine.
```

## Knowledge Check

### Question 1

Why does this course spend its first lessons on requirements instead of Spring Boot code?

### Question 2

"Build orders" names something everyone on the team understands. Why is it still a poor ticket?

### Question 3

Both an RFC and an ADR record technical thinking. What does each one keep, and what does a new engineer lose months later if neither exists?

### Question 4

Why does a useful Pull Request description have a Risks section, even when the change is small?

### Question 5

A teammate suggests starting with microservices and Kafka "because we will need them eventually". What does "problem first, technology second" answer?

## Knowledge Check Answers

### Answer 1

Spring Boot can implement a behaviour, but it cannot tell us which behaviour is correct. If the requirement is misunderstood, well-written code still builds the wrong system, so understanding comes first.

### Answer 2

Its scope is so large that an engineer does not know where to start, a reviewer cannot judge it and nobody can tell when it is finished. A good ticket puts a boundary around one reviewable, testable piece of work.

### Answer 3

An RFC proposes a larger design for review before implementation; an ADR preserves one decision and why it was made. Without them, a new engineer has to reverse-engineer the reasons from code, and may undo a decision whose reason is invisible.

### Answer 4

The reviewer's attention is limited, and the author knows best where the change could go wrong, for example that Inventory restoration runs inside the Order transaction. Naming the risk points the review at it; "no special risk" is also useful information.

### Answer 5

Technology should appear because the project creates a reason for it. No current requirement needs separate services or a message broker, and a simpler architecture that satisfies the requirements is a better start; module 2 makes that decision explicitly.

## Engineering Principle

> **The job is not to write code. The job is to solve the right problem with software.**

Code is an important part of that job. But before code comes understanding, and after production comes ownership. A backend engineer participates in the entire lifecycle.

## Summary

* We join a team building the **Order Management Backend** and evolve that one application through the whole course.
* A backend engineer's work goes from understanding requirements and asking questions through design, implementation, testing and review to operating the system in production.
* Spring Boot is a tool; it cannot decide whether we understood the requirement or designed the behaviour correctly.
* RFCs propose larger technical changes for review; ADRs preserve one decision and its reasoning; tickets give work a clear, reviewable boundary.
* A pull request is communication: what changed, why, how it was tested and where the risks are.
* We start with a simple modular application and add technology only when a real problem requires it: problem first, technology second.
* Behaviour comes before design, and design before code.

In the next lesson, our team receives the actual product requirement for the Order Management Backend. It intentionally begins at a high level, and we will read it like engineers: separating what is explicitly required from what we are assuming, what is ambiguous, what needs clarification and what should not be built yet.


Welcome to the Engineering Team

Reading the Product brief literally, finding its open questions and routing them to the right people.

Understanding the Product Requirement

What the system does versus how well it must do it, without inventing targets.

Functional vs Non-Functional Requirements

Stories for the v1 capabilities and the agreed, testable criteria for Create Order and the rest.

User Stories and Acceptance Criteria

The platform, ownership boundaries and dependencies the backend must fit into.

Understanding the Existing Engineering Context

The team's shared quality bar, and how it differs from Acceptance Criteria.

Definition of Done

Turning Stories into coherent, outcome-oriented tickets from `BACKEND-101` to `BACKEND-128`.

Creating Our Initial Engineering Backlog

Readiness, dependencies, vertical slices, refinement and traceability.

Prioritizing and Refining the Backlog

Solutions to the practice exercises of lessons 1.01 to 1.04.

Module 1 Practice Solutions: Lessons 1.01–1.04

Solutions to the practice exercises of lessons 1.05 to 1.08.

Module 1 Practice Solutions: Lessons 1.05–1.08

Joining the Backend Team

Before the first line of code, the team turns the agreed requirements into a design it can review. This module finds the domain concepts and decides which have identity: Product, a separate Inventory, Order with its OrderItems and purchase-time prices, and a `CustomerId` from the identity capability instead of a local Customer. It assigns each responsibility to handlers, use cases, domain objects, repositories or the `PaymentService` boundary, and shapes them into a modular monolith with one package per capability. The design is then written down as RFC-001, its durable decisions are recorded as ADR-001 to ADR-005, and a review sharpens vague requirements, rejects speculative infrastructure and decides what is ready to build. Every exercise produces a design document that you keep in your project's `docs/` folder.

The questions a technical design answers, from use cases and invariants to transactions, failures and risks.

From Requirements to Technical Design

Which concepts are entities, which are values, what each owns, and why Order is the aggregate root.

Identifying Domain Entities

What handlers, use cases, domain objects, repositories and external services each own.

Defining System Responsibilities

The modular monolith, capability packages, dependency direction and the non-goals.

Designing the Initial Architecture

RFC-001, the reviewable proposal for the whole initial architecture.

Writing Our First RFC

ADR-001 to ADR-005, and which decisions deserve a record.

Architecture Decision Records

Reviewing RFC-001, revising it, rejecting speculative suggestions and accepting it.

Reviewing and Revising a Technical Design

Solutions to the practice exercises of lessons 2.01 to 2.07.

Module 2 Practice Solutions: Lessons 2.01–2.07

Designing the System

The design is approved; this module starts the code. You create the `order-management` repository with Spring Initializr and complete the first ticket, `BACKEND-101`: a Gradle build that works from a clean checkout, a Spring Boot entry point and a context test. Then the module explains what the framework does with it: how project structure decides what Spring finds, how Dependency Injection and the Application Context build the object graph, and why startup fails when a Bean is missing, ambiguous or part of a cycle. It sets the rules for configuration, profiles and secrets, the package convention every later ticket follows, and the local workflow with PostgreSQL in Docker Compose. At the end, the project builds, its test passes without a database, and it starts with the `local` profile.

Generating the project for `BACKEND-101`, with only the dependencies the ticket needs.

Creating a Spring Boot Application

What belongs where in the repository, and how the main class's package decides component scanning.

Understanding Spring Boot Project Structure

Receiving collaborators through constructors instead of constructing them.

Dependency Injection

What Spring manages, how it builds the dependency graph, and why broken wiring stops startup.

Beans and the Application Context

Runtime values in typed configuration, entering at infrastructure boundaries, with secrets kept out.

Configuration and Application Properties

One artifact for every environment, the `local` profile and the precedence of configuration sources.

Environment-Specific Configuration

Capability-first packages, the place of each responsibility and the direction of dependencies.

Structuring a Backend Codebase

The application on the host, PostgreSQL in Docker Compose, and debugging startup.

Running the Application Locally

Solutions to the practice exercises of lessons 3.01 to 3.04.

Module 3 Practice Solutions: Lessons 3.01–3.04

Solutions to the practice exercises of lessons 3.05 to 3.08.

Module 3 Practice Solutions: Lessons 3.05–3.08

Building the Spring Boot Application

The application starts, but it holds no business code yet; this module writes its core. Product, Inventory, Order, OrderItem and the typed IDs become plain Java classes that protect their own rules: a price is never negative, stock never drops below zero, an Order has at least one line, keeps its purchase-time prices, derives its total with exact arithmetic and moves only from `UNPAID` to `PAID` or `CANCELLED`. Along the way the module separates entities, value objects and DTOs, keeps HTTP, security and persistence out of the domain, decides what Customer means when another system owns identity, and finds the line between a passive data holder and an object that does too much. Every rule is tested with plain JUnit, without Spring or a database.

From business language to Java objects that own their state, rules and behaviour.

Turning Business Concepts into Domain Models

Identity, value and boundary data, and why a record or a database key does not decide which is which.

Entities, Value Objects, and DTOs

Which rules belong to the handler, the use case, the domain and the database.

Separating Domain Logic from Transport Logic

Product as an entity with a protected price, idempotent deactivation and a first use case.

Modeling Product

Customer identity as a `CustomerId` value object, without a local Customer aggregate.

Modeling Customer

Order composition, purchase-time prices and derived totals that cannot overflow silently.

Modeling Orders and Order Items

The `UNPAID`, `PAID` and `CANCELLED` lifecycle, its transitions and exhaustive tests.

Modeling Order State

Keeping rules with the state they protect without turning entities into workflows.

Avoiding Anemic Domain Models

Solutions to the practice exercises of lessons 4.01 to 4.04.

Module 4 Practice Solutions: Lessons 4.01–4.04

Solutions to the practice exercises of lessons 4.05 to 4.08.

Module 4 Practice Solutions: Lessons 4.05–4.08

Domain Modeling

The domain model exists; this module gives it an HTTP boundary that clients can rely on. It treats HTTP as a behavioural contract, designs the v1 resources for Products, Inventory and Orders from what Customers and Admins actually do, and implements the first handler in Spring MVC. Along the way it settles the decisions every endpoint shares: request and response DTOs that keep prices, ownership and status server-controlled, a small status vocabulary, validation at the boundary, one RFC 9457 error format with stable codes, bounded pagination, a versioning policy and an OpenAPI document generated with springdoc. Most routes wait for their use cases in module 7, but Product creation already works, and the module ends with a checkpoint where you start the application and call it with `curl`.

HTTP as a contract: methods, safety, idempotency, retries and server authority.

HTTP Through a Backend Engineer's Eyes

The v1 resources and endpoints, derived from business capabilities rather than tables.

Designing Resources and Endpoints

Spring MVC handlers that map HTTP to use cases and keep business workflow out.

Controllers in Spring Boot

Operation-specific DTOs as authority and exposure boundaries.

Request and Response Models

Mapping every expected outcome to a status, including hidden ownership and business conflicts.

HTTP Status Codes

Bean Validation for request shape, and where live business rules belong instead.

Request Validation

One Problem Details contract with stable codes, implemented in one central handler.

Consistent API Error Responses

Bounded collections with validated parameters, deterministic ordering and exact totals.

Pagination and Filtering

What `/api/v1` versions, and which changes break clients.

API Versioning

Describing the v1 contract, including its failures, in an OpenAPI document.

Documenting APIs with OpenAPI

Generating the document from the code and adding the meaning tooling cannot infer.

Generating OpenAPI with springdoc-openapi

The application after module 5, started locally and called with curl.

Module 5 Checkpoint: Calling the API

Solutions to the practice exercises of lessons 5.01 to 5.06.

Module 5 Practice Solutions: Lessons 5.01–5.06

Solutions to the practice exercises of lessons 5.07 to 5.11.

Module 5 Practice Solutions: Lessons 5.07–5.11

Building REST APIs

Until now the application has kept its state in memory, and a restart erased every Product. This module makes business state durable in PostgreSQL. It decides which state the application owns, designs the smallest schema that stores it, with keys and constraints that PostgreSQL enforces, and maps that schema with Jakarta Persistence, Hibernate and Spring Data JPA behind the repository boundary the earlier modules drew. Flyway puts the schema under version control, and Hibernate only validates it. The module then reads the database's side of performance: indexes derived from real queries, query plans, pagination in the query itself, and the JPA habits that hide extra SQL. It ends with a checkpoint where Products created through the API are still there after a restart.

Which state must survive a restart, who owns it, and what the database is not for.

Why Our Application Needs Persistence

From object graphs to tables, keys, joins, normalization and constraints.

Relational Database Thinking

The four tables, their types and constraints, and what we deliberately leave out.

Designing the Initial Schema

Identity, composite keys, referential integrity and restrictive delete behaviour.

Primary Keys and Foreign Keys

What JPA, Hibernate and Spring Data each do, and how they stay behind our repositories.

Spring Data JPA

Explicit entity mappings for the schema, with assigned UUIDs and readable enums.

Entity Mapping

The one association we map, and why most foreign keys stay scalar IDs.

Relationships

Application repositories, Spring Data repositories and the adapters between them.

Repositories

Versioned migrations, schema history, checksums and validation at startup.

Database Migrations with Flyway

Indexes from real queries, composite column order and reading query plans.

Indexes and Query Performance

Deterministic ordering, `LIMIT`/`OFFSET`, count queries and their trade-offs.

Pagination at the Database Layer

N+1 queries, lazy-loading leaks, dirty checking and other hidden database work.

Avoiding Common JPA Problems

The application after module 6 on PostgreSQL 18: migrations, rows and a restart.

Module 6 Checkpoint: Data That Survives a Restart

Solutions to the practice exercises of lessons 6.01 to 6.06.

Module 6 Practice Solutions: Lessons 6.01–6.06

Solutions to the practice exercises of lessons 6.07 to 6.12.

Module 6 Practice Solutions: Lessons 6.07–6.12

Persistence with PostgreSQL

The domain model, the API contract and the database schema exist; this module makes them work together. Each ticket becomes a use case that owns one business operation and its transaction: Product creation, updates, deactivation and browsing, Inventory administration, Order creation with purchase-time prices and overflow-safe totals, and Order cancellation. Along the way the module answers the questions that decide whether a backend is correct under real load: how two Customers ordering the last unit cannot both succeed, what a transaction really guarantees in PostgreSQL, which failures roll back what, how an Order moves between states, and how business errors differ from system errors. It ends with a checkpoint where you run the whole application and call it with real requests.

What a use case owns, what it delegates, and why one business operation is one transaction.

Use Case Responsibilities

The first complete vertical slice, from request to committed row.

Implementing Product Creation

Partial updates, deactivation instead of deletion, and lost updates.

Implementing Product Updates and Deactivation

Customer browsing of orderable Products, with filtering and paging in the database.

Implementing Product Browsing

Administrator Inventory endpoints and the rules that keep stock non-negative.

Implementing Inventory Management

Validating, pricing and consuming Inventory for a new Order in one transaction.

Implementing Order Creation

Money in long cents, purchase-time prices and totals that cannot overflow silently.

Calculating Order Totals

Why check-then-act oversells, and the atomic conditional UPDATE that does not.

Checking and Consuming Inventory Safely

What `@Transactional` guarantees, and the rollback, propagation and proxy rules behind it.

Database Transactions

Each way an Order can fail halfway, and what the database holds afterwards.

Rollback and Failure Scenarios

Order states, legal transitions, and where each rule is enforced.

Order State Transitions

Cancelling with a row lock and restoring Inventory atomically.

Order Cancellation

Telling expected business outcomes from failures, and what that means for HTTP, logs and retries.

Business Errors vs System Errors

The complete application after module 7, started locally and exercised with curl.

Module 7 Checkpoint: Running the Application

Solutions to the practice exercises of lessons 7.01 to 7.07.

Module 7 Practice Solutions: Lessons 7.01–7.07

Solutions to the practice exercises of lessons 7.08 to 7.13.

Module 7 Practice Solutions: Lessons 7.08–7.13

Implementing Business Workflows

Until now any caller could do anything. This module establishes who is calling and what they may do, without letting security leak into the domain. The backend never stores passwords: it validates access tokens from the identity provider, turns the token's subject into a `CustomerId`, enforces that Customers reach only their own Orders, and restricts catalog and Inventory management to administrators. The tests cover allowed and denied callers through the real filter chain, and the checkpoint runs a local identity provider so you can call the API with real tokens.

Who is calling versus what they may do, and which layer answers each question.

So far, we have deliberately postponed security implementation, yet our workflows already assume it. Create Order assumes an authenticated `CustomerId` that came from a trusted identity, and Product administration assumes that only an authorized administrator may perform the operation. Now we need to make those assumptions explicit.

Before introducing Spring Security configuration, filters, tokens or authorities, we need to separate two questions. **Authentication** asks *"Who is making this request?"* **Authorization** asks *"What is that authenticated identity allowed to do?"* The two are related, but they are not interchangeable. The goal of this lesson is:

> **Establish a clear security model where authentication determines trusted identity, authorization determines allowed operations, and resource ownership remains an application-level rule when it depends on business data.**

## Authentication and Authorization

**Authentication** turns an incoming HTTP request into an authenticated identity. The external identity capability may, for example, establish a stable subject such as `user-abc-123`. Our backend does not need to know how that user originally proved who they are (password, social login, magic link, MFA) unless it owns those responsibilities, and it does not. The Order Management Backend receives the *result* of authentication.

**Authorization** asks whether this authenticated identity may perform this operation. A Customer may create an Order and cancel their own Order; an Admin may modify a Product; a Customer may not modify Inventory. Authentication gives us identity; authorization evaluates permissions using that identity and the operation being attempted.

The order matters. We cannot meaningfully ask *"Is this caller an Admin?"* until we know who the caller is, so authentication establishes the trusted security context from which authorization decisions are made:

```mermaid
flowchart LR
    A["Request"] --> B["Authenticate"]
    B --> C["AuthenticatedUser"]
    C --> D["Authorize"]
    D --> E["Handler / use case"]
```

## Our Security Requirements

The requirements we have accumulated throughout the course fall into two groups. An authenticated **Customer** can:

* create an Order
* view their own Orders and their own Order details
* cancel their own eligible Order
* pay their own eligible Order

A Customer cannot operate on another Customer's Order. An authorized **Admin** can create, update and deactivate Products, manage Inventory and view administrative Order data. Our current requirements do not need a large permission system; these two categories are enough for now.

## Identity Is Not a Role

`CustomerId` answers *"Who owns this Order?"*; the `ADMIN` authority answers *"What may the current caller do?"* As we decided when modeling Customer (4.05), there is no `record CustomerId(String value, Role role)`, and `Order` holds its `customerId` but no `Role` or `boolean admin`: an Admin who may view all Orders is authorized to do so, which does not make the Admin their owner, and a person who later gains Admin access keeps their historical ownership.

## Identity Comes From Outside, Authority Never From the Client

Our backend does not own registration, password storage or the identity lifecycle. It receives the *result* of authentication from an external identity capability, so it needs a stable `CustomerId`, not a `customers` table or an `IdentityService` called on every request. Which token claim carries the stable subject, and how it becomes a `CustomerId`, is the next lesson's subject; we do not invent claim names, an issuer or an OAuth flow here. Credentials are never identity: an access token is temporary and rotatable and must never become `orders.customer_id`.

The client controls intent, the server controls authority. A Create Order body with `"customerId": "customer-999"` would let a caller create an Order owned by someone else, so the request stays items only. A Create Product body with `"isAdmin": true`, or a command whose extra `true` means "caller is Admin", would be just as wrong. The client can say *"I want to order Product X, quantity 2."* It cannot authoritatively say *"I am Customer Y"*, *"I am an Admin"* or *"I own Order Z"*.

## Keep Spring Security Out of the Domain and Use Cases

This would be wrong inside `Order`:


```java
public void cancel() {
    Authentication authentication =
            SecurityContextHolder.getContext().getAuthentication();

    // determine current user...
}
```

Now the domain depends on Spring Security, thread-local security state and framework infrastructure. Our domain should stay testable with plain Java, without authentication infrastructure. The same applies one layer out: `createOrderUseCase.execute(authentication, command)` makes application code know Spring Security directly. Instead, the security/HTTP boundary extracts the application concept, and the use case receives only what it needs:


```java
CustomerId customerId = currentUser.customerId();
Order order = createOrderUseCase.execute(
        new CreateOrderCommand(customerId, items));
```

A useful mental model is that **security integration is an adapter**: it translates Spring Security's `Authentication` into an application-friendly identity. In this module that adapter becomes a `CurrentUser` abstraction, built in the next lesson, from which the handler obtains a `CustomerId` without exposing Spring Security throughout the application.

## Authorization Has Two Levels

For our application, authorization happens at two levels that solve different problems.

### Endpoint-Level Authorization

Some operations have simple role requirements. These are Admin only:

```http
POST /api/v1/products
PATCH /api/v1/products/{productId}
POST /api/v1/products/{productId}/deactivate
PUT /api/v1/inventory/{productId}
```

The decision does not require loading a Product or Inventory row to discover who owns it: the caller either has the `ADMIN` authority and reaches the handler, or is rejected. That is a good fit for security-layer authorization.

### Resource-Level Authorization

Now consider `POST /api/v1/orders/{orderId}/cancel`. Knowing that the caller is a `CUSTOMER` is not enough; we also need to know whether this Order belongs to this Customer. That depends on application data, so the decision needs the authenticated `CustomerId` plus the Order's ownership. This is resource-level authorization.

It also shows that authentication does not prove ownership. Customer A may be fully authenticated and request an Order belonging to Customer B: authentication succeeds, but authorization must still fail. *Authenticated* does not mean *authorized for every resource*, and this distinction is fundamental.

Our Order operations already scope such queries by owner, `findOwnedById(orderId, customerId)` and the locking `findOwnedForUpdate(orderId, customerId)`, so a missing Order and another Customer's Order both produce `404 ORDER_NOT_FOUND` rather than a `403` that would reveal the Order exists (5.05). Lesson 8.03 enforces this across every Customer endpoint. For a Customer calling an Admin Inventory endpoint, an explicit `403 ACCESS_DENIED` is perfectly appropriate.

## 401, 403 and 404

Our error model (7.13) already established three meanings, and the security implementation must preserve them instead of introducing ad-hoc responses:

| Situation | Code | Status |
| --- | --- | --- |
| No valid authentication | `AUTHENTICATION_REQUIRED` | `401 Unauthorized` |
| Authenticated, but lacks permission for the operation | `ACCESS_DENIED` | `403 Forbidden` |
| Customer cannot see the requested Order | `ORDER_NOT_FOUND` | `404 Not Found` |

A `401` never reaches business processing and is never thrown by the domain. A `403` means the caller's identity is known but lacks authority, as when a regular Customer sends `PUT /api/v1/inventory/{productId}`.

Spring Security draws the first two lines for us. With a bearer-token resource server, an Admin-only rule on `PUT /api/v1/inventory/**` and every other endpoint requiring authentication, a quick MockMvc run against Spring Boot 4.1 gives:

```text
GET /api/v1/orders, no token            -> 401
  WWW-Authenticate: Bearer resource_metadata="http://localhost/.well-known/oauth-protected-resource"
GET /api/v1/orders, invalid token       -> 401
  WWW-Authenticate: Bearer error="invalid_token", ...
PUT /api/v1/inventory/p1, no ADMIN role -> 403
  WWW-Authenticate: Bearer error="insufficient_scope", ...
PUT /api/v1/inventory/p1, ADMIN role    -> 200
```

The statuses and `WWW-Authenticate` challenges (RFC 6750) are right by default, but the bodies are empty. Later in this module we keep these statuses and add our `ApiProblem` bodies, so security errors look like every other error in the API.

## Customer and Admin Are Authorization Concepts

Our requirements use *Customer* and *Admin* as application language. We should not assume that the external identity provider literally sends `ROLE_CUSTOMER` or `ROLE_ADMIN` claims. The security integration may need to map the provider-specific representation into application authorities. This lesson defines the application rule; `BACKEND-118` settles the provider contract (a `roles` claim mapped to `ROLE_ADMIN`, lesson 8.04).

## Security in Our Workflows

Each workflow takes its trusted inputs from this model. Create Order receives the authenticated `CustomerId`, so `Order.customerId` is trustworthy. Order history binds `WHERE customer_id = :customerId` to the authenticated Customer, so nobody sends `?customerId=someone-else`, and Order detail, cancellation and later payment load the owned Order before anything else; the payment provider does not decide who owns an Order. Product and Inventory administration pass the `ADMIN` check before the handler runs, so neither `Product` nor `Inventory` ever contains `if (!currentUser.isAdmin())`. Whether `GET /api/v1/products` is public is not yet decided; we take it from the product requirement when configuring endpoint security.

## Security Does Not Replace Business Rules

Security establishes that a request belongs to Customer A; the application must still validate that the Product exists, is active and has Inventory. And *"the Customer owns the Order"* does not mean *"the Order can be cancelled"*: both checks are required. Domain rules should not depend on roles either. *A PAID Order cannot be cancelled in v1* stays true whether the caller is a Customer or an Admin. If a future Admin refund workflow is introduced, it will be a different business operation; we do not weaken `order.cancel()` into `order.cancel(boolean isAdmin)` to anticipate requirements that do not exist.

For the same reason, roles do not go into commands without need. Avoid `new CancelOrderCommand(customerId, orderId, Role.CUSTOMER)` when the use case only needs a trusted `CustomerId` for ownership, and do not hand Admin Product use cases an `isAdmin = true` after the security boundary has already authorized the operation. Pass business and application inputs; do not keep propagating security implementation details.

## Framework Authorization and Application Rules Complement Each Other

An annotation or a security rule can express *"ADMIN authority required"* or *"authenticated user required"*, and that works well for coarse endpoint authorization. But it cannot necessarily answer *"Does Customer A own Order X?"* without loading application data. So:

> **Framework authorization and application ownership rules complement each other.**

Nor do we go the other way and encode *"Can this Customer cancel this specific Order in its current state?"* into a complex security expression: authentication and coarse authority belong to the security boundary, ownership to the application workflow and repository, and cancellability to the Order domain.

## Testing Strategy

Because of this separation, domain tests need no Spring Security, and use case tests pass an explicit `new CustomerId("customer-1")` to prove that a Customer can access their own Order and not another's. Only security integration tests need the wired framework: an unauthenticated request is rejected, a Customer cannot reach an Admin endpoint, an Admin can, and the authenticated identity becomes the correct `CustomerId`.

## Our Current Security Model

The model now has four separate layers of reasoning:

| Layer | Question it answers |
| --- | --- |
| Authentication | Who is the trusted caller? |
| Authorization | Which operations is the caller permitted to perform? |
| Ownership | Does this specific resource belong to the authenticated Customer? |
| Domain lifecycle | Is the requested business transition itself valid? |

A cancellation request must pass all four questions in turn: is there an authenticated caller; is the caller acting as a Customer for this Customer endpoint; does this Order belong to that Customer; is the Order currently `UNPAID`? Then and only then do we cancel the Order and restore Inventory, and each question belongs to a different responsibility.

Product update is simpler: is the caller authenticated, does the caller have Admin authority, does the Product exist, and is the requested Product change valid? There is no Customer ownership check. Different operations need different authorization models.

## Practice Exercise 1: Impersonate a Customer Locally

_Solutions: lesson 8.06._

Start the application from the module 7 checkpoint (7.14) with the `local` profile, where `LocalCurrentUser` reads the Customer from the `X-Customer-Id` header. As `customer-ana`, create an Order for one unit of a stocked Product. Then act as Ben, who wants to cancel Ana's Order:

1. With `X-Customer-Id: customer-ben`, request `GET /api/v1/orders` and `POST /api/v1/orders/{orderId}/cancel` for Ana's Order.
2. Change only the header to `customer-ana` and repeat both requests.
3. With no header at all, send `PUT /api/v1/inventory/{productId}` with `{"availableQuantity": 500}`.

Predict each status and code before you send it. Then, for each step, name which of the four questions of this lesson (authentication, authorization, ownership, domain lifecycle) the application answered correctly and which one it could not answer.

## Practice Exercise 2: Which Layer Says No?

Assume the model of this lesson is fully built. Ana and Ben are Customers; Order `A-1` is Ana's and `PAID`, Order `B-1` is Ben's and `UNPAID`. For each request, name the layer that rejects it (or say that it succeeds), with status and code:

1. `POST /api/v1/orders/{A-1}/cancel` with no token
2. Ana: `POST /api/v1/orders/{A-1}/cancel`
3. Ana: `POST /api/v1/orders/{B-1}/cancel`
4. Ana: `PUT /api/v1/inventory/{productId}` with `{"availableQuantity": 50}`
5. An Admin: `POST /api/v1/products` with `{"name": "Desk Mat", "priceCents": -100}`
6. Ana: `POST /api/v1/orders` with a valid item and `"customerId": "customer-ben"` in the body

## Practice Exercise 3: Review a Cancellation Shortcut

A teammate wants "Admins can cancel paid Orders" and proposes:


```java
public record CancelOrderCommand(String customerId, OrderId orderId,
        boolean isAdmin) {
}

@PostMapping("/{orderId}/cancel")
public OrderResponse cancel(@PathVariable String orderId,
        @RequestParam String customerId,
        @RequestHeader(name = "X-Admin", defaultValue = "false") boolean admin) {
    return OrderResponse.from(cancelOrder.execute(
            new CancelOrderCommand(customerId, toOrderId(orderId), admin)));
}

// in Order
public void cancel(boolean isAdmin) {
    if (status != OrderStatus.UNPAID && !isAdmin) {
        throw new OrderNotCancellable();
    }
    status = OrderStatus.CANCELLED;
}
```

Find at least four problems, using this lesson's rules.

## Knowledge Check

### Question 1

A request carries a valid token for Customer A and asks for Customer B's Order. Which question has been answered, and which has not?

### Question 2

Why is the Admin check for `PUT /api/v1/inventory/{productId}` a good fit for the security boundary, while Order ownership is not?

### Question 3

Why does `Order` store a `CustomerId` but no role?

### Question 4

Why does a Customer requesting another Customer's Order get `404`, while a Customer calling an Admin endpoint gets `403`?

### Question 5

Why should `CreateOrderUseCase` receive a `CustomerId` instead of Spring Security's `Authentication`?

## Knowledge Check Answers

### Answer 1

Authentication is answered: we know the caller is Customer A. Authorization for this resource is not: being authenticated does not make Customer A the owner of Order B.

### Answer 2

"Has `ADMIN` authority" depends only on the caller, so it can be decided before any data is loaded. Ownership depends on which Customer the Order belongs to, which only the application's data can answer.

### Answer 3

Ownership is durable business state that must stay true for years. A role is runtime authorization state that can change at any time and says nothing about who owns the Order.

### Answer 4

An Order ID is private to its owner, and `404` avoids confirming that another Customer's Order exists. Admin endpoints are part of the public API; there is nothing to hide, so `403` honestly says "known caller, not allowed".

### Answer 5

The use case only needs the trusted identity. With `Authentication` it would depend on Spring Security, and its tests would need a security context instead of a plain `new CustomerId("customer-1")`.

## Engineering Principle

> **Authentication determines who the caller is. Authorization determines what that caller is allowed to do. Resource ownership is a form of authorization that may require application data and therefore cannot always be solved by endpoint-level role checks alone.**

Trusted identity comes from the security boundary, never from client-controlled business input, and security infrastructure stays there: use cases receive a `CustomerId`, and domain objects never see Spring Security.

## Summary

* Authentication asks who is making the request; authorization asks what that identity may do, and it comes second.
* Authentication is provided by an external identity capability; we need a stable `CustomerId`, not a local Customer table, and credentials such as tokens and sessions are never durable identity.
* Identity and role are different: `Order` stores Customer ownership but no role, and Admin access does not change ownership.
* The client expresses intent; `customerId` and Admin authority never come from the request.
* Spring Security stays at the boundary: an adapter maps it to `CustomerId` and authorities, and neither use cases nor domain objects see `Authentication`.
* Endpoint-level authorization handles coarse Admin restrictions; resource-level authorization, through ownership-aware queries, handles Customer-owned Orders, and missing and non-owned Orders both return `404 ORDER_NOT_FOUND`.
* `401` means no valid authentication, `403` an authenticated caller without permission; Spring Security produces both by default, and security never replaces business validation or domain lifecycle rules.
* Domain tests need no Spring Security, use case tests use explicit `CustomerId` values, and security integration tests verify real endpoint behavior.

In the next lesson, Integrating Authenticated User Identity, we connect this model to the application boundary: bearer authentication through Spring Security to an `AuthenticatedUser` and `CurrentUser`, and from the stable subject to a `CustomerId`, while keeping Spring Security types out of use cases and domain objects and leaving the external identity system as the authority.

Authentication vs Authorization

Validating JWT access tokens with Spring Security and turning `sub` into a `CustomerId`.

Integrating Authenticated User Identity

Ownership enforced in queries, and why another Customer's Order is a 404.

Enforcing Customer Resource Ownership

Mapping the roles claim to an ADMIN authority and protecting administrative routes.

Enforcing Administrator Permissions

Keycloak in Compose, real tokens, and the API called as a Customer and as an administrator.

Module 8 Checkpoint: Logging In Locally

Solutions to the practice exercises of lessons 8.01 to 8.04.

Module 8 Practice Solutions: Lessons 8.01–8.04

Authentication and Authorization

Payment is the first operation that leaves our process, and it changes the rules: a network call can succeed, fail, or end without telling us which, and no database transaction can include it. This module builds the payment integration from that fact. It defines a provider-independent boundary, implements the client with timeouts and a strict classification of answers, decides when a retry is safe, keeps every remote call outside database transactions, persists each payment attempt before the call, serializes payment against cancellation, and exposes the result as an honest API. The checkpoint pays for real Orders against a stub provider that can approve, decline, time out and fail on demand.

A `PaymentService` port that speaks our language, not the provider's.

Defining the Payment Integration Boundary

The `RestClient` adapter, configuration without defaults, and tests against a stub server.

Implementing the Payment Provider Client

Working with External Services

Build a production-style Java backend with Spring Boot while learning real-world engineering practices, from requirements and RFCs to testing, deployment, and production incidents.