Software Architecture in the AI & Cloud Era

← the whole book on one page

Chapter 15: Platform Engineering and the Capstone

The best architecture is the one other teams build great things on without asking you anything.

Encore, which had nine teams in Chapter 5, now has 400 engineers in 40 teams. At that size its most important customer is one it never signed: its own engineering organization. Look back over the book and you will find that every chapter left some machinery behind: enforced boundaries, an event backbone, API golden paths, data products, paved-road security, service-level objective (SLO) tooling, an AI gateway and a tenant control plane. Each piece was built to solve a problem once, for everyone. But building something is not the same as looking after it, and someone must now own all of it and keep it evolving as the company grows. That someone is the platform team. Its job is to see that 40 teams receive this machinery as a shared service, because the alternative is 40 teams each building their own version: 40 ways of rotating secrets, 40 slightly different dashboards, and 40 places for the same mistake to hide.

Platform architecture is architecture applied to architecture. Until now, the systems we designed served fans buying seats for concerts. The platform is a system too, but the people it serves are the engineers who build those fan-facing systems, so the familiar vocabulary shifts by one level. Its users are engineers. Its product is their delivery speed: how quickly, and how safely, a team can take an idea to running software in production. Its API is a golden path, the supported, ready-made route through a common job such as creating a new service, which Section 15.2 develops in full. Everything else carries over as well, including the costs.

That is why every trade-off of the earlier chapters returns here one level up, where it is harder to see and more expensive to get wrong. It is harder to see because a platform’s cost lands on other teams’ delivery, not on its own dashboards; a slow pipeline never pages anyone, yet it taxes every team that uses it. It is more expensive to get wrong because a platform multiplies its decisions. Suppose the template for new services ships with a careless default, such as a timeout that is too generous. Every service created from that template inherits the mistake, and on the evening of a big on-sale, 40 teams discover it together.

The capstone at the end of this chapter asks you to design such a platform completely and to defend it decision by decision, naming the cost of each choice, just as you have defended every design since Chapter 1. The difference is only in who will live with the consequences: this time your customers are fellow engineers, and they will notice.

15.1 Why Platforms

Cognitive load

Start with what an Encore team actually has to know. A stream-aligned team is one organized around a single flow of business change, such as the team that owns on-sales or the team that owns the seat map. Without a platform, that team, hired to ship ticketing features, must also master cluster configuration, build and deploy pipelines, observability wiring, secret rotation, schema registries, cost dashboards, threat models and the AI gateway. Each of these is a specialty with its own documentation, its own failure modes and its own experts. No team can hold all of that in its head and still do its real job well.

Skelton and Pais, the authors of Team Topologies, gave this problem a name. They borrowed the term cognitive load from John Sweller’s educational psychology, where it describes how much a learner’s working memory must hold at once. Applied to a team, cognitive load is the amount of a domain the team must keep in mind to change its software safely. The important word is finite. A team has only so much attention, and every concern it carries is paid for out of the attention it would otherwise give its business. An hour spent learning how to rotate a database credential is an hour not spent making the next on-sale fairer.

When the load exceeds what a team can carry, it fails in one of three ways, and Encore, with 40 teams, would see all three. Some teams sink into the stack: they become part-time infrastructure engineers and stop shipping features. Some teams skip the stack: they cut corners on secrets, signing or access control, and quietly reopen the security gaps Chapter 10 worked to close. And some teams solve it their own way, so the company ends up with 40 different solutions to the same problem. That last outcome is the worst, because it delivers both of the other problems at once (every team is still spending attention on the stack, and many of the 40 versions have gaps) plus an audit finding when someone finally counts them.

Brooks’s distinction from Chapter 1 returns here in a new costume. Recall that essential complexity belongs to the problem itself, while accidental complexity comes from the tools and circumstances we use to solve it. To a ticketing team, the fairness of an on-sale is essential complexity: it is the problem the team exists to solve, and no tool can make it go away. Secret rotation is different. It is real work, and someone must do it well, but it is accidental to ticketing; fans will never know or care how the credentials behind the seat map were rotated. A team that carries secret rotation is carrying someone else’s luggage, and it walks more slowly for it. An internal developer platform is the answer: a curated product that absorbs this undifferentiated stack (work that is the same for every team and gives none of them an edge) and exposes it through self-service interfaces. The product teams can then spend their attention on the business, which is the only place their attention creates value.

Notice that the operating model around the platform matters more than its software. Under platform as a product, product teams are treated as customers, and like real customers they may choose the platform or decline it. That means the platform cannot simply be announced; it has to win its users, as any product must. This one stance generates a whole discipline. The platform team talks to its users to learn where they hurt, measures adoption to find out whether it is helping, and publishes a roadmap so teams can plan around what is coming. And it does not try to build everything at once. It starts from what Skelton and Pais call the thinnest viable platform: the smallest platform that removes real pain, built as a paved road (a well-supported, ready-made route) over the single most painful mile. At Encore that mile is “new service to production.” Without a platform, standing up a new service means a team must assemble a template, a pipeline, observability and identity by hand. The thinnest viable platform puts all four behind one command.

How does a platform team find the most painful mile? Here an idea from landscape design helps. When a paved walkway goes somewhere people do not want to go, they cut across the lawn instead, and over time their footsteps wear bare tracks into the grass. Landscape designers call these tracks desire paths. Some planners deliberately leave a new lawn unpaved for a season, then pave where the grass has died, because the dead grass shows exactly where people walk. A platform team can do the same thing, because product teams have already worn their own tracks. The shared script that three teams pass around, the pipeline everyone copies from the one team that got it working, the wiki page everyone bookmarks: each is a workaround built because the official route did not exist or did not fit, and each shows where the road ought to run. The analogy fails in one instructive respect. Grass records footsteps for free, without anyone asking. A platform team gets no such record; it has to go out and ask, by interviewing teams and looking for the workarounds itself.

