Capstone

Eleven chapters taught the pieces on one running example, the library. This chapter uses them on a different system, so that what you practise is the method and not the example: a booking service for a community centre's workshops. The order is the order of the course. Requirements, then use cases, a domain model, a class design, the key behaviours (a sequence diagram and a state machine), a component view, then code that runs, tests and checks that tie the diagrams to the code, and a short design document that says what was decided and what was not.

Step 1: Requirements, as Words, With the Questions They Raise

The input is what the centre's manager said, written down as she said it. Underneath, the questions the words do not answer. Each unanswered question is either asked or assumed in writing, so the assumption can be challenged later.

Note how much of the work is already in the questions. "A week away" (Q4), what happens to someone whose card is declined (Q2) and what a waiting person pays and when (Q5) all change the design, and none was in the manager's words.

Step 2: Use Cases

Actors first (chapter 3): the attendee, the organiser, and three things that are not people: the card service, the e-mail service, and a nightly timer that expires offers. The scope boundary is the service itself.

PlantUML. "Join the waiting list" extends "Book a seat" (the arrow points at the base, as chapter 3 said it must). This diagram is already at the edge of readable: the lines to the two outside services cross. A list of use cases would carry the same facts.

The descriptions carry the substance. Two are written in full. Look at the guarantees and at the extensions: every "what if" from the requirements ended up as a numbered case.

Writing extension 5b of the second use case ("the payment service fails to refund") produced the first real finding. I did not know what the service should do, so the description says NOT YET DESIGNED instead of pretending. It comes back below: the code, written without an answer, does something harmful there.

Step 3: The Domain Model and a Glossary

The concepts and their links, as in chapter 4: written once as data, producing the diagram and the sentences to read aloud to the manager. The glossary fixes the words, including one it forbids.

Mermaid, generated from domain_model.py. Four concepts, three associations. The Booking has a state, which Step 5 expands.

The glossary's note on "Reservation" is chapter 4's lesson applied: in the library a "reservation" was a thing in its own right; here the word would mean "a booking that has not been paid for", which this system never has, so it is banned rather than allowed to mean two things.

Step 4: Class Design and Responsibilities

Using chapter 6's questions (who has the information? who creates? who coordinates?): the Session holds the capacity and the bookings, so it decides who gets a seat and creates the bookings; the Booking knows its own state; a BookingDesk coordinates a use case across the session, the payment service and the notifications and holds no rule. Everything outside is behind an interface that the application declares (chapter 9), and the refund rule is a Strategy (chapter 11).

Mermaid. The desk depends on interfaces; each provider points into one. The Session owns its bookings (composition). This diagram is checked against the code (Step 8).

Step 5: Behaviour: One Sequence, One State Machine

The booking's central scenario is "Book a seat". The sequence diagram (chapter 7) draws the three outcomes in one picture with alt fragments: the session is full, the payment is declined, the payment succeeds.

Mermaid. Drawn by hand from the design, then checked against traces of the real code in Step 8.

The booking also has a life, which is a state machine (chapter 8): it starts Requested, can be Waitlisted, Offered, Confirmed, and ends Declined, Expired or Cancelled. As in chapter 8, the table of transitions is the source, and the diagram is generated from it.

PlantUML, generated from TRANSITIONS in workshops/domain/booking.py.

And the matrix, computed by driving a real booking into every state and sending every event ((stays) means the event was ignored or its guard was false):

Read the matrix as design review. Terminal states accept nothing. A confirmed booking can only be cancelled (by the attendee or by the organiser). Two cells deserve a question: a booking that is still Requested cannot be cancelled by anyone, and cannot be cancelled by the organiser's session cancellation. With synchronous payment a booking is Requested for the length of one call, so this cannot happen today. If payment ever becomes asynchronous it will, which is recorded as a design decision (D8) and not left as a surprise.

Step 6: Structure

PlantUML. The application requires three interfaces and the infrastructure provides them; the two external services are drawn as "would provide" and "would be driven by", because they were not built.

PlantUML, generated from the real imports by chapter 9's checker, adapted to this package. Everything points at the domain.

Step 7: The Code

Three layers, with the dependency rules of chapter 9. The domain holds the rules and imports nothing. These are its key files: the booking and its state machine, the session, and the refund strategy.

The application layer: the interfaces it requires, and the desk that coordinates the use cases.

