Software Architecture / Evolution: capacity, migration, validation, and review / Lesson 18

Review a complete reservation architecture proposal

Combine scenarios, ownership, contracts, failure handling, evidence, and migration into one reviewable design.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Trace one user promise through structure, data, runtime, and operations.
Produce a justified recommendation with explicit open questions and verification gates.

Begin with a concrete design brief

The fictional product needs learners to reserve workshop seats, inspect their own reservations, and receive notifications. Administrators manage capacity and cancellations. The primary invariant is no overbooking; confirmation means a durable authoritative reservation, while notification may complete later. One small team initially owns the application. Workload numbers and contractual availability targets are deliberately unspecified, so the proposal must not claim measured capacity or a service agreement. Start the review by confirming this brief and identifying missing business decisions, especially pending holds, cancellation eligibility, and retention requirements.

Choose a small structure that fits the stated problem

A reasonable candidate is a modular application with catalog, reservation, and notification responsibilities, one authoritative reservation transaction boundary, and a separate notification worker when durable delayed delivery is required. A browser calls the application over an authenticated interface. The proposal deliberately avoids splitting every module into a service before independent ownership is needed. This is a candidate to evaluate, not the one correct answer. Another design may be justified if its contract, consistency, operating costs, and migration evidence better fit the actual constraints.

yaml An integrated responsibility proposal

reservation_owner:
  writes: [active reservations, capacity allocation, request outcomes, outbox intentions]
  invariant: active allocation never exceeds configured capacity
notification_owner:
  writes: [delivery attempts, final delivery status]
  input: committed ReservationConfirmed event
query_policy:
  reservation_access: authenticated owner or explicitly authorized administrator

The record makes state and permission ownership visible. It remains a design artifact; storage isolation, identity validation, and atomicity need implementation-specific verification.

Walk through the hardest ordinary and failure cases

Trace two learners competing for the last seat, a repeated client request after a lost response, a mail provider outage, and a cancellation racing a new reservation. For each case, name the authoritative decision, durable state, caller outcome, and recovery owner. An outbox can retain notification intention, but duplicate delivery still requires a safe consumer protocol. A stale catalog can display an unavailable workshop, but the reservation owner must reject the command correctly. A private reservation query needs resource authorization even when the identifier is known.

Turn review comments into specific evidence requests

The sample review table maps a concern to a proposed check. No row is marked passed because no deployed application is provided. A useful review differentiates an unsupported assertion from a demonstrated defect and from a product question awaiting an owner. Prioritize evidence for irreversible or high-impact choices first. Avoid requesting a broad benchmark when the unresolved concern is an atomicity race, or a diagram revision when the actual issue is unclear ownership. Evidence requests should make the next engineering step smaller and more decisive.

text A review-to-evidence map

Concern: no overbooking -> isolated concurrent last-seat transaction test
Concern: uncertain response -> same-request retry returns one stored outcome
Concern: provider outage -> pending work stays durable and bounded
Concern: private query -> wrong-owner fixture is denied
Concern: future extraction -> module dependency rule and compatible contract review
Status: proposed checks, no deployment results claimed

Each check targets one claim. Actual implementation tests must record their environment, data, and limits; this document does not manufacture a pass from a planned check.

Conclude with a decision that a maintainer can act on

A review recommendation can conditionally support the modular candidate while requiring capacity enforcement, outcome identity, authorization, and notification recovery evidence before release. Record accepted tradeoffs, unresolved product rules, owners, and review triggers. Include a migration plan if replacing an existing system; a new diagram does not move historical data or retire consumers. Explain what would change the recommendation, such as separate team ownership or a demonstrated scaling bottleneck. The deliverable is a coherent argument with testable claims, not a catalog of fashionable patterns or a promise of readiness unsupported by execution.

Common errors and fixes

The proposal says reliable but names no failure states.

Why it happens: Quality language was disconnected from runtime behavior.
How to fix it: Add concrete partial-failure stories and durable outcomes.
Prevent it next time: Require a success and failure walkthrough for the core promise.

All planned checks are reported as verified.

Why it happens: Review intent was confused with execution evidence.
How to fix it: Label proposed, executed, and passed evidence separately.
Prevent it next time: Attach method and environment to every test claim.

Patterns are added without a concern they resolve.

Why it happens: Design complexity became a proxy for quality.
How to fix it: Remove or justify each mechanism through a prioritized scenario.
Prevent it next time: Review the simplest candidate that preserves the required promises.

Check your understanding

1. Write a defensible release condition for the reservation proposal.

Show worked solution

Require implementation evidence that the authoritative allocation preserves capacity under controlled concurrency, repeated request identity yields one coherent outcome, unauthorized queries are denied, and committed notification intentions survive the stated failure windows. Keep product-rule approvals and operational ownership explicit. Do not substitute these conditions for the project’s actual release process.

2. An architect demands immediate catalog microservices without new constraints. How should the review respond?