Voluntary adoption is the heart of platform as a product, but it has a limit, and it is worth drawing that limit precisely. The platform offers two kinds of things. Guardrails are few and mandatory: signed images, declared authorization, cost ceilings and the other rules of Section 15.3. These protect the whole company, not just the team that might choose to skip them, so no team gets to opt out. Paths are many and voluntary: templates, pipelines and portals that make the common case easy. A team may leave a path if it is willing to carry the load the path would have carried for it. So the rule is simple: the platform imposes guardrails and wins adoption of paths. Each half can go wrong. A platform that mandates its paths has stopped listening, because forced users no longer tell it, by leaving, when a path is bad. A platform that leaves its guardrails optional has stopped governing, because the one team that skips image signing is the one an attacker needs.

My clearest experience of voluntary adoption is a small one. At a bank hackathon I built a retrospective tool in a few days. Nobody mandated it. It spread team by team, each one adopting it because a neighbor had found it useful, until 10,000 employees had used it, and it outlived my tenure by years on a trickle of maintenance. The lesson I took from it is that tools that win their users on merit tend to survive their authors, because their users have a reason to keep them alive. Platforms need the same discipline, at 100 times the stakes: a retrospective tool that fails costs a few awkward meetings, while a platform that fails slows every team in the company.

Each anti-pattern below breaks the platform-as-a-product stance, and each breaks it in a different way:

Figure 15.1 — Four ways platforms die. Each is avoided the same way: real customers, voluntary adoption, measured value and a thin start.

Recap. A platform takes undifferentiated, accidental work off product teams, so that their limited attention goes to the business rather than to the stack. Its operating model is platform as a product: product teams are voluntary customers, adoption is measured, and the platform starts thin, with the most painful mile paved first. It sets a few mandatory guardrails that protect everyone, beside many paths that must earn their users. The four anti-patterns show what happens when that model is abandoned.

Exercise 15.1. List everything a new service at your company needs before it can safely serve production traffic: for example, a repository and template, a pipeline, observability, identity, secrets and access rules. Estimate how long a team would take to do all of it alone, without help. That estimate is the platform’s business case, or, if it is small, the evidence that you do not yet need one.

15.2 Platform Anatomy

Golden paths and the self-service control plane

Section 15.1 argued that a platform must win its customers. The next question is what, exactly, those customers are offered. The answer is the platform’s product surface, the golden path: an opinionated, supported, self-service route through a need that many teams share. Each of the three words does work. The path is opinionated because it has already made the choices a team would otherwise have to research for itself: which pipeline, which dashboards, which way to wire identity. It is supported because someone answers when it breaks, so a team that follows it is never stranded. And it is self-service because using it takes no ticket and no meeting; a team walks the path on its own schedule. Encore’s “new service” path has four parts, and each one replaces a job that a team used to do by hand:

• A template: a skeleton for a new service with the essentials already wired in, namely Chapter 5’s contracts, Chapter 10’s identity and Chapter 11’s observability. A team that starts from it begins with those disciplines in place instead of adding them later, or never.
• A provisioning workflow that creates the pipeline, dashboards, on-call rotation and cost budget for the new service. The older habit was to write a wiki page describing how to set all of that up; the workflow does it instead of documenting it.
• A registry entry recording the service’s owner, its tier and its SLOs. Together these entries form the service catalog, which is what answers “who owns this?” at 3 a.m., when a dashboard is red and someone needs to know whose pager to ring.
• A scorecard that grades the service against Chapter 11’s production-readiness checks, and keeps grading it continuously, so a service that was ready at launch cannot quietly drift out of readiness a year later.

A musical comparison helps to show why such a structure liberates rather than confines. When a jazz quartet plays a standard, the players share the chord changes, the agreed sequence of harmonies that underpins the tune. Nobody renegotiates the key at every chorus, and because that question is settled, each player’s attention goes into what they play over the changes, which is where the music is. A golden path plays the role of the changes. When an Encore team building a new seat-map feature need not decide how its service will be deployed, monitored or authenticated, its attention goes to the seat map. The analogy breaks at the moment of departure, and the break teaches something. A soloist who leaves the changes may be admired for daring. A team that leaves the golden path earns no such applause; it has simply taken on, by itself, all the work the path used to carry, from the pipeline to the on-call rotation.

The idea has an older ancestor in the architecture of buildings. In A Pattern Language (1977), Christopher Alexander and his colleagues gave builders a vocabulary of 253 patterns, each pairing a problem that recurs with the core of its solution. Software borrowed the idea, and our design-pattern catalogs descend from it. A golden path takes the idea one step further: it is a pattern made executable. A pattern written as prose asks every reader to implement it again. Forty Encore teams reading a page titled “how to set up observability” would produce forty slightly different setups, each with its own gaps. A golden path implements the pattern once, in code, and every team that runs it receives the same correct result.

To see where golden paths sit in the larger architecture, it helps to recall Chapter 14. There, Encore built a control plane, the machinery that manages tenants (onboarding them, giving them identities, configuring them and billing them) as distinct from the application plane, which does the work tenants came for. The platform turns that same design inward. Its tenants are no longer venues but Encore’s own product teams, and the machinery it manages is the set of planes this book built one chapter at a time:

Figure 15.2 — The platform as the book’s index page. The bottom row holds the capabilities earlier chapters built, from compute and delivery to the AI gateway; nothing in it is new. What the platform adds is the middle row: one control plane that makes everything below it self-service, registered and metered, using Chapter 14’s machinery with teams as the tenants, and reached by the 40 product teams through the golden paths at the top.

