a. Overview

Every ticketing site starts with the same page: what is on, where, and when? In BoxOffice that is the job of catalog. It is the most read-heavy service of the system — during a flash sale, millions of fans refresh the event page while only a handful of administrators ever change it — and that is why it will be the guinea pig for load balancing (lab 3), caching (lab 5) and indexing (lab 6). Today you build the simplest version that works, the monolith-first step of the scaling journey.

Before you start

Check the tools:

docker compose version        # Docker Compose v2.x (or newer)
java -version                 # 21 or newer
mvn -v                        # Apache Maven 3.9+
k6 version                    # k6 v1.0+
uv --version                  # uv (runs the Python helper scripts)

Start state — the end of lab 0:

📁 boxoffice/
├──  .gitignore
├── 📁 load/
│   └──  hello.js
├── 📁 results/
│   └──  lab0.md
└── 📁 scripts/
    └──  check-env.sh

Slides

Click the slides and use ← → to move through them; F goes full screen and P opens the presenter view, with the notes. Open the slides in a new tab

What you will build

sequenceDiagram
    autonumber
    actor Fan
    participant C as catalog :8082<br/>(Spring Boot)
    participant DB as db :5432<br/>(PostgreSQL, schema catalog)
    Fan->>C: GET /catalog/events?city=Recife
    C->>DB: SELECT events JOIN venues WHERE city = ? ORDER BY starts_at LIMIT 20
    DB-->>C: 20 rows
    C->>DB: SELECT count(*) ... (total for the page links)
    DB-->>C: 20000
    C-->>Fan: 200 {items: [...], page: 0, totalItems: 20000}

The service follows a classic three-layer structure — controller (HTTP, validation, DTOs) → service (business rules, transactions) → repository (SQL through JPA) — with one rule that matters for everything that follows: the API never exposes the database entities, only records (EventOut, VenueOut) that you control.

The database starts with 50 venues in 10 cities and 200,000 events (one per hour from March 2027), generated by a Flyway migration¹. Event 1 is the course's flash-sale show: BoxOffice Fest — Stadium Night, at a 60,000-seat stadium. A realistic volume of data is deliberate: a query that is instant on 10 rows can take tens of milliseconds on 200,000, and that is exactly what you will measure.

Steps

When the three steps are done, your repository looks like this:

📁 boxoffice/
├──  docker-compose.yaml
├── 📁 load/
│   ├──  hello.js
│   └──  smoke.js
├── 📁 results/
│   ├──  lab0.md
│   └──  lab1.md
└── 📁 services/
    └── 📁 catalog/
        ├──  Dockerfile
        ├──  .dockerignore
        ├──  pom.xml
        ├── 📁 src/main/java/boxoffice/catalog/
        │   ├──  CatalogApplication.java
        │   ├──  Category.java
        │   ├──  Event.java              Venue.java
        │   ├──  EventRepository.java    VenueRepository.java
        │   ├──  CatalogService.java
        │   ├──  EventController.java    VenueController.java
        │   └──  EventIn.java  EventOut.java  VenueIn.java  VenueOut.java  PageOut.java
        └── 📁 src/main/resources/
            ├──  application.yaml
            └── 📁 db/migration/
                ├──  V1__create_catalog.sql
                └──  V2__seed_catalog.sql

Measure it: the unloaded baseline

Before asking "how much load can it take?" (lab 2), record how fast each endpoint is with a single user. That is the service time: the best latency you will ever see, and the reference for every comparison later.

Save the smoke test as load/smoke.js:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

// Lab 1: smoke test. One user, 30 seconds: does every endpoint answer, and how fast
// when the service is NOT under load?   k6 run load/smoke.js
import http from 'k6/http';
import { check, sleep } from 'k6';

const BASE_URL = __ENV.BASE_URL || 'http://localhost:8082';
const CITIES = ['São Paulo', 'Rio de Janeiro', 'Belo Horizonte', 'Porto Alegre', 'Curitiba',
  'Salvador', 'Recife', 'Fortaleza', 'Brasília', 'Manaus'];

export const options = {
  vus: 1,
  duration: '30s',
  summaryTrendStats: ['avg', 'med', 'p(95)', 'p(99)', 'max'],
  thresholds: {
    http_req_failed: ['rate==0'],
    // one threshold per endpoint makes k6 print one latency line per endpoint
    'http_req_duration{name:GET /catalog/events/{id}}': ['p(95)<200'],
    'http_req_duration{name:GET /catalog/events?city}': ['p(95)<500'],
  },
};

export default function () {
  const id = 1 + Math.floor(Math.random() * 200000);
  const detail = http.get(`${BASE_URL}/catalog/events/${id}`,
    { tags: { name: 'GET /catalog/events/{id}' } });
  check(detail, { 'detail is 200': (r) => r.status === 200 });

  const city = CITIES[Math.floor(Math.random() * CITIES.length)];
  const list = http.get(`${BASE_URL}/catalog/events?city=${encodeURIComponent(city)}&page=0&size=20`,
    { tags: { name: 'GET /catalog/events?city' } });
  check(list, {
    'list is 200': (r) => r.status === 200,
    'list has 20 items': (r) => r.json('items').length === 20,
  });

  sleep(0.5);   // think time: a real user does not click non-stop
}

With the stack running (step 3):

The numbers above come from a run on a laptop; yours will differ. Two things should stand out anyway: the listing is clearly slower than the detail, about 2 to 6 times (it joins two tables, sorts and counts thousands of rows; the detail is a primary-key lookup), and p99 is far from the median even with a single user (JIT compilation, garbage collection, the first connections of the pool).

Record the results in results/lab1.md:

# Lab 1 — catalog, unloaded (1 VU, 30 s)

| Endpoint                     | p50 (ms) | p95 (ms) | p99 (ms) | max (ms) |
|------------------------------|---------:|---------:|---------:|---------:|
| GET /catalog/events/{id}     |          |          |          |          |
| GET /catalog/events?city=... |          |          |          |          |

- Startup time ("Started CatalogApplication in ... seconds"): ____ s
- Image size (`docker image ls boxoffice-catalog`): ____ MB
- Seed time (Flyway "Successfully applied 2 migrations ... execution time"): ____ s
- Why is the listing slower than the detail? ____

Troubleshooting

Clean up

docker compose down          # stop and remove the containers, keep the database volume
# docker compose down -v     # ...and also erase the database (Flyway seeds it again next time)

Keep the repository as it is: lab 2 measures this same service.

Deliverable

• services/catalog builds and runs with docker compose up --build; Flyway applies V1 and V2.
• Every endpoint of the table answers as described (try the 400 and 404 cases too — the body must be application/problem+json²).
• The OpenAPI document is served at http://localhost:8082/catalog/openapi.
• load/smoke.js passes all thresholds; results/lab1.md is filled in.
• Repository tagged lab1; quiz answered.

End state

📁 boxoffice/
├──  docker-compose.yaml                      # new: db + catalog
├──  load/smoke.js                            # new
├──  results/lab1.md                          # your measurements
└── 📁 services/catalog/                        # new: the whole service
    ├──  Dockerfile  .dockerignore  pom.xml
    ├──  src/main/java/boxoffice/catalog/*.java   (14 classes)
    ├──  src/main/resources/application.yaml
    └──  src/main/resources/db/migration/V1__create_catalog.sql, V2__seed_catalog.sql

Running: db (PostgreSQL 17, schema catalog with 50 venues and 200,000 events) and catalog on port 8082.

Next: Lab 2 — Measure first.