Architecture Foundations stage summary

Most people meet architecture as diagrams: boxes, arrows, layers, technology names. The diagrams are communication artefacts, not the architecture. The architecture is the set of decisions that shape the structure of a system and constrain what can be built on top of it, and the practical test for whether a decision belongs in that set is reversibility. If undoing the choice next quarter would mean rebuilding significant parts of the system, it is architectural. Choosing a code formatter is not. Choosing whether services share one database or own their own is.

Module 1 turns that test into three signals you can check in a meeting rather than a vague feeling of importance. Does the decision reach beyond one team or component? Would it be expensive to reverse after six months of building on top of it? Does it constrain the options open to other teams later? The module draws no scoring threshold across them, and none is needed: a decision that reaches other teams, outlives the release and is expensive to unpick once built on is architectural, and one that stays inside a component and can be changed without touching anything outside it is an implementation decision. That is why microservices or a monolith, one shared database or a database per service, and synchronous or asynchronous communication clear the threshold, and the choice of object-relational mapper, test framework or code formatter does not. Architecture, design and implementation are nested rather than synonymous: architecture fixes the major parts and how they communicate, design fixes how one component is organised internally, and implementation fixes how a particular piece of logic works. ISO/IEC/IEEE 42010:2022, the international standard for architecture description, formalises the same idea as the fundamental organisation of a system, which is a statement about how concerns are separated and how parts relate rather than about which framework was chosen. The sharper filter for which of these decisions earns a written record is Nygard's significance test, and it arrives in Module 4.

The reason this matters is that the cost of an architectural decision is not paid when it is made. It is paid every time the system has to change afterwards, which is why architectural debt compounds faster than any other kind. A naming convention can be fixed with a search and replace. A coupling that has propagated through forty modules cannot. So the working habit to take from this module is small and cheap: before any decision that clears the threshold, write down what it makes easy and what it makes hard. If you cannot answer both halves, you do not yet understand the decision well enough to make it.

Size does not make something a component. A microservice, a library, a module inside a monolith and a function in a pipeline can all be components, and what qualifies them is a set of three properties held together: one clear responsibility, an implementation that nobody outside can see, and an interface through which every interaction passes. A class named UserService that handles accounts, orders and billing fails the first property, because it has three independent reasons to change. A module named Utils fails all three, because a component with no responsibility has no owner, no interface and no reason to keep anything inside it together.

The interface is the contract, and the contract is larger than the signature. It covers the operations offered, the data types accepted and returned, the error conditions that can occur, and the behavioural constraints such as ordering and concurrency. This is the part teams get wrong most often. A function that keeps its parameters but starts returning a null where it previously raised an error has broken its contract even though nothing a type checker looks at has changed, which is why consumer-driven contract tests catch a class of break that types alone cannot. A well-designed interface is minimal, so it exposes only what callers need; stable, because every change breaks every caller; explicit about valid inputs and possible errors; and free of implementation detail, so that a method named findById survives a change of datastore that a method named getUserFromDatabase would not.

David Parnas set out the mechanism in 1972: each module should hide a design decision from the rest of the system. That is the whole point of an interface. When a decision is hidden behind one, changing it does not break anything outside, because nothing outside knew about it. So the check to run on any boundary you are about to draw is whether you can name four things about it: who owns it, what its interface is, who owns the data behind it, and what compatibility promise it makes. A line on a diagram that cannot answer those four questions is a drawing, not a boundary.

Two measures tell you whether a set of boundaries is doing any work. Cohesion asks how well the things inside one component belong together, and a component with high cohesion has a single reason to change. Coupling asks how dependent components are on one another, and low coupling means one can change without dragging the others with it. The goal is high cohesion with low coupling, and the two are related rather than independent: boundaries drawn along the right lines produce both at once, which is why arguing about them separately is usually a sign that the boundary itself is in the wrong place.

Coupling is a spectrum, not a binary, and naming the point on it is what makes a review actionable. Content coupling is the worst: one component reaches directly into another's internal state, and the standard example is one service reading and writing another service's database tables. There is no contract to protect either side, so the owning team cannot add an index, split a table or change a type without breaking a consumer it may not know about. Common coupling means shared global mutable state. Control coupling means one component passes a flag that steers another's internal branching, so the caller now has to understand the callee's logic. Data coupling, where two components exchange well-defined parameters through a declared interface, is the form to aim for.