What the figure shows is hierarchy doing its old work, the same structuring Herbert Simon described for enduring complex systems (Chapter 1). The planes in the bottom row have not become any simpler: the event backbone still has its partitions and the security plane still has its keys and policies. Their complexity has instead been placed behind a small set of requests, such as “create a service,” “give me a topic,” or “grant this service access to that one.” A product team works at the level of those requests, and only the platform team has to look beneath them. That division is the whole point: it is how 40 teams can each use six planes without each of them having to understand six planes.

Very little of this needs to be built from scratch. Most of the boxes in Figure 15.2 can be bought or adopted, which is Chapter 13’s ledger applied to the platform itself. In a typical setup, Backstage (or a commercial portal such as Port or Cortex) carries the catalog, the templates and the scorecards, giving teams one place to find services and start new ones. Crossplane or Kratix expose the control plane as declarative, Kubernetes-style APIs, so a team describes what it wants (“a service with a database and a queue”) and the system works out how to bring it about. Open Policy Agent (OPA) Gatekeeper or Kyverno enforce admission policy, the checks that run whenever something asks to be deployed into the cluster and that reject it, for example, if its image is unsigned. To judge how far along you are, the Cloud Native Computing Foundation’s (CNCF) Platform Engineering Maturity Model offers a yardstick. What remains for Encore to write is the part nobody can sell it: the glue that connects these tools, and the content of the golden paths themselves, which encode Encore’s own decisions about how a service ought to be built.

The organization behind the platform needs designing as carefully as the software. Following Chapter 5’s team topology, a common rule of thumb sizes the platform group at 5–10% of engineering, which at Encore’s 400 engineers means somewhere between 20 and 40 people. They are organized as product teams, one per plane, each owning its plane the way a stream-aligned team owns a service. That arrangement puts Conway’s law on our side. Conway observed that systems copy the communication structure of the organizations that build them, so if the seams between platform teams fall along the seams between planes, the planes will stay cleanly separated, because the people building them are. Arranging teams deliberately to get that result is the later idea named the inverse Conway maneuver. Platform engineers also spend time inside their customer teams, in what Team Topologies calls enabling interactions: working alongside a product team for a while, watching where the golden path chafes, and smoothing it, so that the next team finds the path easier than the last.

One line is fixed, and it is worth stating without hedging: the platform runs the roads and never operates a product team’s service. The reason lies in the feedback loop Chapter 5 described. A team that carries the pager for its own service learns, at 3 a.m. if necessary, what its code does under real load, and that lesson is what makes the next version better. Once platform engineers start carrying the pager for product services, that loop breaks. The Orders & Payments team, say, would stop feeling the cost of its own failures, and so would stop learning how to prevent them, while the platform team would quietly turn into the ticket-queue anti-pattern of Figure 15.1, absorbing other teams’ work instead of automating it.

Recap. Golden paths are the platform’s product, and each one is a pattern made executable. Encore’s “new service” path has four parts: a template, a provisioning workflow, a registry entry and a scorecard. Architecturally, the platform is Chapter 14’s control plane turned inward, with product teams as its tenants, sitting over the planes of Chapters 6–12 and hiding their complexity behind a few self-service requests. It is run by a right-sized product organization, one team per plane, that helps product teams walk the paths but never operates their services for them.

Exercise 15.2. Design the golden path for the need you identified in Exercise 15.1. Write down three things: what the template contains (the code, configuration and wiring a new team receives on day one), what the provisioning workflow creates (pipelines, dashboards, rotations, budgets, registry entries and anything else), and the single command a team runs to set it all in motion.

15.3 Governance as Code

Governance that runs itself

At Encore’s size, governance runs into a problem of arithmetic before it runs into a problem of policy. Suppose a review board can examine a few designs a week with real care. With nine teams, as Encore had in Chapter 5, that is enough: each team brings a design every month or two, and the board can read each one properly. With 40 teams the queue grows faster than the board can read, and the board ends up one of two things. Either it becomes a bottleneck, and teams wait weeks for approval of changes they could have shipped in a day, or it becomes a rubber stamp, approving designs it has had no time to understand. Neither one governs anything. Encore has 40 autonomous teams and no review board, so governance has to run inside the work teams already do, carried by checks that run without anyone convening a meeting. Fortunately, we have been building those checks since Chapter 1, and this section gathers them into one system.

The first part of that system is the fitness function, Chapter 1’s automated check that the architecture still has a characteristic we care about. At platform scale these checks grade every service continuously, on every change and on a schedule, across the concerns the book has built up: boundary rules (Chapter 2), contract compatibility (Chapter 5), security posture (Chapter 10), SLO and cost health (Chapter 11) and eval scores (Chapter 12). The results roll up into each service’s scorecard, which both the team and its leadership can see. The point is timing. Suppose the Notifications team’s error budget burns down a little faster each week, or a new dependency quietly reaches into another module. The scorecard turns amber while the drift is still small and cheap to fix, so the team learns of it from a dashboard on a quiet Wednesday, not from an incident during an on-sale.

The second part is policy as code: the few non-negotiable rules, written as machine-checked policies instead of a wiki page. These policies run at two gates. One is continuous integration (CI), where a change is checked before it merges. The other is admission, the moment the cluster decides whether to accept a workload at all (not to be confused with the Sale Gate’s admission of fans). Encore’s rules are short and concrete. Unsigned images don’t run, so a container that did not come out of the trusted pipeline is turned away at the door. Every endpoint declares its authorization, so there is no such thing as an endpoint that is accidentally open to anyone. And every field holding personally identifiable information (PII), such as a fan’s email address or phone number, carries one of Chapter 10’s data classifications, so every tool that touches the field knows how carefully to treat it. A rule written this way cannot be forgotten, misread or skipped on a busy day, because nobody has to remember to apply it.