(The infrastructure, workshops/infrastructure/memory.py, holds an in-memory store, a payment fake that can be told to decline particular people, and a recorder that stands in for the e-mail service. The event classes are plain dataclasses. All of it is in the project files.) A few lines carry decisions from the design document: the desk decides whether an offer is still open before it takes money (accept_offer), a failing subscriber is recorded and never undoes a booking (_publish), and the comment in book says why a declined payment needs no waiting-list handling.

Step 8: Tests, Mutants and Checks

The tests cover the state machine (every state and event pair is defined, ignored or illegal), the session's rules (one seat per person, a seat held from the request, the longest waiter first, the refund boundary) and every desk use case including the failure paths. They pass:

Passing means little until the tests are shown to fail on broken code. Three plausible bugs, each introduced on purpose:

Each was caught: an off-by-one on the refund boundary (exactly seven days must still refund), the newest waiter offered the seat instead of the oldest, and money taken before the offer was checked (the guarantee in the "Book a seat" use case that nobody is charged for something that did not succeed).

Do the Diagrams Match the Code?

The class diagram is checked for drawn operations, attributes and realisations (chapter 11's check). The sequence diagram is checked against three traced runs of the real desk (seat free and paid; session full; payment declined), using chapter 7's tracer, extended to trace a whole package: every call the code makes must be drawn, and every call drawn must be made in at least one run.

It passed on the first run, which is not evidence on its own, so here it is on a copy where I removed a drawn call, added a call the code never makes, and renamed an operation in the class diagram:

Each tamper was found. What it does not check: the order of calls across the alternatives, and anything about the meaning of a message.

The Story

All the use cases end to end, with the e-mails the subscriber would send. Two people book a two-seat pottery session and a third is waitlisted; a card is declined on another session; the first booker cancels twenty days ahead (refunded in full), the freed seat is offered to the waiting person, who does not take it (the offer expires at the nightly run); a second cancellation three days before the session earns no refund; the organiser cancels a session; a booking on that session is refused.

Step 9: A Review, and the Gap It Found

Chapter 11's checklist, applied to the finished design. The architecture rules are clean; the state machine's matrix has no unexplained cell; the smell detector flags nothing in the session or the desk. It flags one thing in booking.py, "anemic?", for the Transition class, which is a false alarm: a row of a table is data by design. Reading the code found what the detectors did not (the exercises build on these):

• The desk sets fields on a booking from outside (receipt and paid_pence, four assignments). A mark_paid on the booking would put that rule with the data.
• Cancelling a session ignores a booking that is still Requested. Harmless with synchronous payment, wrong the day payment is not.
• A question for the manager nobody asked: booking on the day of the session is refused ("already started"). Is that right? It is an assumption.
• What if the payment service fails to refund? This is the "NOT YET DESIGNED" extension from the use case. Here is what the code does today:

That is a real defect, found by writing a use case honestly and then asking what the code does where the use case is silent. The attendee's booking is cancelled, money is owed and nothing records it, and the person waiting does not get their offer until the next nightly run. The design document lists it as gap G1 with a proposal, and Exercise 1 closes it, as a subclass that does not touch the package.

Step 10: The Design Document

A short document, two pages as text, for the next person (who may be you in six months): what the system is for, where each artefact lives, the decisions with their reasons and how each is checked, the evidence of quality, and the gaps. This is the whole of it.

What the Method Gave, and What It Did Not

• It found the questions early (requirements Q1 to Q6) and made the assumptions visible.
• It found one real defect (G1) through a use case extension left honest, and several smaller decisions (D4, D7, D8) while drawing.
• It did not make the design correct. The 23 tests and the checks show the code does what the diagrams say, not that the diagrams are what the centre needs. Only the manager can confirm Q1 to Q6, and nothing here replaces asking her.
• It cost effort that a smaller system would not repay. For a throwaway script, none of this is warranted (chapter 1). For a service people pay money into, the checks on refunds and offers were cheap compared with one wrong refund.

Hands-On Exercises

Course Complete: What You Can Now Do

Where to go next. Design Patterns teaches the patterns this course only drew, with their trade-offs, and Clean Code, SOLID & Refactoring covers the principles behind chapters 6 and 11 and how to refactor safely. Software Architecture Fundamentals takes the structure diagrams of chapter 9 up a level (the C4 model, architecture decisions and the qualities a system must have), and The Software Development Lifecycle places requirements, design documents and reviews inside a whole project. Then take something you are building and work through the method on it. Start with the questions: that part costs the least and finds the most.