What you'll be able to do
- Distinguish a style, a pattern and a tactic, and name the coupling a design leaves in place — including the schema coupling that messaging does not remove.
- Choose an architectural style for a given set of quality-attribute priorities, using a style-ratings table, and state what the choice costs.
- Select workflow, rules and integration patterns — saga, rules engine, anti-corruption layer, transactional outbox, idempotent consumer, strangler fig — for a concrete integration problem.
- Compare mediator and broker event topologies, and design for ordering, duplicates, tracing and schema evolution.
- Plan a zero-downtime release with blue-green or canary, including its database and capacity consequences.
- Run one Attribute-Driven Design iteration: set a goal from your ASRs, refine an element, choose and instantiate a design concept, sketch the view and trace it back.
Style vs pattern vs tactic
There is no single definition and no clear separation between styles and patterns — as usual, everything depends on the usage context.
| Term | Meaning |
|---|---|
| Architectural style | The highest level of granularity in architecture. Specifies layers, high-level modules of the application, how those modules and layers interact, and the relations between them. A general direction for how you plan to build the solution — "we are going to use event-driven design" |
| Architectural pattern | Solves problems related to the architectural style, becoming more specific because it takes the context into account. For example: "what classes will we have and how will they interact in order to implement a system with a specific set of layers", or "what high-level modules will we have in our service-oriented architecture and how will they communicate", or "how many tiers will our client-server architecture have" |
| Architectural tactic | Design decisions that improve individual quality attribute concerns. Tactics implemented in existing architectures can significantly impact the architecture patterns in the system; tactics selected during initial design significantly impact which patterns are used and how they must change to accommodate the tactics |
A design solution for a concrete context and problem is an architectural pattern. A pattern includes or consists of a number of architectural tactics.
Foundational principles
| Principle | Definition |
|---|---|
| Single Responsibility (SRP) | A class or module has one job, and everything it offers serves that job; Robert C. Martin puts it as having "one reason to change". In practice SRP is high cohesion stated as a rule |
| Separation of Concerns (SoC) | Divide a program into parts that each deal with one concern — a feature, a behaviour, or a technical aspect such as persistence or security — and keep the overlap between parts as small as you can. The term goes back to Dijkstra (1974) |
| Bounded Context | The core pattern of strategic Domain-Driven Design (Evans, 2003), the part of DDD that copes with large models and many teams (see Fowler, BoundedContext, 2014). Instead of one model for everything, draw explicit boundaries inside which one model and one vocabulary hold, and state how the contexts relate. The Context Map shows every context in the application together: how they communicate and what data passes between them |
| Principle of Least Knowledge (Law of Demeter) | A unit works only with its immediate collaborators — its own fields, its parameters and the objects it creates — and does not reach through them into other components' internals ("don't talk to strangers"). Fewer hidden dependencies make the code easier to change. It is named after the Demeter project at Northeastern University in the late 1980s |
Coupling
A software unit can be any size: a method, a class, a package, a module, a service, a whole system. Coupling is how much units depend on one another. Tightly coupled units cannot change independently; loosely coupled units depend on each other only through narrow, stable interfaces; uncoupled units do not interact at all. A class with high coupling needs many other classes to do its work.
Types of coupling, strongest to weakest:
- Shared private data — each class reads or writes the other's internals. The strongest form: neither can change without checking the other
- A shared global data structure — the direct dependency moves into the global structure, but the coupling stays strong: any change to the global data touches every class that uses it
- Method parameters only — much weaker: each method receives just the data it needs, so a change stays local to the methods concerned
- Messages only — units exchange messages and nothing else. The weakest form, but still coupling: both sides must agree on the message's format and meaning
The classic scale (content, common, external, control, stamp, data, message) has more steps than this simplified list. For distributed systems, also think about temporal, location and schema coupling: asynchronous messaging removes temporal and location coupling, but not schema coupling — every consumer still depends on the shape and meaning of the events it reads.
Example: with loose coupling, a major change inside one class leaves the others alone. With tight coupling the classes are so intertwined that one change can ripple through the whole system, which is what makes such code hard to change and maintain.
The usual tool for loosening it is an interface: callers depend on an abstraction, not on a concrete implementation. If the application calls IDatabase.exportToFile(), the database behind it can move from Oracle to MySQL without touching the calling code.
A real drawback story: an application was tightly coupled with a third-party service. Performance testing — and functional testing — was painful, because when the third-party tool was down or experiencing temporary degradation it affected test results. The fix was to talk to an interface and build a stub implementing it.
Cohesion
Cohesion is how strongly the parts inside one module belong together: how closely related the functions it groups are. In a cohesive module everything serves one purpose.
Aim for high cohesion. When a module does one job, a reader can grasp it in one sitting, a change to that job lands in one place, and the module can be lifted into another system whole. Spread unrelated jobs across a module and the opposite happens: each change risks breaking a neighbour, tests must set up things the code under test never uses, and nobody wants to reuse it.
Low cohesion example: a class whose methods have nothing to do with each other — the UTIL class that has become a Swiss army knife of file export, string helpers, FTP connectivity and anything else that had no home. Split it into helpers grouped by purpose.
Cohesion is about the relationships inside a module; coupling is about the relationships between modules.
A related design axis is whether a component is stateful or stateless. A stateful component keeps state shared across several requests, which transfers less data per call but forces you to deal with synchronising concurrent requests against that shared state; a stateless component puts all the information a request needs into the request itself, trading a larger per-request payload for the ability to route any request to any instance without coordination — which is why stateless components are the easier default to scale horizontally.
Monolith
A monolithic architecture — one application built and deployed as a single unit — suits simple, lightweight applications and POC or MVP work, and serves well beyond them: it is simple to build, test and operate, in-process calls are fast, a single database gives ACID transactions, and it can still scale by cloning (the X axis of the scale cube), though not component by component. Keeping internal module boundaries enforced — a modular monolith — is the discipline that stops it decaying.
The major drawback appears when that discipline lapses: tight coupling — over time monolithic components become tightly coupled and entangled, which affects management, scalability and continuous deployment. Other cons stemming from tight coupling:
| Con | Detail |
|---|---|
| Reliability | An error in any of the modules can bring the entire application down |
| Updates | Due to a single large codebase and tight coupling, the entire application must be deployed for each update |
| Technology stack | A monolithic application must use the same technology stack throughout; changes are expensive in both time and cost |
A real drawback story: a desktop application compiled and deployed as one huge executable, used by various departments. Each deployment affected all departments, and there had to be at least core regression testing for every department's functionality after a change in even one particular place.
Layered
One of the powerful features of the layered pattern is the separation of concerns among components.
Rules and their nuances:
- Normally requests always go from up to down. A lower layer should never perform a request to upper layers
- But a lower layer may notify an upper layer, as long as its own correctness doesn't depend on the answer — typically through a callback or observer registered via an interface the lower layer owns (error reporting is one common use). The defining rule is "allowed to use", meaning "depends on for correctness", not merely "calls"
- Layers are closed by default (Richards): a request from A must pass through B to reach C. A layer can be designated open, so that A may bypass B and use C directly — but that is an explicit, documented decision, and every bypass takes away some of the benefit of isolated layers. Don't confuse this with the Open/Closed Principle (open for extension, closed for modification), which is unrelated. The opposite failure, the architecture sinkhole, is when most requests pass through layers that add no logic at all
- Any set of boxes stacked on top of each other does not constitute a layered architecture. If everyone is allowed to use everything, it is not layered
- The key provides the answer to "what allows to use what"
Onion architecture (like hexagonal and clean architecture) is a layered variant that inverts the usual direction: the domain model sits at the centre, and every dependency points inward towards it, with infrastructure such as databases and UIs on the outside.
For more depth: search for "layer bridging" in Software Architecture in Practice by Bass, Clements and Kazman, and read chapter 1 of Software Architecture Patterns by Mark Richards.
The figure below is the one the Task at the end of this module asks about. Layers A (top), B (middle), C (bottom). The plain solid arrows are allowed in a closed layering; the dashed arrow is A bypassing B, which is only allowed if B is designated an open layer; the red arrow is an upward call that expects an answer, which is not layered.
A pragmatic view: stick to the classic approach — A talks to B only, B talks to C only — as much as possible. Jumping from A to C might be needed when performance isn't good enough and you need to speed up; that can be a valid trade-off. Talking backwards from C to B is hard to justify and looks like something that could not be called layered architecture at all.
A related but distinct style is module-based architecture, which treats modularity as a first-class unit rather than a set of call-direction rules: each module declares a name and the dependencies it requires, and hides its implementation behind an explicit contract. Because plain objects, packages and JAR archives don't enforce this kind of boundary, platforms exist to let the runtime check and enforce those module contracts. OSGi goes furthest — bundles carry versions and version ranges and can be replaced and loaded independently at runtime. The Java Platform Module System (Jigsaw, since Java 9) enforces boundaries and explicit exports but deliberately leaves version selection out of scope and does not hot-swap modules.
SOA and microservices
Scope is one difference: Service-Oriented Architecture is usually enterprise scope; microservices architecture is usually application scope. The deeper difference is the attitude to sharing. SOA aims to share as much as possible: reuse of services and integrations across the enterprise is the primary goal, typically mediated by an ESB. Microservices aim to share as little as possible: each service owns its bounded context and its data, because every shared component is also a coupling point. Reuse saves duplicated effort, but shared components increase coupling and coordination cost — they do not by themselves increase scalability.
Microservice architecture is a style that structures an application as a set of independently deployable, loosely coupled services organised around business capabilities, each owned by a small team (Chris Richardson, microservices.io). Microservices are often described as a form of SOA, driven by DevOps practices and emphasising CI/CD: smaller services, smaller responsibilities, less coupling — more infrastructure mess.
Nine characteristics, from James Lewis and Martin Fowler's Microservices article (2014):
- Componentisation via services — components are good again because of low coupling, independent deployment and scalability
- Organised around business capabilities — cross-functional teams each own a business capability end to end, rather than separate UI, server-side and database teams. Per Conway's Law, the system's structure mirrors the communication structure of the organisation that builds it, so team boundaries and service boundaries are designed together
- Products not projects — treat software not as work to do and hand out to maintenance, but as a product to be developed over its lifetime — this emphasises business value for users
- Smart endpoints and dumb pipes — simple communication with no logic — no complex routing or transformation as in an ESB — plus a smart service that contains the logic inside
- Decentralised governance — each team chooses the tools and approaches that best fit its task instead of following one enterprise-wide standard, and takes responsibility for running what it builds
- Decentralised data management — each service owns its own data (database per service) instead of sharing one enterprise database. This allows polyglot persistence — using the right storage technology per service — but gives up ACID transactions across services
- Infrastructure automation — automated build, test and deployment pipelines and automated infrastructure (typically cloud) for both deployment and operations
- Design for failure — design software tolerant to failures as much as possible — monitor, restore
- Evolutionary design — promotes making changes and evolving the system, since you can touch a component with no impact on other components
A reference microservices layering:
| Layer | Contents |
|---|---|
| Consumer | Shows the different clients of the product |
| Delivery | Balances requests, caches static web content, addresses requests to the right application |
| Aggregation | Server-side UI application, and different sets of APIs for specific clients which aggregate business services |
| Service | Business services, system services, gateway and discovery services |
| API Gateway & Service Discovery | Internal components providing routing, discovery, balancing and security for the service layer |
| Business Microservices | Implement business logic and processes |
| System Services | Existing services in the customer's environment — LDAP, printing service, email server, time service |
| Platform Services | Provide support for security and microservices management |
| Infrastructure | Provides virtual infrastructure for the platform |
A microservice is one service in such an architecture: independently deployable, owning its own data, and collaborating with others only through published interfaces.
Challenges and drawbacks. It can be very hard for a small company to maintain the whole lifecycle, because it requires extra methods and tools to support the development process — you need DevOps tools such as CI/CD servers, configuration management platforms, APM tools to monitor application performance, and distributed tracing to follow a request across services. An additional drawback is performance: sending messages back and forth between microservices comes with a certain overhead. The most challenging part is finding how to partition the solution; the usual starting point is to draw service boundaries along DDD bounded contexts (or business capabilities), so each service owns one coherent model. Orchestrating numerous development teams is also more difficult.
Event-driven architecture
(This section follows Mark Richards, Software Architecture Patterns, O'Reilly, 2015.)
In an event-driven architecture the work is done by small components that each do one thing. A component receives an event, processes it on its own schedule, and often emits further events for others to pick up. Nobody waits on a direct reply, so the style is distributed and asynchronous by nature. It suits a small application as well as a large one, and its main attraction is scale.
Reach for it when decoupling and asynchrony are what the drivers ask for. Components that share no call path can each be scaled on their own, which is why the style fits cloud applications that scale horizontally and must keep running when parts of them fail.
It is rarely the whole system. More often one sub-system or component is event-driven inside an otherwise different style.
Mediator topology — a central mediator orchestrates events that need several steps, in a set order, to complete.
It has four kinds of component: event queues, an event mediator, event channels and event processors. A client places an event on an event queue, and the queue delivers it to the mediator. The mediator turns that initial event into one processing event per step and publishes each, asynchronously, to an event channel. Event processors subscribe to the channels, pick up those processing events and run the business logic for their step.
- The event mediator knows which steps the initial event needs, and drives them in order
- Event channels — message queues or topics — carry each step's processing event from the mediator to the processors, asynchronously
- Event processors hold the business logic: each one does the work of one step
There are several ways to build the mediator, and the right one depends on the process it has to run. Richards' range runs from hand-written code, through an integration framework such as Apache Camel or Spring Integration for short flows with simple error handling, to a workflow (BPM) engine for long-running processes with human steps, timers and compensation.
Broker topology — has no central mediator. A lightweight message broker (for example RabbitMQ, ActiveMQ Artemis, or a managed cloud broker) carries events along a chain: each processor handles an event, then publishes a new event announcing what it has just done, and the next processors in the chain pick that up. Use it when the flow is fairly simple and needs no central orchestration. The broker's channels can be queues, topics or a mix of both.
Related: the actor model (Carl Hewitt, 1973) is another event-based approach, in which every unit of computation is an actor. When an actor receives a message it can send messages to other actors, create new actors and decide how it will handle its next message, and these reactions follow no fixed order. A sender needs only an actor's address, not where it runs or whether it has been restarted, so actors communicate asynchronously and keep their state private: no shared memory, no locks. Actor frameworks such as Akka, Erlang/OTP and Orleans build highly concurrent systems on that idea.
Mediator or broker
The two topologies are the event-level form of a wider choice: orchestration (a conductor directs every step) or choreography (each participant reacts to what the others did). The comparison follows Richards & Ford, Fundamentals of Software Architecture.
| Mediator (orchestration) | Broker (choreography) | |
|---|---|---|
| Who knows the whole process | The mediator holds the sequence of steps | Nobody — each processor reacts to an event and announces what it did |
| Control and error handling | Strong: the mediator sees each step, so it can retry, time out, compensate and report the state of any instance | Weak: a failure has to be announced as another event, and no component can say where an instance has got to |
| Coupling | Processors are independent of each other but all depend on the mediator, which changes whenever the process does | Lowest: a new consumer subscribes without any producer changing |
| Throughput and scalability | The mediator is on every path, so it must scale and stay available itself | Highest: no central component to saturate |
| Changing the process | Change one definition | The change is spread across several processors |
| Fits | Multi-step processes with a defined outcome, ordering and compensation | Simple fan-out reactions — notify, index, audit |
Choose the mediator when the process and its failure handling matter more than raw throughput; choose the broker when decoupling and scale matter more and the flow is simple. Many systems use both: an orchestrated core process that emits events which choreographed consumers react to.
Event-driven trade-offs
Martin Fowler separates four things people mean by "event-driven" — event notification, event-carried state transfer, event sourcing and CQRS (What do you mean by "Event-Driven"?, 2017). Whichever you use, the asynchronous hand-off brings the same costs:
- Ordering. Most brokers guarantee order only within one partition or queue, not across the system. If a cancellation can overtake the booking it cancels, key events by the entity (all events for one referral on one partition), or carry a version number and let consumers discard anything older than what they hold.
- Duplicates. At-least-once delivery is the practical default, so every message can arrive twice. Consumers must be idempotent (see Idempotent consumers below).
- Tracing. No call stack spans an event chain. Propagate a correlation ID in every event — the W3C Trace Context headers that OpenTelemetry uses — or nobody can answer "what happened to referral X?".
- Schema evolution. An event is a public contract with consumers you may not know about. Make changes additive (new optional fields), version breaking ones, and check compatibility in the build with a schema registry or consumer contract tests.
- Testability. Asynchronous flows are not deterministic: a test cannot assert on a return value, it has to wait for an outcome. Test each processor in isolation against recorded events, and keep the end-to-end tests few.
Choosing a style
No style is best in general; each buys some quality attributes by spending others. The table rates the styles in this module against the attributes that most often decide the choice. Its layout is after Richards & Ford, Fundamentals of Software Architecture, who rate more styles against more characteristics; the ratings themselves are this course's judgement, so argue with them.
Two rows need a definition first. A modular monolith is one deployable whose code is split into domain modules with enforced boundaries (see Monolith above). Service-based architecture, Richards & Ford's term, deploys a handful of coarse-grained domain services — typically four to twelve — that usually share one database: a pragmatic middle ground between a monolith and microservices.
| Style | Deployability | Scalability | Fault tolerance | Simplicity and cost | Testability | Evolvability |
|---|---|---|---|---|---|---|
| Layered (one deployable) | Low | Low | Low | High | Medium | Low |
| Modular monolith | Low | Low | Low | High | High | Medium |
| Service-based | Medium | Medium | Medium | Medium | Medium | Medium |
| Event-driven | Medium | High | High | Low | Low | High |
| Microservices | High | High | High | Low | Medium | High |
How to use it:
- Start from the utility tree, not from the style you would like. Take your top two or three quality attributes, find the styles rated High on them, then read what those styles cost in the other columns.
- Low is relative, not inadequate. A monolith scales only by cloning the whole application, with one database as the ceiling. For Lumen-sized load — 14,000 referrals a day × 12% = 1,680 in the busiest hour, under 0.5 a second, and roughly 1,650 concurrent sessions (Module 3, QA06) — that ceiling is a long way off. At this size, scalability alone rarely justifies distribution.
- Fault tolerance in microservices is earned, not given. A chain of synchronous calls multiplies availabilities down (availability mathematics); the High rating assumes circuit breakers, bulkheads and asynchronous hand-offs.
- Styles combine. Most systems have one dominant style and a sub-system or two in another. Rate each sub-system against its own drivers, not the system's average.
REST and the Richardson Maturity Model
Leonard Richardson's maturity model, popularised by Martin Fowler, grades how fully an HTTP API uses the web's own mechanisms. It starts three levels below hypermedia: Level 0 (the "Swamp of POX") uses HTTP purely as a transport for RPC-style calls against a single endpoint, with no real use of the protocol; Level 1 introduces individual resources, each with its own URI, in place of that one endpoint; and Level 2 adds proper use of HTTP verbs and status codes (GET, POST, PUT, DELETE) to operate on those resources. Only once all three are in place does level 3 add hypermedia controls on top.
Level 3 of the model is hypermedia controls. It is worth reaching when the client doesn't know the full REST API specification, or when the client's behaviour depends on internal logic implemented inside the REST service.
Example: when a client GETs an account balance it also receives a list of possible actions as links. Per the service's internal logic, when the balance is negative the only available action is "deposit money"; otherwise deposit, withdraw and close are offered. The client may also change UI elements accordingly, disabling or hiding buttons.
Cacheability and layering are REST constraints you can already exploit at Level 2 — safe, cacheable GETs work through standard HTTP caches and intermediaries without any hypermedia. What Level 3 adds is evolvability and discoverability: by including links within a response, hypermedia APIs tell clients what capabilities are possible and in what scenarios, so the server can change workflows and URLs without breaking clients. Hypermedia links can immediately reflect new user permissions without breaking changes on the client side. In practice most production APIs stop at Level 2, described by an OpenAPI contract; Level 3 pays off mainly for long-lived, generic or third-party clients.
CQRS
(CQRS, event sourcing and sharding: after Microsoft's Azure Architecture Center, Cloud design patterns. The explanations and the Lumen judgements are this course's.)
Command Query Responsibility Segregation splits the model that changes data from the model that reads it. Commands change state and enforce the business rules; queries return data shaped for a screen and change nothing. Once the two are apart, each side can have its own schema, its own store and its own scaling. The term is Greg Young's; it extends Bertrand Meyer's Command-Query Separation (CQS), which makes the same split for individual methods.
Why one model struggles. A plain CRUD design serves every screen and every update from the same model, and the compromise shows in three places:
- Shape. Screens want wide, joined, denormalised views; updates want normalised records that protect invariants. One model does both badly: queries pay for joins, and every update carries fields the operation does not touch but must still keep correct.
- Contention. Where many people work on the same records at once, reads and writes compete for the same rows. Pessimistic locks make users wait; optimistic locking rejects their updates. Both get worse as traffic and the domain grow, and heavy queries load the same store and data-access code the writes depend on.
- Permissions. When one entity is exposed for both reading and writing, it is harder to reason about who may see which fields, and easier to return data in a context that should not have it.
Where it pays.
- Very uneven read and write volumes. Each side scales on its own. A feed read thousands of times for every post is the textbook case.
- Different optimisations on each side. Even at similar volumes, writes can go to a normalised store tuned for fast transactions, while projections maintain denormalised read models — a search index, one document per screen — that answer without joins.
- Lumen's availability search (F01). Module 3 already concluded that the transactional store cannot serve this search at acceptable latency. The write side is slot uploads, the API partner's availability, holds and bookings. The read side is search by modality, urgency, location and price: about 6,720 searches in the busiest hour against 1,680 referrals, on the course's shared assumption of four searches per referral. Project slots into a search read model, and keep holds and bookings on the write side.
What it costs.
- Staleness the user acts on. Separate stores add moving parts and, when the read side is updated asynchronously, eventual consistency: a query can show something the write side has already changed, and the user then acts on it. Make every command re-check against the write model and fail cleanly. At Lumen a slot shown as free may have been taken a second earlier, so the hold command validates the slot and returns "no longer available" with fresh results instead of trusting the index. The read model is a hint; the write model decides.
- Consistency is a design choice. Read models kept in the same store and updated in the same transaction as the write stay strongly consistent. Separate read stores updated asynchronously — the usual arrangement, because it scales and lets the read side expose only the fields queries need — are eventually consistent. Say which you have, and state the lag you will tolerate as a requirement you monitor.
- Scope. Use CQRS where reads and writes genuinely diverge, such as Lumen's availability search, not across the whole system. For configuration screens or partner profiles one model is simpler and loses nothing. Applied system-wide, CQRS adds complexity with no matching benefit, and it is not trivial to build well.
- Event sourcing is a common partner, not a requirement. The write side can store events and build its read models from them (next section). Lumen's search read model can just as well be fed from the outbox events described under Transactional outbox and change data capture, over a conventional write store.
Event sourcing
Event sourcing records each change to an entity as an event appended to a log, instead of overwriting the entity's current state. The current state is whatever you get by replaying its events in order, so the record of how it got there is never lost.
How it works. An event is a small, immutable record of something that happened: what changed, with the data needed to describe it. It is appended and never edited, and appending it updates no other table. Handlers react afterwards, often in the background, so the screen or process that raised the event can carry on without waiting for them. Because nothing is updated in place, writers do not queue for row locks, which helps throughput and keeps the user-facing path short.
Appending does not remove the need for rules. The entity must still refuse a command that would leave it inconsistent, and when two writers append to the same stream, an expected-version check makes the second one reload and retry. Conflicts become rare and explicit instead of silent.
What you gain.
- Data in the domain's language. "Referral amended by patient" or "booking reassigned to partner" means something to the Scheduling Manager. A row of current-state columns does not: it is a technical snapshot of the present, with the story of how it got there thrown away.
- History by construction. The log is an audit trail of every change. Any projection — a new report, a repaired read model — can be rebuilt by replaying it, and a bug can be reproduced by replaying the events that caused it. A mistake is undone by appending a compensating event, so the reversal itself stays on record, where an update in place would have erased it. The same log feeds analysis of how the system and its users behave.
- Reactions decoupled from causes. Handlers subscribe to event types and know nothing about the command that raised them. Several can react to one event, and a new system integrates by subscribing. Domain events are usually too fine-grained for outside consumers, though: publish coarser integration events for them, so your internal model does not become their contract.
When to choose it.
- The reason for a change matters as much as the result. "Rescheduled at the patient's request" and "rescheduled because the centre closed" leave the same appointment time but mean different things for reporting and for QA15.
- Conflicting updates to the same data must be rare or impossible.
- You need to rebuild or correct state by replay: undo a run of bad changes and re-apply the good ones, or show what a record looked like on a given date.
- Accepting a change should be decoupled from processing it, to keep the user interface fast or to let other systems listen.
- Read models are expected to change, so being able to regenerate them is worth having. This usually means pairing with CQRS, where the read side may lag the write side and rebuilding an entity from its stream is fast enough; periodic snapshots keep rebuilds fast as streams grow.
- Events are already how the domain works, so modelling them costs little extra.
What it costs. Most domains only ever ask for current state, and there event sourcing is complexity for nothing. Event schemas are permanent: every past event must stay readable, so versioning never ends. And an immutable log collides with deletion. Personal data written into events cannot simply be erased when a rule such as the GDPR's right to erasure requires it, so keep personal data out of events, or encrypt it per person and destroy that person's key (crypto-shredding — see Module 10 for the key design). Which obligations apply — including health-record retention, which can pull the other way — depends on the actual jurisdictions.
For Lumen, the referral and booking lifecycle is the only serious candidate. F07 merges extract changes with in-platform amendments, and being able to show, and replay, who changed what has real value in a dispute. Two cautions. QA13 audits reads of patient data as well as changes, and an event log records only changes, so it does not satisfy QA13 on its own. And a status-history table written in the same transaction as each change, published through the outbox, gives most of the history for a fraction of the cost. Treat event sourcing as an option for the booking aggregate if replay is a firm requirement and the team has built one before, not as the default.
Sharding strategies
Sharding divides one logical data store horizontally. Each shard holds a subset of the rows, and a shard key on each row decides which shard it belongs to. The strategy is the rule that turns a key into a shard:
- Lookup (or directory): a small map records which shard holds each key, or each group of keys.
- Range: each shard owns a contiguous band of key values, such as surnames A–F or one month of dates.
- Hash: the shard is computed from a hash of the key, so no map is needed.
| Strategy | Strengths | Weaknesses |
|---|---|---|
| Lookup | The most control: any key or tenant can be placed on any shard, and moved. Map keys to virtual shards and virtual shards to physical stores, and rebalancing becomes an edit to the map — new stores take over some virtual shards — with no change to application code, which only ever sees the shard key | Every request pays for a lookup, so cache the map. The map must itself stay available and consistent, or it becomes the single point of failure |
| Range | Simple to build. Range queries are cheap, because neighbouring keys sit together, often on one shard and in one call. Operations can follow the ranges: if a shard holds one region, its maintenance and batch work can be scheduled for that region's quiet hours | Load is rarely even. Keys that only grow — dates, sequence numbers — send every new write to the last shard. Splitting a busy range later is hard, and does not help when the activity is concentrated on adjacent keys |
| Hash | The best chance of an even spread of data and load, and routing is a function call, with no map to maintain | Range queries must visit every shard, and the hash adds a small cost to each request. Rebalancing is hard: with a plain modulo, adding a shard moves most keys. Consistent hashing, or a fixed set of hash buckets assigned to shards, limits how many move |
For Lumen, volume is not the reason to shard. 6.5M live records and under 0.5 referrals a second sit comfortably in one well-sized database per region. The reason to partition is QA05 — patient data stays in the jurisdiction where it was collected — together with QA16, a new region by configuration. That is a lookup strategy keyed by region: a directory maps each region to the store in its jurisdiction, and because the directory holds no patient data it can sit in the global layer. A new region is then a new directory entry plus a store built from the template. Hash would scatter patients across jurisdictions, and no key range lines up with them. The cost falls on cross-region queries: group-wide partner-performance reporting runs in each region and combines the results, and whether even aggregated results may leave a jurisdiction is a question to put to Lumen.
Fault tolerance patterns
Fault-tolerance patterns exist for every stage of handling an error — detecting it, containing it, recovering from it — and this module reviews a few. (Redundancy, heartbeat and the leaky bucket counter: after Robert Hanmer, Patterns for Fault Tolerant Software, 2007. Bulkhead and circuit breaker: after Michael Nygard's stability patterns in Release It!, 2007, 2nd ed. 2018, and Microsoft's Azure Architecture Center, Cloud design patterns.)
Three types of redundancy
| Type | Description |
|---|---|
| Spatial | The system has multiple copies in different places that are redundant, providing alternatives selectable with minimal unavailability. Easy to understand and visualise in terms of hardware — multiple copies of the hardware platform |
| Temporal | Redundancy that occurs over time, which helps achieve correct results but lengthens the time of unavailability. Recovery Blocks provide temporal software redundancy: a program consists of a primary block and secondary blocks; if the primary's result fails its acceptance test, the secondary blocks execute in sequence until a result passes. Recovery blocks offer primarily temporal redundancy because they execute sequentially |
| Informational | When information is repeated it can aid detection and correction. The canonical examples are parity bits, checksums and error-correcting codes (ECC), which add redundant information so corruption can be detected or corrected. It can also be provided by having multiple versions of the same data available, stored in different places on different types of storage — for example disk and flash memory |
Spatial redundancy methods
| Method | Description |
|---|---|
| Active-Active | Provides totally redundant units of mitigation for the critical functionality. At any given time both elements are active and load sharing, and either is capable of processing the entire load. Provides the fastest recovery, but has a high cost because there is much more capability in the system than the ordinary workload needs. Implies a pairing between the two active units |
| Active-Standby | The standby is again paired with an active element, but the standby element is not performing useful work. This means the same amount of resources is needed as in active-active, but during normal operation the standby is idle |
| N+M | Where a one-to-one relationship is too expensive: N active elements process the workload and M redundant standby elements are ready to assume control when a failure occurs in any of the N |
The choice of redundancy regime has great effect on switching speed. If the redundant elements are hot standbys, switchover occurs very quickly with minimal outage of the main application. If the standby is only warm, it requires time to return to the same application state — checkpoints help get there more quickly. When the standby is cold, it must be started from an inactive state, which adds time; after starting it can be treated as a warm standby.
Related techniques worth looking up: voting algorithms and triple modular redundancy.
Bulkhead
A ship's hull is divided into watertight compartments, so a breach floods one compartment and not the ship. A bulkhead does the same with resources: each dependency, or each class of consumer, gets its own pool — threads, connections, queue consumers, even separate service instances. When one dependency hangs, the calls waiting on it exhaust only their own pool, and everything else keeps working.
Use it when:
- the application calls several back ends and can still do useful work while one of them is down — partial service beats none;
- some consumers matter more than others and must not be starved by the rest;
- a slow dependency could otherwise tie up shared threads or connections and turn one failure into a cascade.
What it costs. Partitioned pools use capacity less efficiently than one shared pool: what is reserved for a quiet dependency sits idle while another queues. Each pool is also one more thing to size, configure and watch. If neither partial service nor a cascade is a real risk, the extra complexity buys nothing.
For Lumen, the one automated partner API (F02) is the obvious compartment: a third party with its own failure and latency behaviour, carrying about 15% of partner bookings. Its calls get their own connection pool and worker queue, sized for that traffic, so a hanging partner API fills only its own queue while search, the desk's bookings with the other ~600 partners and patient confirmations carry on. Module 3 keeps that API off the synchronous booking path; the bulkhead is what keeps the decision true under load. A second compartment is QA15's burst of about 160 re-offers after a centre closes: run it in its own worker pool, so it cannot starve the desk's interactive searches (QA02).
Circuit breaker
Repeating a call that is going to fail wastes the caller's threads and time, and piles load on a service that is already struggling. A circuit breaker wraps a remote call, like a proxy, and watches its outcomes: errors and timeouts. While failures stay under a threshold it is closed and lets calls through. Once the threshold is crossed it opens: calls fail at once, without reaching the remote service, so the caller can degrade gracefully instead of waiting for the fault to clear — fail fast. After a cooling-off period it turns half-open and lets a trial call through; success closes it again, failure reopens it. That last step is how the breaker notices recovery without anyone resetting it.
Use it on calls to a remote service or shared resource that may fail for longer than a retry can ride out — an outage, not a dropped packet. It complements retry rather than replacing it: a short retry with backoff absorbs transient faults, and the breaker stops the retrying once the fault looks lasting. It adds nothing to in-process calls or local resources, where a failure is better handled directly. Decide what the caller does while the breaker is open — serve cached data, queue the request or return a clear error — and alert on state changes, because an open breaker is an outage someone needs to know about.
For Lumen, put a breaker on the partner API calls inside the bulkhead above. While it is open, bookings for that partner group drop to the manual path the desk already uses for the other ~600 partners: slower and dearer in desk time, but the booking still happens.
Two further fault-tolerance patterns are worth knowing by name. The Heartbeat pattern has a monitored component (or its monitor) emit a signal at regular intervals so failures are detected within a bounded time — the interval is a trade-off between faster detection and the monitoring overhead it adds. The Leaky Bucket Counter tracks how often a given error recurs over a decaying window — the bucket fills on each occurrence and drains at a steady rate — so occasional, transient errors are tolerated while an error rate that keeps exceeding the bucket's capacity is treated as permanent.
Security patterns
Three patterns recur in cloud designs: federated identity, gatekeeper and valet key (after Microsoft's Azure Architecture Center, Cloud design patterns). They are building blocks, not an architecture: Module 10 assembles them, with the other controls, into the full security and privacy architecture for Lumen's health data.
Federated identity
With federated identity the application neither stores passwords nor authenticates users itself. It trusts an external identity provider (IdP), which authenticates the user and issues a signed token of claims — who the user is, and often their groups or roles. The application verifies the signature and acts on the claims. The usual protocols are OpenID Connect, an identity layer on OAuth 2.0, and SAML 2.0, still common in enterprise single sign-on.
What it fixes. When every application keeps its own credentials:
- users juggle many passwords, forget them and reuse them;
- leavers keep access, because each application's account has to be removed separately and in a large organisation some are missed — with federation, disabling the one directory account closes them all;
- administration multiplies: provisioning, resets and reminders for every application.
Where it fits.
- Workforce single sign-on. Employees sign in once to the corporate directory and reach cloud applications outside the corporate network without signing in again, just as they reach applications on the internal network.
- Partner organisations. Users from another organisation sign in through their own IdP and need no account in yours. Partner portals are the usual case, and so is a merger that leaves two directories running.
- Multi-tenant SaaS. Each tenant brings its own IdP: its staff sign in with their corporate identity, its customers with a consumer or social one.
Where it does not pay. If one directory already covers every user — a line-of-business application on the corporate directory, reached on the internal network, over a VPN or through a private link — a second trust relationship adds a moving part for nothing. And retrofitting claims-based sign-in into an application built around its own user store, or one that cannot speak the token protocols, usually costs more than it saves.
For Lumen, F06 names two identity populations, and they should stay two. Staff — desk, managers, centre staff — federate to Lumen's corporate SSO: a workforce identity, with joiners, movers and leavers handled at the source. Patients come through the patient identity service: a consumer identity with a different assurance level, recovery process and lifecycle. The platform trusts both IdPs, maps each to its own roles, and never lets a token from one population open the other's surfaces. Partner users fit neither, which is the clarification Module 3 raised. Assume few of the ~600 practices run an IdP the platform could federate with: platform-managed partner accounts with multi-factor authentication are then the default, with federation offered to partner groups that have their own IdP.
Gatekeeper
A gatekeeper is a separate, internet-facing layer that every request passes through. It checks and cleans each request — authentication, size, format, malformed or hostile input — and forwards only what passes to the trusted services behind it, which hold the credentials and the data and cannot be reached from outside. In current designs an API gateway, a web application firewall, or both, usually play the role.
| Benefit | Why |
|---|---|
| One place for validation | Every request meets the same checks before any application code runs, and anything that fails is rejected at the edge |
| Nothing worth stealing | The gatekeeper holds no keys or credentials for storage or back-end services — only the trusted hosts behind it do — so an attacker who takes it over finds no secrets there |
| Least privilege | It runs with only the rights it needs to inspect and forward. It cannot reach data or services directly, so compromising it is not the same as compromising the application |
Use it for applications that handle sensitive data, must withstand attack, or run operations that must not be interrupted; and in distributed systems where validation should be kept apart from business logic, or held in one place so that it is easier to maintain. The costs are an extra network hop and a component everything depends on: it must scale and stay available, and it should validate and forward, not grow business logic of its own.
For Lumen, the Patient, Partner and Administration portals all sit behind it. It is the natural place to enforce TLS 1.3 on every external connection (QA09) and to reject malformed requests — but it cannot enforce QA12. Whether booking 123 belongs to the partner asking for it is known only to the service that owns bookings, so partner isolation stays in the API and data layer, where Module 3 put it.
Valet key
The name comes from the restricted key you hand a car-park valet. A valet key is a short-lived token or signed URL that lets a client read or write one specific object in a store directly — an Amazon S3 presigned URL, an Azure shared access signature or a Google Cloud Storage signed URL. The application decides whether the client may have one, issues it with a narrow scope — one object, one operation, a few minutes — and then steps out of the data path: the bytes move between client and store without passing through the application's servers.
Why use it.
- Scale and performance. Issuing a key is a local signing step, so the application leaves the transfer path and stops being its bottleneck; the gain grows with file size and concurrency.
- Cost. Direct transfers need fewer round trips and less application compute. When the store sits in another data centre or region, routing the bytes through the application can also mean paying for the same bandwidth twice.
Where it falls short.
- The application must handle the data first — to validate it, transform it or log the access. A store and a client can sometimes manage simple steps between them, such as compression, which browsers handle; otherwise, process afterwards: land uploads in a quarantine area and validate them on the store's object-created event before anything uses them.
- Audit and quotas. If every transfer must be recorded or counted, the server needs to know it happened, and a key mechanism with no notifications or access log cannot tell it.
- Size limits. Some stores let you put a size range in the key itself — an S3 presigned POST policy can set a content-length range. Otherwise you can only check after the upload, straight away or in a scheduled sweep.
- Retrofit cost. An existing design that streams data through the application may need a different approach to sending and receiving data before valet keys fit.
- Leaks. A leaked key works until it expires, so keep its scope narrow and its lifetime short.
For Lumen, partner uploads of slots, prices and capabilities (F03) are a fit — not for bandwidth, since slot lists are likely to be small files, but to keep file handling off the portal servers. Issue a key that can write one object under the uploading partner's own prefix for a few minutes; the key then cannot write into another partner's area (QA12). Land the file in quarantine, validate it, and only then import it into the canonical availability model. Patients' printable confirmations are the opposite case: they contain health information, and QA13 requires every read to be audited. The platform knows it issued a key, not that the file was read, so either join the store's object-level audit events (for S3, CloudTrail data events) back to the user each key was issued to, or serve those files through the application.
Zero-downtime deployment
It is essential to be able to roll back a deployment in case it goes wrong.
— Jez Humble and David Farley, Continuous Delivery (2010)
Diagnosing a failed release in production, under pressure, produces late nights, more mistakes and angry users. The better order is to restore service first, by rolling back, and find the cause afterwards in working hours. This section follows Humble and Farley's treatment of deployment and rollback. Of the rollback techniques they describe, the two advanced ones — blue-green deployment and canary releasing — also give you releases and rollbacks with no downtime.
Blue-green deployment. You keep two production environments, as close to identical as you can make them, called blue and green; at any moment only one of them — say green — serves users. They need not be separate hardware: separate virtual machines, on shared or separate hosts, will do, and so will one environment split into two zones with their own IP addresses.
The mechanics: deploy the new release to the idle environment (blue), and smoke-test it there while no users are routed to it. Then switch the router — load balancer, gateway or DNS (with DNS, allow for TTLs and clients that cache beyond them) — so new traffic goes to blue, letting in-flight requests on green drain; green stays running, and rollback is switching back, which takes seconds as long as nothing has changed underneath. The catch is the database, which both environments usually share: every schema change must work with the old and new versions at once, so it is made in expand/contract steps (add the new column or table first, migrate, and drop the old one only in a later release), and a destructive migration removes the switch-back. The other cost is duplicate capacity: for the switch to be instant the idle environment must carry full production load, which doubles the compute you pay for during each release — or permanently, if you keep it hot.
Canary release. Teams normally assume a single version of their software in production. Canary releasing drops that assumption to answer a question a test environment cannot: will the new version perform under real load? A production estate large enough to matter can rarely be reproduced for capacity testing — unless the architecture is sharded end to end — so the realistic capacity test is production itself, a slice at a time.
It starts the way blue-green does: deploy the new version to servers that receive no user traffic, and smoke-test it there, adding a load test if you want one. Then route a small group of users to it — the canary — and widen the group as confidence grows.
There are several ways to pick the group. The simplest is a random sample; many companies go to their own staff first; a finer approach selects users by profile or demographics. Taken further, several versions can run in production at once, each serving a different group of users.
Benefits:
- Rollback is cheap: stop routing users to the bad version, then investigate
- The same routing supports A/B testing, with some users on the new version and some on the old
- Capacity is checked in production: raise the share of users step by step while watching response times and resource metrics such as CPU, I/O and memory
Constraints:
- It fits server-side software best. Where users install your software on their own computers or phones you control less of the rollout, though app stores now offer phased rollouts to a percentage of users, which serve a similar purpose
- Every shared resource — database schema, caches, message formats — must work with every version in production at the same time
- Each extra version in production adds support cost, so keep the number of canaries small
If your goal is zero downtime and your application has low automated test coverage, a canary release is the safer way to ship — but it limits the blast radius of untested defects; it does not replace the tests. The first users exposed are real users (for Lumen, real patients), so you still need monitoring and fast rollback — and the missing tests remain a debt to pay.
Integration
Gregor Hohpe and Bobby Woolf's Enterprise Integration Patterns (2003) is the "bible" of the integration patterns — a must read. Concepts from the book are widely used in modern platforms, frameworks and tools.
Underneath that single reference sit four distinct integration styles — File Transfer, Shared Database, Remote Procedure Invocation, and Messaging — trading off coupling, latency and platform independence differently; messaging is the style most of the book's patterns assume. Individual patterns worth naming include the Messaging Gateway (encapsulates access to the messaging system behind a domain-specific API so the rest of the application never talks to the broker directly), Guaranteed Delivery (persists a message on both sender and receiver so it survives a broker crash), and the Aggregator (a stateful filter that collects a set of related messages and republishes them as one combined message once the set is complete).
Frameworks that implement these patterns directly include Apache Camel and Spring Integration on the JVM; in .NET, MassTransit and NServiceBus cover the messaging subset, sagas included.
Workflow, rules and integration patterns
The styles above set the overall shape. The hardest requirements in the Lumen case sit one level down: a booking workflow that must change after go-live (Module 3's F04), prioritisation rules the Scheduling Manager edits without a release (F08, QA10), one partner on an API next to ~600 partners working by hand (F02, F03), and a referral system that publishes only a change extract every 15 minutes, whose changes must be merged with amendments made in the platform (QA11, F07). These are the patterns usually reached for; each subsection says which requirement it bears on.
Workflow engine, process manager and saga
A workflow engine runs a process definition held as data — states, transitions, timers, human tasks — so changing the process means deploying a new definition, not new code; BPMN engines such as Camunda or Flowable are one family. Hohpe & Woolf's process manager is the same idea at message level: a component that keeps the state of each process instance and decides its next step. A saga (Garcia-Molina & Salem, 1987; applied to microservices by Chris Richardson) replaces one distributed transaction with a sequence of local transactions, each paired with a compensating action that undoes it if a later step fails. A saga is either orchestrated by a process manager (the mediator topology) or choreographed through events (the broker topology). Lumen's Requested → … → Billed lifecycle is a long-running workflow with timers (an offer that expires); its booking steps — hold the slot, book with the partner, confirm — form a saga whose compensation is releasing the slot; F04 asks that it change after go-live, which is the case for keeping it out of code.
Rules engine
A rules engine evaluates business rules held as data — decision tables, scoring criteria — against the facts of a case, so the people who own a policy can change it without a release. DMN (Decision Model and Notation, from the OMG) is the standard notation for decision tables. Lumen's prioritisation "on clinical match plus custom rules", which "may change over time" (F08), is a decision table: modality, urgency, distance and price in; a ranked list of slots out. QA10 — a policy change live within one working day, without code — then needs rule versions with effective dates, a way to replay sample referrals against a draft rule set before activating it, and an audit of who changed what. The trade-off: rules are logic written by non-developers, so they need the same testing and change control as code, and an engine is overkill for five rules that never change.
Anti-corruption layer and canonical data model
An anti-corruption layer (Evans, Domain-Driven Design) is a translation boundary that keeps a foreign model out of yours: one adapter calls the external system and maps its codes, slots and errors into your terms, and nothing beyond the adapter knows the other side's vocabulary. A canonical data model (Hohpe & Woolf) is the one internal representation every channel translates to, so each source and each consumer needs one translator, rather than one for every pair. For F02 and F03 that means one canonical partner-availability model (slot, modality, capability, price, validity): the ~600 manual partners write it through the upload screens, and the API partner reaches it only through its anti-corruption layer. Search (F01) then sees a single model, and doubling the number of partners adds rows, not code. Keep the canonical model small — one that tries to describe the whole enterprise becomes the coupling it was meant to remove.
Transactional outbox and change data capture
A service that must update its database and publish an event cannot do both atomically, so a crash between the two loses one of them — the dual-write problem. The transactional outbox writes the event to an outbox table in the same local transaction as the state change, and a relay publishes from the table at least once (Richardson, microservices.io). Change data capture (CDC) is the usual way to build the relay — Debezium, a common open-source tool, reads the outbox table from the transaction log; pointed at business tables instead, it publishes raw row changes and exposes your internal schema to every consumer. For QA11 there are two directions. Inbound, the referral system has no events, only an extract every 15 minutes (96 runs a day), so the platform must compare each extract with what it holds and raise its own change events. That comparison is where F07's conflict policy runs: an amendment made in the platform since the last extract is merged by rule, not overwritten. Polling also sets a floor under latency — a change can wait up to 15 minutes for the next extract — which is why Module 3 states QA11 as "within 5 minutes of the extract that carries them", about 20 minutes worst case, rather than promising 15. If Lumen could allow log-based CDC on the referral system's database the floor would go; that is a clarification question, not an assumption. Outbound, every change the platform publishes goes through an outbox, so state and events cannot diverge.
Idempotent consumers
With at-least-once delivery any message can arrive more than once — after a broker redelivery, a consumer crash before acknowledgement, or a re-run extract. An idempotent consumer (Hohpe & Woolf's idempotent receiver) makes processing a message twice have the same effect as processing it once: record each message ID in the same transaction as the state change and skip IDs already seen, or make the operation naturally idempotent (set the status to Confirmed rather than advance it one step; upsert by referral ID and version). A message that keeps failing goes to a dead-letter queue for inspection instead of blocking the stream. The cost of skipping this at Lumen's scale: 4.2M studies a year ÷ 12 × 6 notifying stage changes = 2.1M SMS a month, so an assumed 1% duplicate rate is 21,000 unwanted messages. At an illustrative $6 per 1,000 that is only about $126 a month; the real cost is patients receiving repeated or contradictory messages about their appointment — and the same fault on the booking path books a slot twice.
Strangler fig
Martin Fowler's strangler fig application (bliki, 2004; named after the fig that germinates in a host tree's canopy and roots round it until it replaces the host) replaces an existing system gradually rather than in one cut-over: put a routing façade in front of the old system, move one capability at a time behind the façade to the new one, and retire each old path once nothing uses it. Every step is small enough to roll back, and the business keeps running throughout. Lumen's legacy is mostly a manual process rather than a system, but the shape is the same: automated booking replaces phone and email one capability at a time, and region by region, which the case allows; the desk's manual booking through web forms, which the case requires anyway, stays as the fallback path. Where a real legacy system sits on the path, the façade is usually an API gateway route or the anti-corruption layer above.
Delivery model selection
The three cloud service models differ in how much of the stack the consumer runs. With IaaS you rent virtual machines, storage and networks and operate everything above them; with PaaS you deploy your own application onto a runtime the provider manages; with SaaS you use the provider's application and manage at most its configuration. Module 9 defines them in full (service models).
When a customer asks for something "delivered as a service", separate two decisions:
- The consumption model is what the customer buys and operates. If the customer runs nothing but configuration, they are buying SaaS, whatever sits underneath.
- The hosting model is the Supplier's own choice of what to build that service on — IaaS, PaaS, managed services, or a mix. It is yours to make and justify against your own drivers.
Then work out what the consumption model forces:
- Tenancy — one dedicated deployment per customer, or one shared multi-tenant deployment. Multi-tenancy pays off only when you will serve several customers, and it makes tenant isolation an architectural problem.
- Data location — where each customer's or region's data must live, which shapes the deployment topology.
- Configuration versus custom code — what the customer changes themselves and what needs a release from you. The more self-service change the contract promises, the more the product needs configuration surfaces (workflow definitions, rules, templates, forms) in place of code.
Design fundamentals
Everything above is a catalogue: styles, patterns and tactics, each with the qualities it buys and what it costs. A catalogue does not say which entry to use, in what order, or how to show that the choice meets the requirements — that takes a design method. This section sets out what every design has to decide; the next teaches Attribute-Driven Design (ADD), which starts from the ASRs and utility tree you built in Module 3 and draws its design concepts from this module's catalogue. Module 6 then documents the design ADD produces, and Module 8 reviews it.
An architecture can be viewed as the result of applying a collection of design decisions. The seven categories of design decision from Module 3 give those decisions a systematic categorisation, so that an architect can focus attention on the design dimensions likely to be most troublesome.
- These categories are not the only way to classify architectural design decisions, but they provide a rational division of concerns
- The categories might overlap, and it's all right if a particular decision exists in two different categories — because the concern of the architect is to ensure that every important decision is considered
As a reminder, the seven categories are: allocation of responsibilities, coordination model, data model, management of resources, mapping among architectural elements, binding time, and choice of technology.
Trace architecture principles directly to the business drivers. A principle with a driver behind it is a legitimate source of constraints on every later decision; a principle with no driver is an unjustified constraint.
Design to the architecturally significant requirements, not to all of them. The rest are settled in detailed design; documenting every requirement up front buries the few that actually shape the architecture.
A baseline architecture is what exists today — systems, interfaces and manual processes. Only a truly greenfield project has none; Lumen's baseline is its phone-and-email process and the three systems it must integrate with (Module 6).
The big picture from SEI, with three main points:
- Different levels of architecture: Enterprise, System, Software
- Architecture comprises multiple structures: modules, component-and-connector, and allocation
- Input for the design process is Quality Attributes, Scenarios, Functional Requirements, Patterns and Tactics
Module 7 places this design work in the delivery lifecycle — discovery, construction and transition.
Attribute-Driven Design (ADD)
The structure of the method:
The version taught here, ADD 3.0 (Cervantes & Kazman, Designing Software Architectures: A Practical Approach, 2016), refines SEI's earlier ADD 2.0, whose loop — as summarised in Software Architecture in Practice, 3rd ed. — was a simpler four-step cycle: select element, identify the architecturally significant requirements, generate the design, and verify and refine requirements. ADD 3.0 keeps that same spirit but expands it into today's seven-step loop, adding an explicit drivers input (design purpose, functional requirements, quality attribute scenarios, constraints, architectural concerns) that feeds step 2 and an architecture-design output that closes the loop.
- Steps 1–7 constitute a design round
- Steps 2–7 constitute an iteration within that round; there can be several iterations in a round
- Each iteration focuses on achieving a particular goal
- The design we get after a particular round will be the input for the following rounds
The goal of an iteration is a subset of the drivers: structures that will meet one performance scenario, say, or let one use case be completed. Cervantes and Kazman's rule follows from that — set the goal before the iteration starts, because the goal decides which design concepts are even candidates, and it is the yardstick step 7 measures against.
Refinement (step 3)
To satisfy drivers you produce architectural structures, and their elements usually come from refining elements identified in an earlier iteration.
Refinement can mean:
- Decomposition into finer-grained elements — a top-down approach
- Combination of elements into coarser-grained elements — a bottom-up approach
- Improvement of previously identified elements
On a greenfield system the first iteration has only one element to refine — the system itself, placed in its context — and refines it by decomposition. On an existing system, and on later iterations of a new one, you refine elements found earlier. Lumen is brownfield in this sense: the platform is new, but the referral system, the patient identity service and corporate single sign-on already exist, so they fix the system context from the first iteration.
Choosing design concepts (step 4)
Cervantes and Kazman single this step out as the hardest in the method: you must first find credible alternatives that could achieve the iteration goal, and then choose between them.
In practice this step breaks into three moves: identify a list of alternatives, analyse each one against the drivers and ASRs to select candidate patterns and tactics, and select the alternative that best fits the defined criteria. The alternatives themselves are typically surfaced from the architect's own experience, skills and knowledge, from known tactics and patterns, and from the wider community's experience with similar problems. In this module, the style ratings and the pattern trade-offs above are that raw material.
Instantiating elements (step 5)
A chosen design concept is still abstract; the next decision is how to instantiate it as concrete elements, with responsibilities and interfaces. Cervantes and Kazman's example is the Layers pattern: choosing it does not tell you how many layers to have, because the pattern prescribes no number. Deciding on, say, presentation, business and data layers, and what each is responsible for, is the instantiation — the layers are the instantiated elements.
Sketching views (step 6)
Views drawn in one iteration are almost always incomplete: later iterations add the elements that other drivers need, so expect to revise them. That is why ADD speaks of sketching — the views at this stage are preliminary documentation. Formal, complete view documentation, the Module 6 kind, comes only after several iterations have settled the design.
The following step, analysing the design, is where you check whether the requirements have actually been satisfied and refine responsibilities accordingly, and review the sketches, views and decisions you just recorded. Use a checklist or ask for an external, unbiased review at this point, precisely because a design that looks complete to its own author can still hide gaps.
Recording an iteration
An iteration that is not written down cannot be reviewed. One page per iteration is enough:
| Step | What to write down |
|---|---|
| 2. Iteration goal | One sentence naming the drivers this iteration addresses — usually one or two ASRs, often a quality-attribute scenario plus the constraint it collides with |
| 3. Element refined | The element you decompose, combine or improve — the whole system on a first greenfield iteration |
| 4. Design concept | Two or three alternatives, how each fares against the drivers, and the one you chose |
| 5. Instantiated elements | The concrete elements, the responsibility of each, and the interfaces between them |
| 6. Sketch and decision | One view that shows the decision, with a key; the decision itself as a short ADR (Module 6 covers the format) |
| 7. Analysis | Whether the goal is met, what moves to the next iteration, and one sentence of traceability: which ASR this satisfies and how you will verify it |
Check yourself
- Two services exchange only events through a broker, and a colleague says they are now "fully decoupled". What coupling remains, and what would you put in place for it?
- The style table rates a modular monolith Low on scalability. A colleague concludes it cannot carry Lumen's load. What is wrong with the argument?
- An insurance claim passes through eight steps with timeouts and compensations, and the business wants to see where every claim has got to. Mediator or broker — and what do you give up?
- A consumer receives "appointment 123 cancelled" before "appointment 123 rescheduled". Name two design measures that stop this corrupting its state.
- Why does the transactional outbox exist, and why does it oblige every consumer to be idempotent?
- Blue-green rollback is "switch the router back". When does that stop working, and how do you keep it working?
- Why does ADD insist on an iteration goal before you choose design concepts?
- A customer asks for a platform "delivered as a service". Does that oblige the Supplier to build it on PaaS?
Suggested answers
- Messaging removes temporal and location coupling but not schema coupling: both sides still depend on the event's shape and meaning. Give the event contract an owner, make changes additive, version breaking ones, and check compatibility in the build with a schema registry or contract tests.
- The ratings are relative to the other styles, not to a load. Lumen's busiest hour is 1,680 referrals — under 0.5 a second — with roughly 1,650 concurrent sessions, which a cloned, stateless application tier on one well-sized database carries comfortably; the deciding drivers lie elsewhere.
- Mediator (orchestration): one component holds each claim's state, so it can time out, compensate and report progress, and the process changes in one place. You give up some throughput and decoupling, and the mediator becomes a component that must scale and stay available.
- Partition events by entity, so all events for appointment 123 arrive in order on one partition; and carry a version or sequence number so the consumer discards anything older than what it holds. Idempotent handling covers the duplicates that come with redelivery.
- A service that updates its database and then publishes an event can crash between the two, leaving state and events disagreeing. The outbox writes the event in the same local transaction and a relay publishes it at least once: a relay that crashes after publishing but before marking the row sent publishes it again, so consumers must absorb duplicates.
- It stops working once the new release changes something the old one cannot handle — a destructive schema migration, data written in a new format, a call to an external system that cannot be undone. Expand/contract migrations and backward-compatible data keep the old version runnable until the new one is proven.
- The goal selects the subset of drivers the iteration must satisfy. Without it you cannot tell good alternatives from bad in step 4, nor say in step 7 whether the iteration succeeded.
- No. "Delivered as a service" describes what the customer consumes — effectively SaaS. What the Supplier hosts it on (IaaS, PaaS, managed services) is a separate decision, justified by the Supplier's own drivers such as time to first release, operating cost and regional presence.
Exercises — Module 4
Task. Take your Module 3 ASRs for Lumen Diagnostics to a first design.
Output: a design record of 3–5 pages in two parts, with one diagram.
- A style/pattern decision note: one paragraph on the delivery model, then one entry for each of the Lumen sub-problems (a)–(c) listed under Part 1 below — the chosen style or pattern, one rejected alternative and why, and the Module 3 ASR IDs it serves (for example F01, F03, F04, F08, QA02, QA10, QA11).
- One ADD iteration on a high-priority ASR from your Module 3 utility tree: iteration goal, the element refined, the design concept chosen with the alternatives considered, the instantiated elements and their responsibilities, a sketch of the view, and a one-sentence traceability statement.
Time: about 3½ hours — 45 minutes on the warm-up questions, 1¼ hours on the decision note, 1½ hours on the ADD iteration.
Inputs: the case, including its Volumes and usage table; your Module 3 ASR list and utility tree; your Module 2 business drivers. Keep the record: Modules 5 and 6 build on it, and Module 8 reviews the design it contains.
Warm-up questions — answer in your notes, from your own knowledge first, then research. They are not part of the deliverable.
- A design solution for a concrete context and problem: style, pattern, or tactic? How do the three differ?
- What are coupling and cohesion? Give a specific example of each.
- Typical cons of a monolith, including drawbacks you have seen — and which of them a modular monolith removes
- The layer figure in the Layered section: is it a correct layered architecture, and why?
- Can C use B?
- Can A use C? If you allowed it, how would you record that decision?
- When is event-driven worth using? When Mediator, when Broker?
- REST: is Richardson Level 3 worth chasing? Describe a case where it helps.
- What is a microservice? List challenges and drawbacks.
- When is CQRS a good fit?
- Name an integration framework or platform in a language you use; list pros and cons.
- Error, Fault, Failure: which leads to which? One sample of each from a project you know. (See Module 3 — Reliability, faults, errors, failures.)
- When does a circuit breaker help?
- Goal is zero downtime; the app has almost no automated tests. Which techniques, and why?
Part 1 — decision note
- Lumen wants a supplier-hosted scheduling platform. IaaS, PaaS or SaaS?
- What does that choice force on tenancy, regional data, and configuration vs custom code?
- For Lumen, which style or pattern for each, and why against the case?
- (a) availability search
- (b) offer / confirmation workflow
- (c) one automated partner API plus ~600 manual partners
- For each of (a)–(c), one rejected alternative that was a serious contender, and the reason from the case
- For each, the Module 3 ASR IDs it serves and what the decision costs
Part 2 — one ADD iteration
- Pick one H,H or H,M quality-attribute scenario from your Lumen utility tree
- Iteration goal: the drivers this iteration addresses, in one sentence
- The element you refine — the whole system on a first iteration, or an element from your decision note
- At least two candidate design concepts, compared against the drivers; the one you chose
- Instantiated elements, the responsibility of each and the interfaces between them
- A sketch of the view that shows the decision, with a key
- Traceability in one sentence: which ASR this decision satisfies, and how you will verify it
Self-assessment
| Criterion | What good looks like |
|---|---|
| Traceability | Every decision cites at least one Module 3 ASR ID, and every H,H or H,M ASR that (a)–(c) touch is served by some decision |
| Real alternatives | Each rejected alternative is one a competent architect might have chosen, rejected for a reason taken from the case or a labelled assumption — not a straw man |
| Costs stated | Each decision says what it costs — complexity, consistency, operations, money — not only what it buys |
| Case numbers used | Where scale matters you used the case's figures (14,000 referrals a day, 1,680 in the busiest hour, ~600 partners doubling) and labelled any figure of your own as an assumption |
| ADD iteration complete | Goal, element, alternatives, chosen concept, instantiated elements with responsibilities, sketch with a key, and a traceability sentence are all present, and the goal names specific ASR IDs |
| Delivery model | The paragraph separates what Lumen buys from what you host it on, and says what that forces on tenancy, data location and configuration |
Worked answer — Lumen delivery model
Attempt the delivery-model question in the Task before reading this.
SaaS, as Lumen consumes it. Lumen is buying a booking capability, not a place to build one: the case asks for a platform "delivered as a service and hosted and supported by the Supplier" (Module 3's constraint C01). Lumen's staff configure rules and workflow; they do not operate virtual machines or deploy code. IaaS or PaaS as what Lumen buys would leave Lumen operating infrastructure or a platform itself, which the case rules out.
The Supplier's hosting decision is separate. You build and run the application, and may well host it on IaaS, PaaS or managed services underneath — that choice is yours to make and justify against your own drivers. A first release within 12 months favours managed services that remove undifferentiated operations work; entering a new jurisdiction requires a provider with a presence there.
What SaaS forces:
- Tenancy. Lumen is a single customer, so a dedicated, single-tenant deployment is a legitimate answer and avoids tenant isolation work. Multi-tenancy earns its cost only if you plan to sell the platform to other imaging networks — a business decision to raise with your own management, not an assumption to build in.
- Regional data. Patient data stays in the jurisdiction where it was collected (QA05), and one of the two new regions is in another jurisdiction. Plan per-region deployments, or at least per-region patient-data stores under a non-identifying global layer, from the first release, and build them from templates so a new region is configuration rather than code (QA16) — retrofitting data partitioning later is expensive.
- Configuration versus custom code. The workflow must change after go-live (F04), prioritisation rules change over time (F08), and a policy change must be live within one working day without code (QA10). Under a SaaS contract every change that needs code is a change request to the Supplier, so the workflow definition, prioritisation rules, notification templates and forms belong in configuration owned by Lumen's Scheduling Manager; code changes are reserved for new capabilities.