There is an old precedent for rules of this kind. After the Great Fire of 1666, London was rebuilt under rules that required brick and stone in place of timber. Notice what those rules did and did not do. They were few. They concerned what could burn, which is to say the risk one house posed to its neighbors. And they left the shape of each house, its rooms and its use, to its owner. That is the economy Encore’s admission policies should aim for: rule on what can set the neighbors on fire, such as an unsigned image or an open endpoint, and leave every other design choice to the team. The analogy breaks at the inspection, and the break is instructive. A city inspects a building once, when it goes up, and the building then stands mostly unchanged for decades. Our services are rebuilt many times a day. An inspector who had to visit every one of those rebuilds would never keep up, so the inspection must be automated or, in practice, it will not happen at all.

Rules this firm need a safety valve, and the third part of the system is the exception path, designed in advance instead of improvised under pressure. Teams may leave the paved road, but every deviation is priced, logged, owned and time-boxed. Priced means the team that leaves carries the cost of building and running its own alternative. Logged means the exception is recorded where anyone can see it. Owned means a named person answers for it. Time-boxed means it expires, and must be renewed or retired, instead of becoming permanent by neglect. Suppose the Sales Analytics team needs a database the platform does not yet offer: it may run one, provided it records the exception, names an owner and accepts that it is on its own when that database pages at night. This is freedom with a ledger. It replaces two older failures at once: the ivory tower’s blanket “no”, which drives teams to work around the rules in secret, and the unrecorded drift that follows when nobody asks at all. The ledger also teaches the platform team something. When the same exception is requested for the third time, it is no longer an exception. It is a path the platform is missing, and the ledger has just written its requirements.

Governance covers the platform itself too, and here it is strictest. The platform’s APIs are the kind of promise Chapter 7 described, made to strangers, except that these strangers are internal: 40 teams the platform team cannot coordinate with one by one. So those APIs get the full discipline of Chapter 7. They are versioned. They change by Chapter 5’s expand–contract, adding the new shape first and removing the old only after every consumer has moved. And they are contract-tested against every consuming team, so a platform change that would break the Catalog team’s pipeline fails the platform’s own build before it ships. A platform that breaks 40 teams at once has done more damage than any single team could, which is why its contracts deserve the company’s most careful handling.

The same discipline applies when the platform takes something away. Deprecation runs as a campaign, not a memo. It has four parts: migration tooling that does most of the move for each team; a dashboard of laggard teams, so everyone can see who has not yet moved; hands-on help, a person sitting with the last three teams, who are often last because their case is the hardest; and a real sunset date that actually arrives. Without such campaigns, a platform accumulates every capability it has ever offered, each still running, each still able to fail. A platform that never retires anything becomes a museum that pages: a collection of old exhibits that still wakes someone at night. When a capability does go, Chapter 1’s rule for architecture decision records (ADRs) applies at a larger scale. An ADR is never deleted; it is superseded and kept, so the reasoning survives the decision. In the same way, the retired capability disappears from production, but the record of why it existed, and why it was retired, stays in the archive for the next team that wonders whether to build it again.

Recap. A review board cannot keep pace with 40 teams; it becomes a bottleneck or a rubber stamp. So governance moves into the work itself. Fitness functions feed scorecards that show drift while it is still small, policy as code enforces a few non-negotiables in CI and at admission, and a priced, logged, owned and time-boxed exception path lets teams leave the paved road in the open. Repeated exceptions show the platform team which paths are missing. The platform’s own APIs carry the company’s strictest contract discipline, and deprecation campaigns, with tooling, laggard dashboards, hands-on help and sunset dates, retire what it no longer needs while keeping the record of why.

Exercise 15.3. Write three policy-as-code rules your organization would enforce at admission today if it could. For each, state what it blocks and what harm it prevents. Then name one rule your organization currently enforces that you would demote to advisory, a warning instead of a block, and justify the demotion: explain why the harm it prevents is small enough, or the cost of blocking high enough, that a warning is the better trade.

15.4 Architecting When Code Is Cheap

What changes when code is cheap

The preface made a prediction that we can now cash out: as code gets cheaper to produce, judgment becomes the scarce part of the work. Consider what “cheap” means in practice. When a coding agent can regenerate an entire service overnight, the implementation itself stops being the precious thing. If it is wrong, we can have another by morning. What we cannot regenerate overnight are the artifacts this book has been building since Chapter 1, the ones that steer the code rather than constitute it. Architecture decision records (ADRs) say why the system is shaped as it is. Module boundaries say where each responsibility lives. Contracts say what each part promises the others. Fitness functions confirm, continuously, that all of this still holds. Those four are now the scarce artifacts, because they are what tells the generator what to build and what tells us whether it built the right thing. Architecture, in this light, becomes the discipline of directing code that nobody reads line by line.

We have been here before, or nearly. The cost of producing code has collapsed once already. When the first FORTRAN compiler shipped in 1957, programmers did not stop caring about machine code overnight; for a while many checked what the compiler emitted. Gradually they stopped reading it, and the profession moved its attention up a level, from registers and jumps to formulas and loops. It is tempting to say the same thing is happening again, and in one sense it is. But the parallel breaks at an important joint. A compiler is deterministic: the same source produces the same output every time. Its behavior is also specified: the language definition says what each construct means, and the compiler can be tested against it. That is why programmers could eventually trust the compiler itself and stop looking at its output. An agent is neither deterministic nor specified. Ask it twice and it may write two different services; ask it once and nothing defines exactly what it was obliged to produce. So we cannot place our trust in the generator, as we learned to do with compilers. Our trust has to rest on checks of what comes out: its behavior, its boundaries and its contracts.

