Capstone 1: Requirements and Architecture

This article writes no business code at all, yet it decides whether the next three articles are "building upward" or "filling holes". We do exactly one thing: turn a vague wish — "users can place orders" — into a contract nobody has to guess at. The contract states who asks for what (user stories with acceptance criteria), which things and rules exist in this world (the domain model and state machine), where each part stands (layering and module boundaries), and what the system says to the outside world (the API list).

Six terms explained in one line each — they recur throughout:

• Requirement: the sentence someone says out loud, "I want a checkout feature" — that is not a requirement, it is a wish; only the phrasing you can write a test case against counts
• User story: the wish rewritten as "As a ⟨role⟩, I want ⟨capability⟩ so that ⟨value⟩", always followed by acceptance criteria you can verify
• Domain model: the nouns and the iron rules of this business — orders, stock, payments, plus laws like "stock can never go negative" — nothing to do with database tables yet
• Aggregate root: the single door into a group of objects that must change together. Items are modified through the order, the way an invoice line is corrected by reissuing the invoice
• Layering: lining your code up by "who stands nearest to the user": Controller first, Service in the middle, Mapper last, with dependencies pointing only forward
• Contract: a specification both frontend and backend sign, fixing what the request looks like, what the response looks like and which code an error carries. Signed means no unilateral edits

That map is also this article's table of contents: the first branch is the call direction (Section 6), the five after it are what the six business packages own (Section 8), and common at the bottom is the three shared building blocks. While reading, hold on to one fact: no arrow on the map points back to the left — that discipline matters more than any framework detail, and its cost shows up live in the risk list of Section 10 and the error table of Section 13.

After this article you should be able to answer three questions:

1. Between "checkout should be fast" and "P99 latency under 500ms", why does only the second belong in a requirements document? What is the test?
2. order may call inventory but not the reverse — why? If someone breaks the rule, does the trouble surface at compile time, at startup or at runtime? The error table in Section 13 gives the answer.
3. Where is the real line between a monolith and microservices — "how many jars you ship", or "who can scale and release independently"?

The previous 40 articles took Spring apart piece by piece — IoC, AOP, Web, data access, transactions, caching, security, async and events, monitoring. But knowledge is scattered; real development demands you assemble them into one project that runs as a whole. Starting here, four articles deliver a complete, launch-ready project: BeeOrder, the Hive Order Center.

First, the boundaries. It is an e-commerce order-backend monolith that runs the main path from "a user registers" to "a user receives goods":

Equally important is a not-to-do list — stating what you will not build prevents scope creep better than listing features:

• No frontend: every deliverable is a REST API, verified with curl or Postman (#46 shows an optional Docker-hosted UI, but it is not required).
• No real payments: real payment needs merchant credentials and keys; we use a "mock payment gateway" plus a callback endpoint to fully reproduce the state and idempotency of payment.
• No microservice split: a monolith first, with clean boundaries; the end of this article discusses "when to split", but this project does not.
• No big data or recommendations: operational stats stop at "daily order count and revenue".

The initial requirement is often just one sentence: "users can place orders." But how much code that means, and when it is done, nobody can say. Requirements analysis turns vague expectations into acceptance-testable user stories.

The standard form is "As a ⟨role⟩, I want ⟨capability⟩ so that ⟨value⟩", with acceptance criteria attached. BeeOrder's core story cards:

Notice the last two rows — they are not triggered by "a user click" but are system behaviors. Such requirements are the most easily forgotten, yet they directly determine whether stock is released correctly.

The table above is the finished product; the animation below plays it backwards — watch one vague wish get cornered by three questions into a testable story card:

The question most often skipped is "in which scene", and that is exactly where system behaviours like "close unpaid orders after 30 minutes" come from. A story whose acceptance criteria will not come out is a story whose questions have not been asked to the end.

With requirements clear, first find the "nouns" of the world. BeeOrder has seven core domain objects:

The relationships: a user has many orders; an order contains many items; each item points to a product; each product has one inventory record; a payment maps to an order. The order is the aggregate root — changing items must go through the order.

Key business rules must be written down, because they map directly to code branches and constraints:

• Order total = Σ(unit price × quantity), stored as DECIMAL or cents; never double.
• Stock can never go negative: deduction must be guarded at the database level with a conditional update (WHERE available >= ?).
• Status changes only follow the state machine; no skipping from CREATED straight to COMPLETED.
• Only one valid payment per order: repeated callbacks must be idempotent.
• Every change to money or stock leaves a ledger entry for reconciliation.

Order status is the project's most central abstraction. Once the states are muddled or the transitions loose, you get dirty data like "a cancelled order receiving a successful payment". BeeOrder has six states:

CREATED → PAID → SHIPPED → COMPLETED, plus two terminal branches, CLOSED and REFUNDED. The full transition table:

That table is the state machine's entire statute book, but reading statutes three times beats one glance at the picture. Drawn as a single map you can tape next to your monitor:

Read it by the mnemonic "one main line, two terminals, three conditions": the main line CREATED → PAID → SHIPPED → COMPLETED only moves rightward; CLOSED and REFUNDED each enter through one designated door and never leave; and the three conditions (state matches event, target is allowed, side effects transactional) are written into validation code in the next article.

Every transition must satisfy three conditions: the current state matches the event, the target is in the allowed set, and side effects run in the same transaction or via reliable events. Turning this table into an enum plus a validation method in code is next article's job.

Choosing a stack is trade-offs, not name-dropping. BeeOrder's choices:

Each row deserves the question "why not the other one". For example, why MyBatis over JPA: the project's two most critical queries — UPDATE inventory SET available = available - ? WHERE product_id = ? AND available >= ? (atomic deduction) and the daily aggregation for reports — are exactly "precise SQL control" scenarios, where JPA's auto-generation gets in the way.

BeeOrder uses a layered monolith with four layers, top to bottom, and a one-way request flow:

• Access layer (Controller): protocol adaptation only — validation, DTO to domain conversion, calling a service, wrapping a uniform response. No business logic here.
• Application layer (Service): business orchestration and transaction boundaries. Checkout is "validate stock -> create order -> deduct stock -> record ledger", and that orchestration belongs here.
• Domain and data layer (Mapper / Repository): MyBatis handles persistence, Redis serves cache and distributed locks, MySQL is the single source of truth.
• Infrastructure: Actuator provides observability, logging spans the whole path, and Docker Compose handles local and deployment orchestration.

Read the same picture once more, this time asking per layer, top to bottom: "did this layer reach over and grab someone else's job?" The four chips in the access layer are all protocol work (auth, validation, conversion, wrapping responses); the four in the application layer are about who orchestrates whom; the data layer only stores and fetches, it judges nothing. Finish the sweep and you will find not one line pointing back up:

Module boundaries are expressed as packages. Within one module, split by business, and inside each package by controller / service / mapper / domain / dto:

Boundary discipline: cross-module calls go one way — "upper calls lower", "order calls inventory". Two-way dependencies are forbidden. order depending on inventory and product is fine; inventory depending back on order creates a cycle and must be avoided.

See what that discipline governs, one click at a time — the first four nodes are each layer's "never", and the last is the bill for breaking it:

After the last node, look back at the endpoint list in Section 7: every endpoint walks down this chain, none of them reaches the Mapper directly.

So which module actually deserves to leave the monolith? Do not guess — measure it on two axes: horizontal is how often the package changes, vertical is whether it needs to scale on its own.

Two conclusions are enough to read this chart: common, top right, ripples through the entire project when touched, so tests freeze it in place; inventory, top left, is the only package that is both write-heavy and narrow-interface, so on the day a split really happens it is the first seam. A boundary is not a service — order and product, bottom right, change weekly yet need nothing more than a one-way dependency.

The API contract is the "contract" for frontend/backend collaboration. BeeOrder uses the prefix /api/v1. The full list (about 15 endpoints):

Conventions: all responses are wrapped as { "code": 0, "message": "ok", "data": ... }; code != 0 signals a business error. /payments/callback skips JWT but must verify the gateway signature and be idempotent — it is the only publicly exposed write endpoint and the largest attack surface.

One last structural decision before coding: multi-module Maven, or a single module with packages? Many teams immediately split into beeorder-user, beeorder-order and so on, then find that touching one API means editing three poms and every build is slow.

BeeOrder picks the single-module layout. The tree:

Section 8's conclusions plus the quadrant from Section 6 make one good matching game: the left is each module's or option's situation, the right is the disposition this article prescribes. A wrong pair explains itself on the spot:

The project splits into four iterations, matching four articles, each with clear deliverables:

Use that animation as a progress bar: its six frames land on the four rows of the table above — frame 1 is this article, frame 2 is #44, frame 3 is #45, frames 4-6 all belong to #46. When a frame stalls you, look up which row you are standing in. Each frame delivers exactly one thing, and nothing moves on until the previous one is accepted — that discipline keeps four articles from ending as four piles of code that never run together:

Listing risks at kickoff beats a post-mortem after an incident. BeeOrder's four main risks:

Before freezing the design, run four labs that show what this architecture actually prevents. Lab 1: layers and dependency direction — it draws that restaurant service passage as real calls:

Lab 2: one request across the whole site. The architecture picture shows four boxes, but a request walks a far longer road — authentication, validation, transaction, stock deduction and messaging each live at a different stop:

Lab 3: conditional assembly, which answers "same feature, but staging and production must behave differently". Conditional annotations — the @Conditional family, the gate that decides whether a bean gets wired based on whether a class exists, a bean exists or a property is set — are the bouncers of auto-configuration:

Lab 4: your own starter, which packs all three lessons into one box. A starter — a bundle of dependencies plus auto-configuration, ready to use the moment you declare it — is literally "other people's hard-won lessons" put in a box. BeeOrder will pull in spring-boot-starter-web, mybatis-spring-boot-starter and friends, so it is worth knowing what is inside a box:

Lab 5: type those conclusions into a real container. The four labs above let you look; this console lets you type — boot the container, name the beans, then run layering, layer-skipping, the request journey and condition evaluation as one pipeline:

Once beans has listed them, recall the layer picture from Section 6: every bean's seat is decided by its package and the direction of its dependencies — far more intuitive than memorising a directory tree.

Architecture will not change how long your day is, but it decides how many files one requirement has to touch. The sandbox below folds Sections 6 and 8 into a single three-position switch; each position shows side by side whether the app boots, how many files an added column touches, and whether cross-module calls now go over the network:

A warm-up question on how to read the technology-choice table in Section 5:

Now a combined question threading Sections 6, 7 and 10:

However tidy the design doc, day one of coding still hits walls. Copy each fragment below straight into a search box — do not paraphrase or shorten it.

That cycle in the table's second row reads very differently as the original text. Here is the raw report; every fragment is clickable, and a wrong pick still tells you why it is not the one:

One line of review is enough: the only spot you actually edit is that backward import inside the inventory package; every other frame explains why it is not the one.

Three tiers: level 1 runs if you type it in; finish level 3 and you own your own architecture review checklist.

Goal: assemble the BeeOrder skeleton yourself, then deliberately break the wiring once and watch the could not be found failure happen.

Step one, a new pom.xml (Spring Boot 3.2.5 + Web + JDBC; it starts fine without MySQL):

No need to type that pom by hand — tick it out. The three defaults (Web / Validation / JDBC) are exactly the minimal skeleton level 1 needs; then look over the dependencies the next three articles will pull in — know the total first, then decide what actually goes in today:

Step two, create the packages from Section 8 and write the startup class plus two minimal classes. The startup class must sit in com.beeorder, the common ancestor of every business package:

Step three, start it and call it:

Expected response — one bare line, no JSON envelope (the envelope is next article's job):

Step four, break the wiring. Rewrite OrderMapper.java the way MyBatis projects really write it — an interface plus @Mapper — and move it from com.beeorder.order.mapper to com.beeorder.dao. Notice it is still under the startup class's subtree, so "outside the scanned package" is not the excuse this time:

Restart, and the console stops right here:

Two layers of cause, the second more subtle: ① an interface has no implementation for the container to instantiate reflectively — a mapper instance is produced on demand by MyBatis' dynamic proxy, never by component scanning; ② @Mapper carries no @Component semantics, so being inside the scanned subtree changes nothing. Without mybatis-spring-boot-starter (or without telling it where to find the interfaces), the chain snaps at the wiring stage.

Step five, repair it: add @MapperScan("com.beeorder.dao") to the startup class and make sure the MyBatis starter is in pom.xml. Restart, curl again, and mapper-ok returns. The lesson you keep forever: "can the package be scanned" and "who wires this kind of object" are two different questions — ordinary classes via component scan, mapper interfaces via @MapperScan, third-party pieces via starter auto-configuration.

Acceptance checklist: ① explain why step four failed and step five succeeded; ② name the single word in that error that actually decides the outcome (scan); ③ switch the controller from constructor injection to a field @Autowired and restart — it still fails, because "does this bean exist" is answered during wiring regardless of injection style. Say that clearly and you have separated "missing bean" from "bean ordering".

Change exactly one thing per run and the conclusion flips:

1. Build a reverse dependency across layers: give OrderMapper a private final OrderService orderService; (constructor injection) while OrderService constructor-injects OrderMapper. You will observe startup failing with the log drawing orderService ==> orderMapper ==> orderService. Now switch the OrderMapper side to field injection: on Boot 3 it still fails, because spring.main.allow-circular-references has defaulted to false since Spring Boot 2.6; only when you set it to true does the field-injection side get through via the three-level cache — the app runs, but the module boundary has collapsed.
2. Move @Transactional off OrderService's public orchestration method onto a private helper in the same class and call it through this.helper(). You will observe neither variant raising anything nor rolling back — transactions ride the proxy, and the proxy can only intercept "a public method called in from outside". Put the annotation back on the public method, invoked by the controller through the injected bean, and the second failing write now undoes the first. Compare with the "where the tx boundary sits" position of Lab 1 in Section 10; both should tell the same story. (Do not try to prove it with getClass(): only beans that actually match advice get proxied, and controllers usually do not.)
3. Delete spring-boot-starter-jdbc from pom.xml. You will observe the app booting normally as long as nothing injects JdbcTemplate — dropping a starter drops capability, it need not error; the moment something injects it, startup reports No qualifying bean. Cross-check the condition evaluation report from --debug and find the DataSourceAutoConfiguration line marked matched: false.

Tip: after variant 1, reopen the second row of the table in Section 13 — both should match exactly.

Write yourself an architecture health check you can run on any future project before touching its code.

Requirements:

• A LayerRulesTest (plain JUnit + reflection, no business class may be modified) that walks every .java file under src/main/java reading its package and import statements
• Enforce three rules: ① no controller package imports a mapper package; ② no package imports a class from order that in turn imports back (detecting cycles of length 2); ③ common imports no business package
• On violation print a table: file, line, offending import, which rule broke, suggested extraction
• Ship an ARCHITECTURE.md template stapling the Section 6 layer diagram, the Section 7 endpoint list and this rule table together

Acceptance checklist: ① run it on the current skeleton and rule ① immediately catches PingController importing OrderMapper; ② insert an OrderService as suggested and the test goes green; ③ fabricate an inventory -> order -> inventory cycle and the script reports it in the test phase instead of waiting for the app to fail at boot; ④ the whole exercise changes zero lines of business code.