Where the lines go is decided by four kinds of difference: different rates of change, different deployment needs, different team ownership, and different trust levels. Conway's observation from 1968 is the reason the third one is not optional; a system tends to mirror the communication structure of the organisation that built it, so two teams sharing a table with no boundary between them will argue about schema changes indefinitely. Dependency direction is the last control: when high-level policy defines the interface and low-level infrastructure implements it, the business rules can be tested with no database at all. The consequence to carry forward is that a good boundary makes the blast radius of a change predictable, and predictable blast radius is the thing you are actually buying.

Functional requirements say what a system does. Quality attributes, also called non-functional requirements, say how well it does it, and they are what constrain the design space. The user can log in is functional. Login succeeds within 200 milliseconds for 99 percent of requests is a quality attribute, and only the second one rules any architecture in or out. A system can satisfy every functional requirement and still destroy the organisation that owns it: the Knight Capital trading incident of 1 August 2012 involved a deployment that activated dormant code, and every order the system placed was executed exactly as instructed. Nothing functional failed. What was missing were reliability, safety and observability properties that nobody had specified.

The fix for vagueness is a template rather than more adjectives. The Software Engineering Institute's quality attribute scenario has six parts, and all six have to be present: the source of the stimulus, the stimulus itself, the environment the system is in at the time, the artefact affected, the response, and the response measure. The system should handle peak load names only the artefact, which is why it can be neither designed for nor tested. When 500 customers request account balances simultaneously during normal business hours, the balance API returns correct data within 150 milliseconds at the 99th percentile is the same requirement with the other five parts supplied, and it can now be failed by a load test.

ISO/IEC 25010 supplies the shared taxonomy that keeps these conversations from becoming arguments about the word quality, grouping product quality into top-level characteristics such as performance efficiency, reliability, security and maintainability, each with sub-characteristics beneath it. The standard was revised in 2023 and the revision changed the model, so cite the edition you are working from rather than a remembered list. The habit that follows is the one the figure in this section makes explicit: every stated quality requirement needs a threshold, a test or observation that can produce proof, and a signal that a release decision can actually be made on. A requirement with none of those three is a wish.

Quality attributes are not free and they pull against each other. Strong consistency competes with availability once a network partition is possible. Every authentication check and validation step buys security and spends latency. A single server is simple to operate and cannot scale horizontally. Shipping sooner costs maintainability later. None of these pairs has a correct answer in the abstract, which is exactly why they are architectural: the answer depends on measured requirements for this system, and once chosen it is expensive to revisit.

The Architecture Trade-off Analysis Method, developed at the Software Engineering Institute, is the structured version of this conversation, and its value is the vocabulary it gives you even when you never run the full method. A sensitivity point is a decision that strongly affects one quality attribute. A trade-off point is a decision that affects two or more in conflicting directions. A risk is a decision that may not support a stated requirement under some conditions. A utility tree ranks candidate scenarios by business importance and by architectural difficulty, and the scenarios that score high on both are the risks worth designing against first.

Work an example through and the mechanism becomes obvious. Adding a cache improves read latency, weakens consistency because the cached copy can be stale, adds an operational component that has to be monitored and configured, and increases cost. That is not a reason to avoid caches. It is the shape of the record you owe the next engineer: the attribute you improved, the attribute you knowingly weakened, and the measured requirement that made the exchange acceptable. An architecture where nobody can say which quality attribute was traded away has not made the trade-off; it has just absorbed it.

Most documentation describes what a system does. An Architecture Decision Record describes why it does it that way and what was rejected on the path, and that reasoning is the first thing to evaporate when a team changes. The practice was named by Michael Nygard in a 2011 post titled Documenting Architecture Decisions, and the format is deliberately short: a numbered title, a status, the context that forced a decision, the decision itself in one clear active sentence, and the consequences that follow. The Markdown Architectural Decision Records template maintained by the ADR community adds an explicit options section, which is the part practitioners most often skip and most often need.

The threshold for writing one is the same reversibility test from Module 1, applied to a specific list: write a record when the decision is hard to reverse, crosses more than one team or component, trades quality attributes against each other, carries a compliance or audit implication, or will be questioned by an engineer who does not have today's context. Do not write one for a linting tool or a date library. The useful rule of thumb is to imagine a new engineer six months from now asking why is it this way, and to write the record that answers the question before the meeting to relitigate it is booked.