Encore learned what this looks like on an ordinary Tuesday. A coding agent, working from a well-specified backlog, rebuilt the Notification service overnight. By morning there was a new framework, better retry semantics (the rules for when and how to try again after a failed send) and 40 files that nobody had typed or read in full. The interesting part is how much of that change had already been vouched for before anyone finished breakfast, and by machines. The consumer contracts passed, so every service that relied on Notification still got the messages it expected. The boundary rules held: the new code made no calls outside the published contracts and read no other service’s tables. The security checks came back clean. And the SLO canary, which sends a small slice of real traffic to the new build and promotes it only if its service-level objectives hold, promoted the build like any other change.

There was one thing the checks missed, and it was not small. The new retry semantics could send a fan the same ticket twice. Picture a fan who buys a seat for a Saturday show: the email provider is slow to acknowledge the first send, the new code treats the silence as failure and tries again, and the fan ends up with two copies of one ticket in their inbox. That is confusing at best, and at worst it invites a dispute at the venue door. No contract test caught it, because the messages were correctly shaped; the trouble lay in how many of them went out. One engineer spent 20 minutes on that change alone and added a spec-level idempotency test, one that asserts a ticket is delivered once no matter how many times delivery is retried, before merging. I think that morning shows the shape of the work to come. Machinery vouched for nearly everything. One human judgment, applied in the one place no check reached, stood between a fan and a duplicate ticket. And once that judgment was turned into a test, it became machinery too, so the next agent to touch Notification will meet the check instead of needing the human.

From that Tuesday, four shifts follow. None of them demands new machinery. Each lands on something Encore already built in earlier chapters, and changes what that thing is for.

Decision records become agent context. An ADR corpus was always the team’s memory: the place a new engineer goes to learn why the seat ledger is a consensus group, or why Orders & Payments integrates two payment service providers. Now that corpus is also the prompt. Agents read the decisions, the constraints and the consequences before they write code, which means a clearly written ADR is no longer just documentation; it is a direct control input to what gets generated. This is the second law of Chapter 1 operating at generation time: the recorded why steers the how, quite literally, because the how is now produced by something that reads the why. The cost of a poorly written ADR changes accordingly. A vague ADR used to cost an argument in a design review, where a human could ask what it meant. Now it costs a confidently wrong implementation by Thursday, because the agent will not ask; it will pick an interpretation and build on it.

Review economics invert. When implementation was expensive, review meant reading the code, because the code was where the effort and the risk both lived. When implementation is cheap and abundant, reading every line becomes both impossible and pointless. Human attention has to move up to the places where decisions are visible: the boundary the change touches, the diff to the contract, the change in eval scores (the delta between the old and new results of the automated quality checks Chapter 12 introduced), and the ADR the change claims to implement. Chapter 5’s testing pyramid gains a human layer on top: people review decisions, interfaces and any behavior that no automated check covers yet, as the engineer did with the duplicate tickets. CI reviews everything else, or, to put it bluntly, nobody does. There is no middle option. A team that tries to hand-read generated volume soon becomes the bottleneck on every change, and under that pressure its reviews quietly decay into rubber-stamping, which is worse than no review because it looks like one.

Governance becomes the main safeguard. Section 15.3 built governance as code so that 40 teams could move safely. Now the same machinery has to cover their agents too, and the volume of change it must check grows far beyond anything a review board could ever read. The good news is that it can. Boundary checks, contract tests and evals run in CI on every change, and they cost the same whether a change was typed by a person or generated by an agent at 3 a.m. They are the only reviewers that scale with generation speed, because they run at machine speed themselves. That changes the role of the paved road. It began as a convenience, the easy way to do the right thing; now it is also what keeps a high volume of change from slowly wearing the architecture away.

Agents are tenants too. A coding agent that opens pull requests, provisions environments or queries production data is a user of the platform, as surely as any engineer is. So it should be treated like one. It gets its own workload identity and scoped credentials (Chapter 10), so that what it can touch is limited to what its task needs. It gets a sandbox to work in, quotas on what it can consume, and metered spend, so its cost lands on someone’s budget. It reaches the golden paths through machine interfaces, such as the platform’s APIs or Model Context Protocol (MCP) tools, rather than through the portal a human would click. The principle is the one any shared machine has always applied to its users: an agent needs an account, a quota and a bill. Consider the alternative. An agent that runs on a human’s credentials, with no path of its own, repeats the mistake Chapter 12 described in its direct-call stage, one level down: keys scattered across scripts and laptops, and costs that no one can attribute. When something goes wrong, the logs will say a person did it when a machine did.

Erosion at generation speed. Picture 1,000 commits. Each one is plausible on its own, and each one passes its tests. Yet together they dissolve the architecture. One adds a helpful import that reaches across a module boundary. Another adds an accommodating optional field that widens a contract a little. None of them is wrong enough to fail a check, and so the boundaries blur and the contracts widen, until the modular monolith is just a monolith again and nobody typed a line of it. The countermeasures are this book in miniature: boundaries enforced by machines (Chapter 2), contracts tested on every change (Chapter 5), evals gating behavior (Chapter 12), scorecards surfacing drift (Section 15.3), and an architect who reads trend lines instead of diffs, watching whether the architecture is holding across a thousand changes rather than judging any one of them.

