Software Architecture / Foundations: promises, structure, and ownership / Lesson 1

Architecture begins with consequential decisions

Connect a system boundary, stakeholder concern, and reversible decision using a fictional workshop-booking service.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Distinguish an architectural decision from a local implementation detail by its consequences.
Define scope, constraints, assumptions, and evidence before selecting infrastructure.

Identify decisions that are expensive to reverse

Architecture concerns the structures and decisions that shape how a system changes, runs, and fails. A framework name alone says little about those consequences. In our fictional workshop service, deciding who owns a seat reservation affects concurrency, recovery, and support; choosing a private helper name usually affects one file. Significance depends on context rather than a universal list. A decision can become architectural when many teams rely on it, when changing it requires moving data, or when its failure crosses an important trust boundary.

Describe what the system promises

Start with an observable user task: a learner requests a place and receives either a confirmed reservation or an explicit rejection. Draw the boundary around the software that owns this promise. Email delivery is a collaborator, while the learner and workshop administrator are actors. A browser can belong inside the software boundary even though it runs on another machine. Organizational ownership, execution location, and trust are separate dimensions. Naming them prevents an external payment or notification provider from quietly becoming an assumed part of your transaction.

json A bounded scope record

{"system":"Workshop Booking","owns":["seat reservations"],"external":["mail provider"],"excluded":["course delivery"]}

This valid JSON declares one owned responsibility and two explicit boundary decisions. It is a documentation artifact, not a deployment or enforcement mechanism.

Separate imposed constraints from chosen preferences

A legal retention rule, an existing identity service, and a team budget can constrain options. A developer preference for an unfamiliar broker is not automatically a constraint. Record who imposes each limitation, its rationale, and when it can be reviewed. Distinguish a fact from an assumption: the statement that workshop enrollment peaks at a certain hour needs evidence or an explicit hypothetical label. Architecture should expose uncertainty early, since a precise design built on an unverified workload can be less useful than a simpler design with a clear measurement plan.

Compare consequences against the same question

Consider a modular application and separately deployed services for the booking workflow. Both can expose an HTTP interface and use a durable database. Compare release independence, operational skill, consistency needs, and expected team coordination rather than counting boxes. The sample decision records why one option fits a small fictional team now. Its review trigger matters: if independent release ownership becomes a demonstrated need, the team can revisit the choice without pretending that the original decision was a mistake or a timeless rule.

yaml A compact decision with a review trigger

decision: keep booking in one deployable application
reason: one team owns the reservation transaction
cost: components share the release schedule
review_when: two teams need independent releases

The stated cost prevents the decision from becoming a sales pitch. The trigger describes evidence that could change the conclusion; no particular team size or deployment style is universally correct.

Turn unknowns into bounded investigations

Investigate the riskiest assumption with the smallest useful experiment. If two competing reservation requests threaten the last seat, a local transaction test is more informative than a broad platform benchmark. Define the inputs, expected invariant, observed result, and limits of the experiment. A successful local test does not prove behavior under every production failure. Keep the architecture record linked to the evidence and its environment so future reviewers can tell whether a decision remains justified after workloads, teams, or dependencies change.

Common errors and fixes

The diagram lists products but no responsibilities.

Why it happens: Technology selection replaced definition of the user promise.
How to fix it: Name the owned workflow and the consequence of each boundary.
Prevent it next time: Require a scope statement before reviewing product choices.

A preference is labeled mandatory.

Why it happens: The source and authority of the constraint were omitted.
How to fix it: Record the owner and distinguish an assumption from an imposed rule.
Prevent it next time: Review constraints when their source or context changes.

A decision has benefits but no costs.

Why it happens: The record attempts to defend a choice instead of explain it.
How to fix it: Document the rejected alternative and accepted tradeoff.
Prevent it next time: Include a review trigger and evidence link in every significant decision.

Check your understanding

1. The team proposes a queue because enrollment might grow. What evidence should precede approval?

Show worked solution

Identify the workflow that needs buffering, its acceptable completion delay, current arrival and processing rates, and how users learn the eventual outcome. Compare this with synchronous processing under the same workload assumption. If no delayed task or capacity mismatch exists, a queue may add failure states without solving a demonstrated problem. Record the uncertainty and a bounded experiment rather than manufacturing a growth forecast.

2. An external mail provider is unavailable. Does that imply the seat reservation must fail?