The lifecycle carries a governance rule that is easy to break and expensive to break. A record moves from proposed to accepted, and may later become deprecated or superseded, but an accepted record is never edited to change its decision. When the context changes you write a new record that supersedes the old one and explains what changed, and you update only the old record's status and its pointer forward. That preserves a chain a reader can walk in 2030. It also means the record has to be written at the moment of decision: a record written six months later is a rationalisation, because the constraints, the rejected options and the team's capacity at the time are exactly what has already been forgotten.

A layered architecture organises code into horizontal tiers with defined responsibilities, commonly presentation, application services, domain and data access. The tiers are not the point. The dependency rule is: arrows run downward only, and no layer imports from a layer above it. Where a lower layer genuinely needs to notify a higher one, it does so indirectly, through an event or a callback that the higher layer subscribes to, so the import still never goes upward. Strip that rule out and you have four folders, not four layers.

What the rule buys is separation of change, independent testability and replaceability. Each layer has one reason to change, so a change to the API contract does not force a retest of business rules. A domain layer that imports nothing external can be unit tested with no database and no HTTP server, which is why domain tests in a properly layered system are fast and stable. And because the presentation layer knows nothing about persistence, either end can be replaced without touching the other. A layer violation, whether it is a lower layer importing upward or a controller reaching past the service layer straight into a repository, removes all three benefits at once. Erosion is gradual and starts with a single pragmatic shortcut, which is why teams enforce the rule with static analysis in the pipeline rather than in code review, using tools such as ArchUnit, Dependency Cruiser or NetArchTest.

Two calibrations stop this becoming dogma. Strict layering allows a layer to call only the layer immediately below it and is the right choice when the domain layer holds certified, audited or safety-critical logic that must be insulated from infrastructure change; relaxed layering allows a layer to call any layer below it and is the pragmatic choice in thin, data-entry-heavy applications. And the layer count is not sacred: a three-layer split of presentation, domain logic and data source is a complete architecture, and adding an application services layer to a system with no use-case orchestration produces boilerplate and nothing else. The failure to watch for is the anaemic domain model, named by Martin Fowler in 2003, where entities hold only getters and setters and all the rules migrate into service classes. The diagram still shows layers. The domain layer is isolating nothing, because it contains nothing to isolate.

Client-server is the shape of nearly everything on the web: a client sends a request, a server processes it and sends a response, and the cycle closes. HTTP, which governs the exchange, is stateless by design. RFC 9110, the current Internet Standard for HTTP semantics, states that each request message's semantics can be understood in isolation. That constraint is what allows any server in a pool to serve any request without session affinity, and it is also the source of a persistent confusion: sessions, cookies and tokens are stateful mechanisms built on top of a stateless protocol, so an application can be stateful while the protocol underneath it remains stateless.

A production request does not go from browser to application code in one hop, and latency is additive along the chain: name resolution, an edge cache, a load balancer at layer 4 or layer 7, the application server, and the datastore behind it. Treating that chain as one opaque call is how teams end up unable to say where time went. Each hop needs a timeout that bounds how long the caller waits, a retry budget rather than unlimited retries, and backoff with jitter so that a struggling dependency is not hit by every client at the same instant. Retries without a budget turn a slow dependency into an outage, because the load that arrives while it is recovering is larger than the load that broke it.

Synchronous request-response fits work that finishes inside a tolerable response time. Work that does not fit is acknowledged immediately and completed in the background, with the client polling a status endpoint or receiving a callback, because holding an HTTP connection open for twenty minutes loses to the first proxy timeout in the path. When the server needs to push rather than answer, three options sit at different costs: long polling needs no new infrastructure but reintroduces waiting; Server-Sent Events give native one-way streaming with automatic reconnection through the browser's EventSource interface; WebSockets give a full-duplex channel and add connection state, reconnection logic and load balancer stickiness to your operational burden. The decision rule is simple and often ignored: use WebSockets only when the client genuinely needs to send frequent messages back over the same channel.

The C4 model gives four hierarchical views, each answering a different question for a different reader. System Context shows the system as one box among its users and the external systems it depends on, carries no technology names, and is written for people who do not read architecture diagrams for a living. Container zooms inside the system boundary and shows the separately deployable and runnable things, a web application, an API, a database, a queue, each annotated with the technology it uses and each relationship labelled with the protocol and the data exchanged. Component zooms inside one container to its internal building blocks. Code is optional, and modern tooling generates it on demand, so it is very rarely worth maintaining by hand.