Erosion itself is an old problem, and it helps to see how old. Perry and Wolf (Chapter 1) named it in 1992, and they drew a useful distinction. Erosion is the outright violation of an architecture: a call that crosses a boundary it should not. Drift is subtler: an insensitivity to the architecture, a loss of awareness of what it intends, which makes violations easy and therefore likely. Earlier still, Fred Brooks, in The Mythical Man-Month (1975), called conceptual integrity the most important consideration in system design, and he worried about what many hands would do to it. Each pair of hands brings its own idea of how the system should work, and the sum of many reasonable ideas is rarely one coherent design. We now have many hands that are not hands at all, and they work through the night. What is new is only the rate. Erosion that once accumulated over years of human commits can now accumulate far faster. And a rate can only be met by something that keeps the same pace, which is why the defense must be machinery that runs on every change, not people who look in from time to time.

None of this machinery makes the trade-offs for you. No agent owns the consequences recorded in an ADR, and no eval decides which architectural characteristics should drive Encore’s next year: whether, say, on-sale availability matters more than the speed of shipping new features. Those remain human judgments, made by people who will answer for them. Cheap code makes that judgment more valuable, not less, because each judgment is now multiplied across everything the agents generate. The platform is where such judgment is encoded once and enforced everywhere. When writing code costs almost nothing, the cost that remains is the cost of being wrong about it.

Recap. When code is cheap, ADRs, boundaries, contracts and fitness functions become the steering interface for the system, read by humans and machines alike. Human review moves up from lines of code to decisions, interfaces and behavior no check yet covers, while governance as code checks everything else at the speed the code arrives. Agents are tenants of the platform like any other, with their own identities, quotas and paths.

Exercise 15.4. Take one recent AI-assisted change in your codebase (or the Notification rebuild). Make two lists: what was machine-checked before merge, and what only a human could have caught. The second list is your erosion surface. For each item on it, name the check that would move it onto the first list.

15.5 Platform Strategy and the Elevator

The map, the money, and the message

A platform team lives in an awkward position. It spends real budget, but the value it creates is indirect: its benefits show up in other teams’ numbers, while its costs show up in its own. When the ticketing team ships a feature in three days instead of three weeks, the ticketing team gets the credit; the platform team gets the invoice for the clusters and the salaries. A platform in that position is always one budget review away from looking like pure overhead. So the code alone will not keep it alive. Strategy (what to build and what to buy) and communication (how to explain the value to people who never see it directly) decide whether it survives. We will take these in three parts: the map, the money and the message.

The map. Strategy starts with knowing where each capability sits. Chapter 13 laid out an evolution road with four stages: genesis (something new and poorly understood), custom (built by hand, still changing), product (packaged and offered by vendors) and commodity (standard, interchangeable, bought like electricity). Place each of the platform’s capabilities on that road and let its stage set the posture. Commodities such as Kubernetes clusters, message queues and container registries are bought or adopted. Nobody chooses Encore over a rival because Encore runs its queues by hand, so Encore should never try to differentiate on them. The capabilities that are genuinely custom, and worth building, are the ones no vendor sells and that make Encore what it is: the Gate’s fairness engineering, which decides who gets into a sold-out on-sale and in what order, and ticketing’s domain paths. The classic failure is Figure 13.1’s posture lag, now at company scale. The team hand-rolls a commodity (an artisanal, home-built Kubernetes distribution that engineers must nurse by hand) while buying the differentiator off the shelf, so its scarcest engineering attention goes to the one thing that cannot make Encore special.

The money. Once the map says what to build, the platform has to show that building it paid off. The business case is Chapter 11’s arithmetic applied to the platform itself. We measure four things before and after each golden path ships: lead time (how long a change takes to go from commit to production), incidents, unit cost (for example, infrastructure spend per ticket sold) and onboarding time (how long a new engineer or a new service takes to become productive). In practice these usually come from two sources. The first is the DevOps Research and Assessment (DORA) delivery metrics, which track how often and how quickly teams deploy and how often those deployments fail. The second is a developer-experience survey, built on the SPACE framework (satisfaction, performance, activity, communication, efficiency) or the similar DevEx framework, which asks engineers how their work actually feels. Both matter, but they do different jobs. Developer experience tells you how the paths feel to the people walking them, and that is what drives adoption. The hard delivery numbers are what persuade the people holding the budget to renew funding.

Be ready for the numbers to be mixed at first. DORA’s 2024 report found that engineers who used an internal platform reported higher productivity, yet their teams’ delivery throughput and change stability dropped, by roughly 8% and 14%. A plausible explanation is that a new platform adds handoffs and pipeline steps: an extra approval gate, a policy check that blocks a deploy, a migration that pauses normal work. For a while, those costs arrive before the benefits do. The right response is to plan for that dip and say so up front, not to explain it away after it appears. Imagine telling Encore’s finance team that the new paths will speed everything up, and then watching the dashboard show slower releases for the next two quarters. The platform’s credibility would not survive. A business case that promises only upside will be refuted by its own dashboards; a case that predicts the dip and the recovery is confirmed by them.

The message. Numbers alone do not carry a decision through a company, because different people need to hear different things. Chapter 1’s architect elevator, Gregor Hohpe’s image, describes the skill: the architect rides between the engine room, where systems are built, and the penthouse, where strategy and budgets are set, and stops at every floor in between. On each floor the architect states the same platform decision in the language that floor uses. To engineers it is golden paths and guardrails: what they can do with one command, and what they are not allowed to skip. To directors it is delivery predictability: on-sale features land when promised. To the chief financial officer (CFO) it is unit economics: the cost of serving each ticket falls as volume grows. To the board it is a competitive claim: “we ship in days what peers ship in quarters.” Each version is true, and none is the whole truth. The skill lies in choosing the true part that each audience can act on, without bending it into something false. That translation between engine room and penthouse is not a soft skill bolted onto the technical job; it is part of the technical job. At platform scale it often decides the funding, because the people who approve the budget will only ever hear the penthouse version.

