JAVA-290 · Lesson 3 of 12 · 35 min
Architecture and technology choices
▶ Video coming soon A video version of this lesson is on the way.
On Wednesday, May 24, 2028, Leif Quarmby joined the team's evening with Ingrid. He runs the shop's server and the pipeline that deploys the booking API, and he had one question before anyone drew a box: what will I have to run, and what happens at three in the morning when it breaks? Ingrid had a different first question: which of the requirements are hard to change later? Those two questions frame architecture better than any diagram. Architecture is the set of decisions about a system's structure that are expensive to reverse, and the job of this lesson is to make those decisions deliberately, write them down and leave everything else to be decided while building.
What already exists
The team was not starting from nothing, and that shaped every choice. The booking API that Hamza built in the winter is a Spring Boot 4 service in the hexagonal style from the design course: a domain package with the slot rules and no framework code, an application package of use cases behind ports such as BookRepair and SlotQuery, and adapters around them, REST controllers on one side and JPA repositories, the SMS notifier and the supplier clients on the other. Its data lives in the PostgreSQL database that also holds StockStore's parts tables, with Flyway migrations up to V6. Since late April it has been deployed through the pipeline from the deployment course, blue-green behind Caddy on the shop's rented server, at api.secondgear.org.
| Piece | What it does today | Who uses it |
|---|---|---|
| Booking API 1.5.0 | Free slots, bookings, part availability, staff status changes; REST under /api/v1 | Counter app since May; the website, planned |
| PostgreSQL 17 | Parts, stock movements, repair bookings | Booking API, StockStore |
| Pipeline | Build, test, secret scan, image to ghcr.io, staging, approved blue-green production | Leif, Hamza |
| Caddy 2 | TLS certificates, routing by host name to containers | Every public request |
| Prometheus and Grafana | Metrics, dashboards, burn-rate alerts to Leif's phone | Leif |
Hamza drew this as a context diagram and a container diagram in the notation of Simon Brown's C4 model, which describes software at four zoom levels: the system in its context, the containers that run, the components inside a container and, if needed, the code. A container in C4 means anything that runs or stores data on its own, such as a web application or a database, not specifically a Docker container. The first two levels are usually enough for a team to agree on, and they are the ones a newcomer needs first.
Requirements that shape the architecture
Most of the stories could be built in almost any architecture. The non-functional requirements could not, because they constrain the whole system rather than one feature. Ingrid asked the team to name, for each one, what it rules out. This is the heart of architecture work: quality attributes such as performance, accessibility, security and operability decide the structure, while functional requirements decide the contents.
| Requirement | What it pushes toward | What it rules out |
|---|---|---|
| N1 accessible, works without JavaScript | Pages rendered on the server as plain HTML forms | A page that is empty until a script runs |
| N2 small screens, old browsers | Little or no client code, small pages | Large script bundles and the newest browser features |
| N3 p95 under 300 ms | Few network hops; queries that use indexes | Chains of services calling each other per page |
| N4 delete personal data after 30 days | One place that stores customer data | Copies of bookings in several stores |
| N5 deploy through the existing pipeline | One artifact, built and deployed as now | A second, separately deployed service with its own pipeline |
| N6 no guessable references, limited lookups | Existing references and a lookup limiter | Sequential booking numbers in links |
Three ways to build the website
Noemi came prepared. In March, Tamsin's plan for the website had been a single-page application in TypeScript that calls the booking API through a client generated from its OpenAPI document. Noemi had built exactly that kind of site in her program, and she liked it. Thierry had read about a third option in which a separate Spring Boot service renders the pages and calls the API on the server, sometimes called a backend for frontend. Hamza's option was to add the pages to the booking service itself, as a new driving adapter beside the REST controllers, calling the same ports. Ingrid asked each to argue for the option they did not prefer, which made the evening much more useful.
| Option | How it works | Strongest argument | Weakest point |
|---|---|---|---|
| 1. Single-page app | TypeScript in the browser calls the REST API | Rich interaction; the API already exists | Needs JavaScript; a second build, hosting and test toolchain |
| 2. Separate page service | A new Spring Boot app renders HTML and calls the API over HTTP | Pages and API change independently | Two services to deploy, monitor and secure; an extra network hop per page |
| 3. Site adapter in the booking service | Spring MVC controllers and templates call the same application ports | One artifact, one pipeline, no extra hop | Pages and API are released together; the service grows |
To compare them, they used the same approach as for choosing the project, but this time each criterion was a quality attribute from the list, weighted by how much it mattered to the clients, and each option was scored on how well it supports that attribute. The point was not to let a spreadsheet decide, but to see whether the arguments people were making actually added up.
import java.util.*;
public class Main {
record Attribute(String name, int weight) {}
public static void main(String[] args) {
List<Attribute> attrs = List.of(new Attribute("accessibility without JS (N1, N2)", 5),
new Attribute("page speed (N3)", 3), new Attribute("one place for personal data (N4)", 3),
new Attribute("deploy through existing pipeline (N5)", 4), new Attribute("team skills", 4),
new Attribute("rich interaction", 1), new Attribute("pages and API change independently", 2));
Map<String, int[]> options = new LinkedHashMap<>();
options.put("1 single-page app", new int[] {1, 3, 4, 2, 2, 5, 4});
options.put("2 separate page service", new int[] {5, 3, 4, 2, 4, 3, 5});
options.put("3 site adapter", new int[] {5, 5, 5, 5, 4, 3, 2});
for (var e : options.entrySet()) {
int total = 0;
StringBuilder weak = new StringBuilder();
for (int i = 0; i < attrs.size(); i++) {
total += attrs.get(i).weight() * e.getValue()[i];
if (e.getValue()[i] <= 2 && attrs.get(i).weight() >= 3) weak.append(" [weak: ").append(attrs.get(i).name()).append("]");
}
System.out.println(e.getKey() + ": " + total + weak);
}
}
}1 single-page app: 55 [weak: accessibility without JS (N1, N2)] [weak: deploy through existing pipeline (N5)] [weak: team skills] 2 separate page service: 83 [weak: deploy through existing pipeline (N5)] 3 site adapter: 98
What this code does
The scores run from 1, which means the option works against the attribute, to 5, which means it supports it fully, and each is multiplied by the attribute's weight. Besides the total, the program lists any important attribute, weight 3 or more, where an option scores 2 or less, because one serious weakness can matter more than a good total. The single-page app is weak exactly where the clients' strongest requirements are, while the site adapter's only low score is on an attribute weighted 2.
Noemi's honest assessment of her own option was the turning point. A single-page app can be made accessible, and good ones are, but it takes careful work with focus management and live regions, and nothing appears until the script loads, which on Jordan's old phone with limited data might be several seconds. A plain HTML form posted to a server, on the other hand, has worked in every browser for thirty years and is accessible by default if the markup is right. She agreed to option 3 on one condition: that the team would allow small scripts later for progressive enhancement, such as updating the free times without reloading, provided every page still worked without them.
Option 2 lost more narrowly. Its advantage, that pages and API change independently, mattered little when the same three people would change both. Its costs were real: a second service in the pipeline, a second set of health checks and alerts for Leif, and an extra network call on every page, which would eat into the 300 ms budget. Leif summed it up: split a system when two teams need to release independently, not before.
Recording decisions
A decision explained in a meeting is forgotten within weeks, and the people who join later never hear it. Michael Nygard proposed in 2011 that teams record each significant decision in a short text file called an architecture decision record, or ADR, kept in the repository beside the code. An ADR has a title, a status, the context that forced the decision, the decision itself and its consequences, good and bad. ADRs are never edited to change their meaning; if a decision changes, a new ADR supersedes the old one, so the history of the team's thinking is preserved.
# ADR-001: Serve the website from the booking service as a site adapter
Status: Accepted (2028-05-24)
## Context
Customers need public pages to see free times, book, find and cancel bookings (US-01 to US-03).
The pages must work without JavaScript and with assistive technology (N1, N2), serve a page
in under 300 ms at the 95th percentile (N3), keep personal data in one place (N4) and deploy
through the existing pipeline (N5). The team is three people for one term, two of them Java
developers. The booking API already implements the slot rules and bookings behind ports.
## Options
1. Single-page application in TypeScript calling the REST API.
2. A separate Spring Boot service rendering pages and calling the API over HTTP.
3. Spring MVC controllers and server-side templates in the booking service, calling the
same application ports as the REST controllers.
## Decision
Option 3. The site is a new driving adapter in org.secondgear.booking.adapters.site.
It may use the application ports and the domain, never the persistence adapters directly.
## Consequences
+ One artifact, one pipeline, one set of alerts; no extra network hop per page.
+ Plain HTML forms work without JavaScript; small scripts may enhance pages later.
- Pages and API are always released together.
- The service grows; if a second team ever owns the pages, revisit with a new ADR.What this code does
The context names the requirements by their numbers, so a later reader can check whether they still hold. The decision states a rule about dependencies as well as the choice itself, because a rule is what keeps the decision true as code is added. The consequences list the costs honestly, including the condition under which the team should reconsider.
That evening produced five ADRs. Not every choice deserved one. Ingrid's test was whether a newcomer, seeing the code six months later, would wonder why it was done that way, and whether the answer would take more than a sentence. Choosing a date format did not pass the test; choosing how staff sign in did.
| ADR | Decision | Main reason |
|---|---|---|
| 001 | The website is a site adapter in the booking service | Accessibility, one pipeline, team size |
| 002 | Pages are rendered with Thymeleaf templates | Templates are valid HTML that Noemi can edit; well supported by Spring Boot |
| 003 | Staff sign in with a form and a session; the counter app keeps HTTP Basic on the REST API | Browsers need sign-out and CSRF protection; the counter app is a program |
| 004 | Texts are queued in an outbox table and sent by a scheduled job | A booking must not fail because the SMS provider is slow |
| 005 | The same image serves book.secondgear.org; Caddy routes the new host name | No new container; one deployment |
The ADRs live as numbered files in docs/adr, and the README links to an index. A small program regenerates the index from the files' first lines in the build, so it can never fall out of date. Running it on the five files, plus a sixth that Thierry wrote as a joke and then rejected, shows the shape.
import java.util.*;
import java.util.regex.*;
public class Main {
record Adr(int number, String title, String status, String date) {}
static Adr read(String fileText) {
String[] lines = fileText.strip().split("\n");
Matcher t = Pattern.compile("# ADR-(\\d+): (.+)").matcher(lines[0]);
Matcher s = Pattern.compile("Status: (\\w+(?: by ADR-\\d+)?) \\((\\d{4}-\\d{2}-\\d{2})\\)").matcher(lines[2]);
if (!t.matches() || !s.matches()) throw new IllegalArgumentException("bad header: " + lines[0]);
return new Adr(Integer.parseInt(t.group(1)), t.group(2), s.group(1), s.group(2));
}
public static void main(String[] args) {
List<String> files = List.of(
"# ADR-003: Staff sign in with a form and a session\n\nStatus: Accepted (2028-05-24)\n",
"# ADR-001: Serve the website from the booking service\n\nStatus: Accepted (2028-05-24)\n",
"# ADR-006: Write the site in COBOL\n\nStatus: Rejected (2028-05-24)\n",
"# ADR-002: Render pages with Thymeleaf\n\nStatus: Accepted (2028-05-24)\n",
"# ADR-005: Same image serves book.secondgear.org\n\nStatus: Accepted (2028-05-24)\n",
"# ADR-004: Queue texts in an outbox table\n\nStatus: Accepted (2028-05-24)\n");
List<Adr> adrs = new ArrayList<>(files.stream().map(Main::read).toList());
adrs.sort(Comparator.comparingInt(Adr::number));
System.out.println("| No. | Decision | Status |");
System.out.println("|-----|----------|--------|");
for (Adr a : adrs) System.out.printf("| %03d | %s | %s %s |%n", a.number(), a.title(), a.status(), a.date());
long accepted = adrs.stream().filter(a -> a.status().equals("Accepted")).count();
System.out.println(accepted + " accepted of " + adrs.size());
}
}| No. | Decision | Status | |-----|----------|--------| | 001 | Serve the website from the booking service | Accepted 2028-05-24 | | 002 | Render pages with Thymeleaf | Accepted 2028-05-24 | | 003 | Staff sign in with a form and a session | Accepted 2028-05-24 | | 004 | Queue texts in an outbox table | Accepted 2028-05-24 | | 005 | Same image serves book.secondgear.org | Accepted 2028-05-24 | | 006 | Write the site in COBOL | Rejected 2028-05-24 | 5 accepted of 6
What this code does
Each file's first line gives the number and title and its third line the status and date, read with regular expressions that reject a file whose header is malformed instead of guessing. The records are sorted by number, because the order of files on disk is not something to rely on, and printed as a Markdown table for the README. The status pattern already allows a value such as Superseded by ADR-007 for the day a decision changes.
Choosing the technologies
With the structure decided, most technology choices followed from what the shop already ran and what the program had taught. Ingrid's advice was to be boring on purpose: a capstone has enough unknowns without adding a framework nobody on the team has used. Each new library had to earn its place by solving a problem the team actually had.
| Need | Choice | Already used? |
|---|---|---|
| Language and runtime | Java 25 on the Temurin JRE image; code kept compatible with Java 21 | Yes, booking API |
| Framework | Spring Boot 4.1 with Spring MVC | Yes |
| Page templates | Thymeleaf through Spring Boot's starter | New (ADR-002) |
| Staff sign-in | Spring Security 7 form login, sessions, CSRF tokens | Partly; the API uses HTTP Basic |
| Data | PostgreSQL 17, Spring Data JPA with Hibernate 7, Flyway migrations from V7 | Yes |
| Build | Gradle wrapper in the repository | Yes |
| Tests | JUnit 6, Mockito, Testcontainers, Spring's MockMvc | Yes |
| Browser tests and accessibility | Playwright for Java with axe-core | New; Noemi has used both |
| Delivery | GitHub Actions, Docker image, Compose and Caddy on the shop server | Yes |
Thymeleaf won its ADR against two alternatives. JSP was dismissed quickly because it is old and awkward with Spring Boot's executable JARs, and a newer, faster template engine was rejected because only Hamza had read about it and nobody had used it. Thymeleaf's deciding feature for Noemi was that its templates are valid HTML files with extra attributes, so she could open one in a browser, edit it and run accessibility checks on it before any Java existed. It also escapes text by default when it inserts values into a page, which matters a great deal in lesson 9.
The listing shows how small the change to the build file is. Everything else the website needs was already on the class path.
dependencies {
// existing
implementation("org.springframework.boot:spring-boot-starter-web")
implementation("org.springframework.boot:spring-boot-starter-data-jpa")
implementation("org.springframework.boot:spring-boot-starter-security")
implementation("org.springframework.boot:spring-boot-starter-validation")
implementation("org.springframework.boot:spring-boot-starter-actuator")
implementation("org.flywaydb:flyway-database-postgresql")
runtimeOnly("org.postgresql:postgresql")
// new for the website (ADR-002)
implementation("org.springframework.boot:spring-boot-starter-thymeleaf")
implementation("org.thymeleaf.extras:thymeleaf-extras-springsecurity6")
testImplementation("org.springframework.boot:spring-boot-starter-test")
testImplementation("org.springframework.boot:spring-boot-testcontainers")
testImplementation("org.testcontainers:postgresql")
testImplementation(libs.playwright) // versions in gradle/libs.versions.toml
testImplementation(libs.axe.playwright)
}What this code does
Versions of Spring's own modules come from the Spring Boot plugin and its dependency management, so only libraries outside Spring carry a version. The Thymeleaf security extras let a template show or hide a link depending on whether a staff member is signed in. Playwright and the axe-core integration are test dependencies only, so they never reach the production image, and their versions sit in the Gradle version catalog file, where Dependabot proposes updates.
Keeping the dependency rule
ADR-001's rule, that the site adapter may use the application ports and the domain but never the persistence adapters, is exactly the kind of decision that decays one convenient import at a time. The booking API already ran an ArchUnit test in its build that enforced the hexagon's dependency rule; Hamza extended it to the new package. To show the team what the rule means, he wrote the check in plain Java first, over a list of the imports each class would have.
import java.util.*;
public class Main {
static final Map<String, Set<String>> ALLOWED = Map.of(
"domain", Set.of("domain"),
"application", Set.of("domain", "application"),
"adapters.rest", Set.of("domain", "application", "adapters.rest"),
"adapters.site", Set.of("domain", "application", "adapters.site"),
"adapters.persistence", Set.of("domain", "application", "adapters.persistence"));
static String layer(String cls) {
String rest = cls.substring("org.secondgear.booking.".length());
return rest.startsWith("adapters.") ? rest.substring(0, rest.indexOf('.', 9)) : rest.substring(0, rest.indexOf('.'));
}
public static void main(String[] args) {
Map<String, List<String>> imports = new LinkedHashMap<>();
imports.put("org.secondgear.booking.adapters.site.SlotsPage",
List.of("org.secondgear.booking.application.SlotQuery", "org.secondgear.booking.domain.Slot"));
imports.put("org.secondgear.booking.adapters.site.CancelPage",
List.of("org.secondgear.booking.application.CancelBooking",
"org.secondgear.booking.adapters.persistence.BookingRepository"));
imports.put("org.secondgear.booking.domain.SlotCalendar",
List.of("org.secondgear.booking.domain.Slot"));
imports.put("org.secondgear.booking.application.BookingService",
List.of("org.secondgear.booking.domain.Booking", "org.secondgear.booking.adapters.site.SlotsPage"));
int violations = 0;
for (var e : imports.entrySet()) {
String from = layer(e.getKey());
for (String target : e.getValue()) {
String to = layer(target);
if (!ALLOWED.get(from).contains(to)) {
violations++;
System.out.println("VIOLATION " + e.getKey().substring(23) + " (" + from + ") -> " + to);
}
}
}
System.out.println(violations + " violation(s) in " + imports.size() + " classes");
}
}VIOLATION adapters.site.CancelPage (adapters.site) -> adapters.persistence VIOLATION application.BookingService (application) -> adapters.site 2 violation(s) in 4 classes
What this code does
The layer method reads a class's layer from its package name, treating each adapter as a layer of its own so that the site adapter may not reach into the persistence adapter. ALLOWED lists, for each layer, the layers it may depend on, which encodes the rule that dependencies point inwards toward the domain. The check finds two violations: the cancel page reaching past the port to the repository, and the application layer importing a page class, which points outwards.
In the real build the same rule is three lines of ArchUnit, and it runs in every pull request. The listing is what Hamza added to the existing architecture test.
@ArchTest
static final ArchRule siteUsesPortsOnly =
noClasses().that().resideInAPackage("..adapters.site..")
.should().dependOnClassesThat().resideInAnyPackage("..adapters.persistence..", "..adapters.rest..")
.because("ADR-001: the site adapter calls application ports, never other adapters");What this code does
ArchUnit reads the compiled classes and fails the test if any class in the site package depends on a class in the persistence or REST packages. The because clause puts the ADR's number into the failure message, so a developer who breaks the rule learns why it exists. The existing rule that the domain depends on nothing else already covered the outward import that the plain Java check found.
A budget for page speed
N3, a 95th percentile under 300 ms, was the booking API's existing service level objective, and the website would share it. A requirement for the whole page is easier to meet when it is split into a budget for each part of the path, so that each developer knows what their part may spend and a slow part shows up before the whole is too slow. Leif had measured the existing parts on the production dashboard, so the team could start from real numbers rather than guesses.
import java.util.*;
public class Main {
record Part(String name, int p95ms, boolean measured) {}
public static void main(String[] args) {
int budget = 300;
List<Part> parts = List.of(
new Part("Caddy: TLS and routing", 4, true),
new Part("Spring Security filters and session", 6, true),
new Part("free-slot query for 14 days (indexed)", 18, true),
new Part("part availability for the problem kind", 9, true),
new Part("render the slots template", 25, false));
int total = 0;
for (Part p : parts) {
total += p.p95ms();
System.out.printf("%-40s %3d ms %s%n", p.name(), p.p95ms(), p.measured() ? "measured" : "estimate");
}
System.out.println("sum of parts: " + total + " ms of " + budget + " ms budget");
System.out.println("headroom: " + (budget - total) + " ms");
System.out.println("note: adding p95 values overestimates the p95 of the sum, so the sum is a safe upper bound");
}
}Caddy: TLS and routing 4 ms measured Spring Security filters and session 6 ms measured free-slot query for 14 days (indexed) 18 ms measured part availability for the problem kind 9 ms measured render the slots template 25 ms estimate sum of parts: 62 ms of 300 ms budget headroom: 238 ms note: adding p95 values overestimates the p95 of the sum, so the sum is a safe upper bound
What this code does
Each part of the path to serve the slots page has a 95th percentile time, either measured on the existing service or estimated for the new template, and the sum is compared with the 300 ms objective. Adding percentiles is not exact, because the slowest requests for one part are not usually the slowest for another, but the sum is an upper bound, which is the safe direction for a budget. With about 240 ms of headroom, the design is comfortable, and the estimate for template rendering is the number to measure first.
The headroom confirmed the decision against option 2: a call from a separate page service to the API would have added a network round trip and a second set of filters on every page, perhaps 20 ms, which would still have fitted. Speed was not the deciding factor; simplicity was. The budget also told the team where to look if pages ever became slow: the template estimate was the only number nobody had measured.
A spike for the riskiest unknown
The riskiest unknown at the end of the evening was not technical in the usual sense. Nobody knew how long it would take Noemi, who knew HTML well and Java only from one introductory course, to work productively in Thymeleaf templates inside a Spring project. A spike is a short, time-boxed experiment that answers one question and is then thrown away. Noemi took a spike for the Thursday and Friday: render the next free times as a list on a page, with real data from a local database, in no more than six hours.
The spike worked in four and a half hours, and its findings went into the team's notes rather than the code. Templates were comfortable; running the application locally with Docker for PostgreSQL took her an hour to set up, which became a one-command script for everyone; and the slots page, with its styles, weighed about 14 KB before compression. That number became a budget too: every public page under 50 KB, with no image heavier than the page itself.
import java.util.*;
public class Main {
public static void main(String[] args) {
int budgetKb = 50;
Map<String, int[]> pages = new LinkedHashMap<>(); // page -> {html bytes, css bytes, script bytes}
pages.put("slots (spike)", new int[] {9_800, 4_300, 0});
pages.put("booking form (estimate)", new int[] {7_200, 4_300, 0});
pages.put("single-page app shell (Noemi's earlier project)", new int[] {1_100, 18_000, 182_000});
for (var e : pages.entrySet()) {
int bytes = Arrays.stream(e.getValue()).sum();
int kb = (bytes + 1023) / 1024;
System.out.printf("%-48s %4d KB %s%n", e.getKey(), kb, kb <= budgetKb ? "ok" : "over budget");
}
int seconds = 182_000 * 8 / 400_000;
System.out.println("at 400 kbit/s, 182 KB of script alone takes about " + seconds + " s to download");
}
}slots (spike) 14 KB ok booking form (estimate) 12 KB ok single-page app shell (Noemi's earlier project) 197 KB over budget at 400 kbit/s, 182 KB of script alone takes about 3 s to download
What this code does
Each page's weight is the sum of its HTML, style sheet and script bytes, rounded up to whole kilobytes, and compared with the 50 KB budget. The third row is a single-page app shell from Noemi's earlier project, kept as a comparison, and its script alone is over three times the budget. The last line converts bytes to bits and divides by a slow mobile connection's speed, which is what Jordan's phone on a limited plan might see.
What the architecture leaves open
Good architecture decides little and decides it well. The team deliberately left open the shape of the waiting list, the wording of every page, the reminder's timing and the layout of the staff pages, because those were cheaper to decide once they were building and could see the real problem. Ingrid's closing remark was that an architecture is working if the next twelve weeks produce many small decisions and no large surprises, and that the ADRs should be reread at every sprint review in case the context had changed.
Exercises
Try it yourself
Find the dependency violations
Each entry of deps is fromLayer toLayer. A dependency is allowed when toLayer is the same layer, or when it is listed for fromLayer in ALLOWED. Complete main so that it prints each violation as fromLayer -> toLayer, then the number of violations.
import java.util.*;
public class Main {
static final Map<String, Set<String>> ALLOWED = Map.of(
"domain", Set.of(),
"application", Set.of("domain"),
"site", Set.of("application", "domain"),
"persistence", Set.of("application", "domain"));
public static void main(String[] args) {
List<String> deps = List.of("site application", "site persistence", "application domain",
"domain application", "persistence domain", "site site", "application site");
System.out.println("0 violation(s)");
}
}Try it yourself
The ADR index with superseded records
Each entry is number|title|status, where status is Accepted, Rejected or Superseded by N. Complete main so that it prints, in number order, every record as NNN title [status] with the number padded to three digits, and then a line current: followed by the numbers of the accepted records that are not superseded, separated by commas.
import java.util.*;
public class Main {
public static void main(String[] args) {
List<String> records = List.of("3|Staff form login|Accepted", "1|Site adapter|Accepted",
"6|Write it in COBOL|Rejected", "2|Thymeleaf templates|Superseded by 7",
"7|Thymeleaf templates with fragments|Accepted", "4|Outbox for texts|Accepted");
for (String r : records) System.out.println(r);
}
}By ten o'clock the whiteboard held a container diagram, the bench held five printed ADRs, and Leif had his answer: one image, one more host name in Caddy, the same alerts. What nobody had yet was a plan for who would build what, in what order and how they would keep three people's work from colliding. That came the following Wednesday.
Common mistakes
MistakeDrawing boxes before naming the quality attributes.
InsteadList the non-functional requirements and what each rules out; they decide the structure.
MistakeSplitting into services because it is fashionable.
InsteadSplit when separate teams need to release independently; otherwise one deployable unit is simpler to run.
MistakeExplaining decisions only in meetings.
InsteadRecord significant decisions as ADRs in the repository, with context, options and consequences.
MistakeEditing an old ADR when the decision changes.
InsteadWrite a new ADR that supersedes it, so the history is kept.
MistakeWriting a dependency rule in a document only.
InsteadEnforce it with a test in the build, such as an ArchUnit rule, that names the ADR.
MistakeChoosing an unfamiliar framework for a short project.
InsteadPrefer what the team and the operator already know, and run a time-boxed spike for the riskiest unknown.
Summary and key terms
- Architecture is the set of structural decisions that are expensive to reverse.
- The team started from what already existed: the hexagonal booking API, PostgreSQL, the pipeline and Caddy on the shop server, drawn as C4 context and container diagrams.
- Non-functional requirements decided the structure: working without JavaScript, page speed, one place for personal data and deployment through the existing pipeline.
- Of three options, a single-page app, a separate page service and a site adapter inside the booking service, the team chose the site adapter after weighing the options against weighted quality attributes and arguing each other's cases.
- Decisions were recorded as ADRs with status, context, options, decision and consequences, superseded rather than edited, and indexed automatically.
- Technology choices stayed with what the team and the shop already used, adding Thymeleaf, Playwright and axe-core.
- ADR-001's dependency rule is enforced by an ArchUnit test, a latency budget splits N3 into parts, and a time-boxed spike answered the riskiest unknown.
- Architecture
- The decisions about a system's structure that are expensive to change later.
- Quality attribute
- A property such as performance, accessibility or security that a system must have.
- C4 model
- Simon Brown's way of describing software as context, containers, components and code.
- Container (C4)
- Anything that runs or stores data on its own, such as a web application or a database.
- Driving adapter
- Code that receives requests from outside, such as controllers, and calls the application's ports.
- Architecture decision record
- A short file recording one decision with its context, options and consequences.
- Superseded
- The status of an ADR replaced by a later one, kept for history.
- Dependency rule
- The rule that code dependencies point inwards toward the domain.
- Latency budget
- A split of a response-time objective into allowances for each part of the path.
- Spike
- A short, time-boxed experiment that answers one question and is then thrown away.
Practice problems
Work each problem on paper first, then reveal the answer to check.
Why did the non-functional requirements matter more to the structure than the stories?
Show answer
They constrain the whole system, for example ruling out pages that need JavaScript, while stories mostly decide what the system contains.
Why did option 2 lose despite separating pages and API?
Show answer
The same three people change both, so independence was worth little, while a second service added deployment, monitoring and a network hop.
What should happen to ADR-002 if the team changes template engines?
Show answer
A new ADR records the change and supersedes ADR-002, which keeps its text and gains the superseded status.
Why is the sum of p95 values a safe budget check?
Show answer
The slowest requests for each part rarely coincide, so the sum overestimates the p95 of the whole.
What question did Noemi's spike answer?
Show answer
How quickly she could work in Thymeleaf templates inside the Spring project, and what a server-rendered page weighs.
Lesson quiz · 5 questions
Score 60% or more to complete this lesson.
Create a free account to save your progress, take quizzes and earn a certificate.