Most teams need only the first two, and the Container diagram is the one that repays maintenance. It is concrete enough to drive deployment and technology conversations and abstract enough to stay true while implementation details churn underneath it. The notation demands little: every element carries a name, a type and a short description, every relationship carries the intent rather than just an arrowhead, and elements outside the system boundary are visually distinguished so that the places where integration risk lives are obvious at a glance. C4 does not replace UML, because it cannot express message ordering or state transitions; a sequence diagram is still the right tool when the question is what happens when X occurs and in what order.

The failure mode is not drawing the wrong boxes, it is drawing them once. A diagram that described the system accurately eighteen months ago is worse than no diagram at all, because it produces confident wrong decisions. The teams whose diagrams stay useful treat them as generated outputs rather than hand-drawn documents, writing them in a text DSL such as Structurizr or the C4 macros for PlantUML, keeping them in version control beside the code, reviewing them in pull requests and rendering them in the pipeline. That is the consequence to act on: if a diagram cannot be regenerated by a build, assume it is already wrong.

Security that is retrofitted is consistently weaker and more expensive than security that was designed in, because the properties that matter most are structural: where the trust boundaries sit, which data crosses them, and where identity is established. The NCSC's secure design principles organise the guidance into five groups that make useful headings for a design review: establish the context, make compromise difficult, make disruption difficult, make the detection of compromise easier, and reduce the impact of compromise. The first is the one teams skip and the one everything else depends on, because a control chosen without knowing what is being protected and from whom is decoration.

STRIDE turns that into a systematic pass over a data flow. Spoofing is claiming an identity you do not have, and it is answered with strong authentication. Tampering is unauthorised modification, answered with integrity controls and parameterised queries. Repudiation is denying an action, answered with signed and timestamped audit records. Information disclosure is exposure to the wrong party, answered with access control, encryption and restraint about what goes into logs and error responses. Denial of service is answered with rate limits, circuit breakers and edge protection. Elevation of privilege is answered with server-side authorisation checks on every request and least privilege everywhere. The critical distinction the module drives at is that authentication establishes who is calling and authorisation decides what that caller may do; a system that checks the first and assumes the second is how one customer reads another customer's account by changing an identifier.

Two habits follow. First, defence in depth, meaning no single control is the only thing standing between an attacker and the data: network controls, application controls, data controls and operational detection each limit the blast radius when the layer outside them fails, and egress restrictions on application containers are the specific control that would have blunted the Log4j vulnerability published on 10 December 2021 as CVE-2021-44228, which scored 10.0 and reached organisations through transitive dependencies they did not know they had. Second, a Software Bill of Materials produced at build time, listing every component including transitive ones, so that the question which of our services contains this library has an answer within minutes of the next advisory rather than within weeks. A threat model that ends in a list of risks has not done its job; each threat should end in a control, a test and evidence a reviewer can look at.

The three terms hidden inside the abbreviation CI/CD are distinct and the distinction matters in any conversation with a change approval board. Continuous integration means changes are merged into a shared branch at least daily and tested automatically on every merge, so integration problems surface within hours rather than on a painful integration day. Continuous delivery means every build that passes is in a state where it could be deployed, with a deliberate human decision about when. Continuous deployment removes that gate, so every passing build goes to production automatically. Most regulated organisations practise continuous delivery, and a required approval gate does not stop them doing so.

A pipeline is an ordered set of stages arranged fast to slow, so that cheap checks fail early: a commit stage of unit tests, linting, type checks, static security analysis and a build, aiming to finish inside a few minutes; an integration stage with integration and contract tests and a deterministically tagged image; a security stage scanning dependencies and the built image; a staging deployment with smoke tests and a performance baseline against an environment that genuinely mirrors production; and a production deployment using a rolling, blue-green or canary strategy with health checks watching error rate and latency. Rollback has to be a button, not a fresh run of the pipeline, because a rollback that takes as long as a deployment is not a rollback.

Two practices make the rest work. Feature flags separate deployment from release, so code can ship disabled, be enabled for a small ring of users, and be switched off instantly without a redeploy; the cost is flag debt, since every live flag is another branch in production behaviour, so temporary flags need an owner and a removal date. Trunk-based development keeps batches small by integrating every change immediately and hiding unfinished work behind flags rather than in long-lived branches that accumulate integration debt for every day they stay open. The measurement frame to use is DORA's, which now publishes five metrics rather than the four many teams still quote: change lead time, deployment frequency and failed deployment recovery time on the throughput side, with change fail rate and deployment rework rate on the instability side. The counterintuitive finding these support is the one to carry into Stage 2: deploying more often makes each deployment safer, because smaller batches are easier to diagnose.