One floor of the building is a classroom. The gateway migration of Chapter 13 took hold only when I started teaching it: 20 short sessions over two weeks and a dozen hands-on exercises, after which the team ran the new platform without me. Before the teaching, I was the only person who truly understood how the new gateway worked, so every question and every incident came back to me. After it, the knowledge lived in the team. I now treat teaching as part of the job, not an optional extra after the real work. An architect who cannot teach a decision remains its only operator, and a platform with a single operator is a platform with a single point of failure.

Underneath the map, the money and the message sits systems thinking. Donella Meadows argued that a system’s behavior arises from its feedback structure, that is, from the loops by which its outputs come back around to shape its inputs, more than from any single part. Platform adoption is exactly such a loop. Good paths attract users; users give feedback about what hurts; that feedback improves the paths, which attract more users. When adoption stalls, the tempting fix is to add features. But the weak link in the loop is usually the feedback itself: the platform team has stopped hearing what its users struggle with, so it keeps improving the wrong things. That is why a platform team’s calendar holds more user interviews than a typical product team’s. A product team can watch its customers through analytics; a platform team’s customers are engineers working around its tools in ways no dashboard records, and the only way to find out is to go and ask.

Architecture reviews

The last instrument in the platform architect’s kit is the lightweight design review: a way for significant decisions to be examined before they are made, without turning examination into bureaucracy. The format that survives real calendars is the request for comments (RFC) loop. Someone writes a proposal of one to three pages covering the context, the options considered and the trade-offs chosen, in a shape that can become an ADR once it is accepted. The proposal is circulated asynchronously, so people read it when they have time, not when a meeting is booked. Reviewers comment in writing, on the document itself. The decision is made visibly, so everyone can see what was decided and by whom, and the document is archived permanently. There is no committee and there are no slides. The document is the meeting. And because the archive is written, structured text, it becomes, at no extra cost, the agent context that Section 15.4 described: the record of why that coding agents read before they generate the how. Suppose the Orders & Payments team proposes changing how new payments fail over to the second payment service provider. The RFC states the context, lays out the options and names the trade-off chosen; Gate and ticketing engineers comment on it over two days; the decision is recorded; and the next agent asked to touch the failover code reads that record first.

The name has a history worth keeping. In 1969 Steve Crocker circulated the first Request for Comments among the people building the ARPANET, the research network that became the Internet. He chose the modest title on purpose: the group was young and had no formal authority, and a humble name invited discussion instead of claiming the last word. Keep that tone in your own RFCs. An RFC that reads as a verdict already handed down gets silence, because reviewers conclude that their comments will change nothing. And silence is the one review outcome nobody learns from: the author gets no correction, the reviewers get no understanding, and the flaws surface later, in production.

For bigger decisions, a one-page RFC needs more structure. Here we can borrow the spine of the Software Engineering Institute’s (SEI) Architecture Tradeoff Analysis Method (ATAM), a formal method for evaluating an architecture against the qualities it must deliver. The full ATAM runs over several days with trained evaluators; we keep its central move and drop the ceremony. We walk the design through its driving characteristics, asking one probing question for each:

Applied to every significant change, this review takes about an hour, fits on one page and asks six questions. It beats the quarterly architecture board it replaces, and the main reason is timing. A quarterly board often sees a design after the team has already built half of it, when changing course means throwing work away, so the board’s choice is to approve or to cause a delay. The six-question review happens while the decision is still a proposal and can still change cheaply.

Recap. Place each platform capability on the evolution road, and buy or build according to its stage: adopt commodities, and build only what differentiates Encore. Fund the platform with before-and-after numbers, including the uncomfortable early dip, and describe it on each floor of the elevator in that floor’s language without changing the facts. Teach what you build so that you are not its only operator, and when adoption stalls, fix the feedback loop before adding features. Run design reviews as one-page RFCs written to invite comment, and for bigger decisions add the six characteristic-driven questions.

Exercise 15.5. Take one internal capability your company hand-rolls, such as a deployment tool, a feature-flag service or a home-grown message queue. Place it on the evolution road (genesis, custom, product or commodity) and note why it belongs at that stage. Then write either a two-sentence justification for continuing to build it, explaining what it does that no product or commodity offering could, or a two-sentence plan to migrate it to a commodity.

Kata: The Capstone — Meridian

Everything since Chapter 1 was practice for this. Each earlier kata isolated one discipline: a style, a boundary, a data design, a cost model. This one asks for all of them at once, the way a real job does. Meridian is roughly Encore’s size, with 40 teams, but it is older and messier, and unlike Encore it has not had 14 chapters of careful decisions behind it. You will be building the platform of Section 15.2 for a company that has not yet built the machinery that Encore’s platform packages, such as enforced boundaries, an event backbone and data products.

Your brief: “Meridian.” A business-to-business (B2B) logistics company: 40 product teams (520 engineers), one aging monolith carrying 60% of revenue, and 190 services of widely varying age carrying the rest. Known pains: a new service takes four weeks to reach production; the last audit found three different security postures; every team runs its own CI; data science can’t get clean data; and two teams have each built a shadow AI gateway of their own. The chief technology officer (CTO) has funded a platform organization of 36 engineers (you), with the board’s attention and 18 months of patience. Meridian also sells a customer-facing API and is midway through building a multi-tenant product, “Meridian for Carriers.” You have already met two of its recent acquisitions: Cargo, Chapter 9’s freight forwarder, and Relay, Chapter 11’s locker network. Their architectures arrive with the deal, incident history and all.

