System Architecture · Insper · Lab 1

Lab 1 — First service: catalog

A web service for events and venues: Spring Boot, PostgreSQL, Flyway, a container — and its unloaded latency

The story so far

lab 0 · the ceilingstock Nginx: tens of thousands of req/s
→
chapter 2 · lab 1catalog: one service, one database
→
next · lab 2the knee, measured

At 10:00 the demand is ~33,000 holds/s; one PostgreSQL does ~1,100. First: how fast does one real service answer one user?

  • The service time you measure today is the reference for every later lab.

Why catalog first?

During the flash sale, how many reads of the event page happen for each change an admin makes?

  • Millions of fans refresh; a handful of admins edit → read-heavy.
  • It will be the guinea pig for load balancing (lab 3), caching (lab 5), indexing (lab 6).
  • Today: the simplest version that works — monolith-first.

What you will build

fanGET /catalog/events?city=Recife
→
catalog :8082Spring Boot · 1 CPU, 768 MB
→
db :5432PostgreSQL 17, schema catalog
query 1events JOIN venues · ORDER BY starts_at · LIMIT 20
query 2count(*) for the page links: 20,000
200{items, page: 0, totalItems: 20000}
  • 50 venues in 10 cities, 200,000 events, seeded by a migration: a realistic volume on purpose.
  • Event 1: BoxOffice Fest — Stadium Night, at a 60,000-seat stadium — the flash-sale show of the course.

The contract

Method Path Answer
GET /catalog/events?city=&page=&size= page of upcoming events
GET /catalog/events/{id} event + venue, or 404
POST /catalog/events 201 + Location
PUT · DELETE /catalog/events/{id} 200 · 204
GET · POST /catalog/venues venues

Everything under /catalog: the edge and the gateway route without rewriting paths.

Design decisions

  • Collections are paginated, size ≤ 50 — every list is bounded.
  • Money is BigDecimal / NUMERIC(10,2); time is TIMESTAMPTZ, ISO-8601.
  • Errors follow Request for Comments (RFC) 9457: problem+json.
  • 201 Created + Location for new resources.

In the interview: resources + verbs, pagination strategy, error model.

Three layers, one rule

  • Controller: HTTP, validation, status codes.
  • Service: business rules, @Transactional.
  • Repository: queries (Jakarta Persistence, JPA).

The application programming interface (API) never returns entities: only records, the data transfer objects (EventOut, VenueOut). A new column must not leak; a lazy association must not explode.

Which status code?

POST /catalog/events
→
@Valid EventIn, @Min / @Maxchecked before the method runs
→
CatalogServicedoes the venue exist?
→
201 Created+ Location
400 problem+jsonmissing title, price −1, ?size=500
400 / 404unknown venue / unknown id
@RequestParam(defaultValue = "20") @Min(1) @Max(50) int size
  • ?size=500 → 400 problem+json, not a 500-row query.

JPA: watch the N+1

Listing 20 events, each with its venue. How many Structured Query Language (SQL) queries?

  • Without join fetch: 1 + 20 = 21 round trips.
  • With select e from Event e join fetch e.venue: 1.
  • Each round trip holds one of the 10 pooled connections longer.

Flyway: the schema is code

  • V1__create_catalog.sql, V2__seed_catalog.sql — applied once, in order.
  • Never edit an applied migration: add V3__....
  • ddl-auto: validate: Hibernate checks, Flyway owns.
  • Seed with generate_series: 200,000 events, identical on every laptop.

Realistic data volume on purpose: a query instant on 10 rows can take tens of ms on 200,000.

The container: two stages

build · maven:3.9-eclipse-temurin-21
pom.xml + src/
mvn package~/.m2 in a cache mount
target/app.jar
COPY --from=build →
runtime · eclipse-temurin:21-jre
app.jarrun by user app, not root
no Java Development Kit (JDK), no Maven, no sources
  • java -XX:MaxRAMPercentage=75: the heap follows the container's memory limit.
  • The image ships only a Java Runtime Environment (JRE) and the jar.

Compose: what up waits for

db starts
→
pg_isreadyevery 5 s → healthy
→
catalog startsdepends_on: service_healthy
→
Flyway V1, V2then Hibernate validates
→
/actuator/health/readinessUP → healthy
  • Volume db-data: data survives down; down -v resets.
  • 1 CPU, 768 MB per catalog: a fixed unit of capacity.

Inside a container, the database is db, not localhost.

Measure it: service time

k6 run load/smoke.js        # 1 VU, 30 s, think time 0.5 s
Endpoint p50 p95 p99
GET /catalog/events/{id} ~5 ms ~11 ms ~40 ms
GET /catalog/events?city= ~30 ms ~42 ms ~71 ms

One laptop's numbers — record yours in results/lab1.md.

Reading the baseline

  • Listing ≈ 2–6× the detail: join + sort + count(*) over 20,000 rows; the detail is a primary-key lookup.
  • p99 ≫ p50 even with one user: just-in-time (JIT) compilation, garbage collection, cold pool, cold pages.
  • Always warm up before measuring; never compare cold with warm.

Which endpoint will break first under load? Write the hypothesis for lab 2.

What breaks next

lab 1 · service timeone user: detail ~11 ms, listing ~42 ms at p95
→
how many req/s?the preview draws ~530; 10:00 asks for ~33,000
→
lab 2 · measure firstopen load until latency explodes: the knee
  • Write your hypothesis now: which resource fills first?

Takeaways

  1. Design the contract first: resources, bounded collections, status codes, problem+json.
  2. Records decouple the API from the tables.
  3. join fetch avoids N+1; every query borrows a pooled connection.
  4. Flyway owns the schema; applied migrations never change.
  5. One command to run it all: docker compose up --build.
  6. Record the unloaded latency: it is the reference for every later lab.

Chapter 2 of the story. Outline: (1) why catalog first; (2) what you will build; (3) the API contract; (4) layers, DTOs and status codes; (5) JPA, N+1, the pool; (6) Flyway; (7) Dockerfile and Compose; (8) smoke test and service time.

The story of the course (2027.1 overview, "The story of the course"): every chapter opens with the number the previous one left. Lab 1 opens chapter 2: the one service and one database that class 2 checks on paper.