Before you begin, read the brief the way Chapter 1 taught you to read a business sentence: as a list of characteristics in disguise. The four-week lead time is a deployability problem. The three security postures are a consistency problem, since an auditor has found that the same question gets three different answers depending on which team you ask. The separate CI pipelines and the two shadow gateways are the same symptom seen twice: when no shared road exists, every team paves its own, and the company pays for the same road many times over. And the 18 months of patience is a constraint like any other. It tells you that the platform must show measurable results well inside that window, or it will not be funded for a second one.

Deliverables — the full architect’s dossier:

1. Platform strategy — a capability map postured in Wardley’s terms: each capability placed on Chapter 13’s evolution road (genesis, custom, product, commodity), with its stage deciding whether you buy, adopt or build it. From Meridian’s pains, choose the thinnest viable platform, and sequence the first three golden paths by pain you have measured, not pain you assume.
2. Platform architecture — a design as detailed as Figure 15.2, showing the control plane, the planes beneath it, the registry and the scorecards; plus C4 diagrams that mark where trust changes hands (Chapter 10’s trust boundaries).
3. Golden-path specifications — the “new service” and “new data product” paths, end to end: what the template contains, what the provisioning workflow creates, which guardrails a team inherits without asking, and the single command that runs it all.
4. Governance design — the catalog of fitness functions, three admission policies, the priced exception path, and the deprecation playbook for the long tail of 190 services.
5. Migration roadmap — the monolith strategy (per Chapter 3: what gets strangled, and what stays); the consolidation of the two shadow AI gateways; the convergence of the carrier product’s tenancy machinery with the internal control plane; and plans to bring Cargo’s data products and Relay’s ingestion fleet onto the platform’s paths. Your kata answers from Chapters 9 and 11 are admissible evidence.
6. The economics — how the 36 platform engineers are organized into teams, the before-and-after metrics that will renew funding at month 18, and the instrumentation that measures unit economics.
7. The elevator narrative — one page with four floors: the same platform described to engineers, to directors, to the CFO and to the board.

A word on why these seven belong together. Each answers a different reader’s question. The strategy says what you will build first and why. The architecture and the path specifications say how it works, in enough detail that an engineer could start on Monday. Governance says how the platform stays correct after you stop watching it. The roadmap says how Meridian’s existing estate, which no one can switch off, gets from here to there. The economics say why anyone should keep paying for it, and the narrative says the same thing to people who will never read the rest. A dossier missing any one of them leaves some reader without an answer, and at platform scale an unanswered reader is usually the one who controls the budget.

Rubric — the book’s final examination:

Where you now stand — a graduation note

The preface made a second claim alongside its first: that architecture is a continuing stream of trade-offs, made under uncertainty, written down and revisited when the facts change. You now hold the whole chain that claim was pointing toward. It runs from characteristics through styles, boundaries, distribution, fleets, events, promises, pixels, data, defense, operations, intelligence, economics and tenancy, and arrives at platforms. Holding it together is a single habit: name what it costs, in ink. Every link in the chain was a decision with a price, and in every chapter the work was to see that price clearly and write it down where others could find it.

Looking back along that chain, I see one adversary in every chapter, and its name is complexity. Some of it is essential, because concerts, seats and payments are genuinely intricate; much of it is of our own making, the accidental complexity of choices we could have made more simply. Our weapons against it never changed either. We abstracted, so that a team could use what it did not need to understand: a ticketing team calls the seat ledger without knowing how its five replicas reach agreement. We decomposed, so that a change would land in one place instead of five. And we built hierarchies, so that 40 teams could stand on a control plane without needing to see what lies beneath it. Every chapter applied those three moves to a new kind of problem.

That is why the arrival of capable tools changes less than it seems to. The tools now produce the how, faster than any of us. What they do not produce is the why with someone accountable for it: which trade-off was chosen, for which characteristic, at what cost, written down where the next person can find it. And the why matters most at the edges of a system. Systems tend to fail at their boundaries, where one component’s assumptions meet another’s, and those boundaries are drawn by judgment, not generated by a tool. That judgment is now yours: practiced on Encore, tested on 14 katas, and about to be defended at Meridian.

Go draw good boundaries. And write down why.

References

• Google Cloud DORA — Accelerate State of DevOps Report 2024. Google Cloud, 2024 — free online.
• Camille Fournier, Ian Nowland — Platform Engineering. O’Reilly, 2024.
• Diana Montalion — Learning Systems Thinking. O’Reilly, 2024.
• Sarah Wells — Enabling Microservice Success. O’Reilly, 2024.
• Christian Ciceri, Dave Farley, et al. — Software Architecture Metrics. O’Reilly, 2022.
• Neal Ford, Rebecca Parsons, Patrick Kua, Pramod Sadalage — Building Evolutionary Architectures, 2nd ed.. O’Reilly, 2022.
• Will Larson — Staff Engineer: Leadership Beyond the Management Track. Self-published, 2021 — free online.
• Gregor Hohpe — The Software Architect Elevator. O’Reilly, 2020.
• Will Larson — An Elegant Puzzle: Systems of Engineering Management. Stripe Press, 2019.
• Eben Hewitt — Technology Strategy Patterns. O’Reilly, 2018.
• Donella H. Meadows — Thinking in Systems: A Primer. Chelsea Green, 2008.
• Matthew Skelton, Manuel Pais — Team Topologies, 2nd ed.. IT Revolution, 2025.
• Simon Wardley — Wardley Maps — free online.