Architecture practice: from capability maps to katas

13.1 Enterprise architecture toolkit Added

A small set of tools that turn "what does the business do, and what runs it?" into pictures and decisions: capability maps, value streams, portfolio rationalisation, roadmaps, a technology radar and principles.

Heat-mapping a capability map

Colour each capability by one measure at a time: business value, technical health, risk, cost or number of applications. Always show the legend and the data source.

Portfolio rationalisation: the TIME model (Gartner)

Current → transition → target

13.2 Quality attributes & trade-off analysis Added

Quality attributes (the "-ilities") shape an architecture more than features do. Make them measurable with scenarios, rank them in a utility tree, test the design against them in a workshop, and guard them with automated fitness functions.

ISO/IEC 25010:2023 product quality model

The 2023 edition has nine characteristics. Usability became interaction capability, portability became flexibility (now including scalability), and safety is new.

Quality-attribute scenarios

"Must be fast" can't be tested. A six-part scenario can. Write NFRs this way (see NFRs in 12.9).

Utility tree

A tree from "utility" to attributes, refinements and concrete scenarios. Rate each scenario (importance, difficulty) as H/M/L, then analyse the (H,H) ones first.

ATAM-lite in a workshop

ATAM (Architecture Tradeoff Analysis Method) comes from the SEI. The full method takes days. A "lite" version fits in half a day with architects, product owner, ops and security.

Fitness functions

Automated checks that keep a quality attribute from silently getting worse. They run in CI/CD or on a schedule (also see 12.15).

13.3 Cloud migration strategies: the 7 Rs Added

Pick one strategy per workload, move workloads in waves onto a landing zone that is already in place, and treat every cutover as a rehearsed, reversible event followed by hypercare.

AWS advises against refactoring during a large migration: rehost, relocate or replatform first, then modernise once the workload is stable in the cloud.

Cutover planning

13.4 Legacy & mainframe modernisation Added

Modernise legacy and mainframe systems in small, reversible steps: wrap them with APIs, stream their changes out as events, move capabilities one at a time, and prove each step with reconciliation before switching anything off.

Gartner's seven options, from least to most change

Patterns that work together

Managing the risk

13.5 Team & org architecture Added

Systems end up shaped like the teams that build them, so design team boundaries, team interactions and cognitive load together with the software architecture.

Team Topologies (Skelton & Pais, 2019)

Cognitive load

A team can only own as much as it can understand. Three kinds: intrinsic (the problem itself), extraneous (tooling and process friction) and germane (learning the domain). Platforms should remove extraneous load. Signs of overload: slow onboarding, constant hand-offs, nobody understands a service fully.

Platform engineering & internal developer platforms

Deep dive: 13.9 Platform engineering.

13.6 API & event evolution Added

Change APIs and event schemas without breaking consumers: prefer additive changes, know your compatibility mode, version only when you must, and retire old versions with clear Deprecation and Sunset signals.

Versioning strategies

REST basics are in 08.2; gateway versions vs revisions are in 09.5.

Compatibility, in plain words

Deprecation and Sunset

• Deprecation header, RFC 9745 (March 2025, Standards Track): the date it was or will be deprecated, as @ + Unix seconds. Link to docs with rel="deprecation". Behaviour doesn't change.
• Sunset header, RFC 8594 (2019, Informational): the HTTP date after which it may stop responding. Must not be earlier than the deprecation date.
• Watch usage per consumer, contact the stragglers, then return 410 Gone after sunset.

HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Wed, 30 Jun 2027 23:59:59 GMT
Link: <https://developer.example.com/payments/v1-retirement>; rel="deprecation"

Event schema evolution with a schema registry

Schema registries and data contracts are also covered in 10.3 and 07.8.

builder.Services.AddApiVersioning(o =>
{
    o.ReportApiVersions = true;   // api-supported-versions / api-deprecated-versions
    o.ApiVersionReader = new UrlSegmentApiVersionReader();
    o.Policies.Sunset(1.0)        // adds Sunset + Link headers to v1 responses
        .Effective(new DateTimeOffset(2027, 6, 30, 23, 59, 59, TimeSpan.Zero))
        .Link("https://developer.example.com/payments/v1-retirement")
            .Title("Payments v1 retirement")
            .Type("text/html");
});

var app = builder.Build();
var payments = app.NewVersionedApi("Payments");

var v1 = payments.MapGroup("/v{version:apiVersion}/payments")
                 .HasDeprecatedApiVersion(1.0);
v1.MapGet("/{id}", (string id) => Results.Ok(new { id, amount = 10.50m }));

var v2 = payments.MapGroup("/v{version:apiVersion}/payments")
                 .HasApiVersion(2.0);
v2.MapGet("/{id}", (string id) =>
    Results.Ok(new { id, amount = new { value = 10.50m, currency = "AUD" } }));

13.7 Front-end & edge architecture Added

Choose where the HTML is built (browser, server, build time or a mix), put a BFF and a gateway between clients and services, push cacheable work to the edge, and design mobile apps to keep working offline.

Rendering options

Mobile offline-first sync

Banking: never execute a payment offline. Queue the intent, show it as pending, and confirm it online with an idempotency key (08.7).

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();

var app = builder.Build();
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof(Client._Imports).Assembly);

// In a component: static SSR by default, opt in per page
// @rendermode InteractiveAuto

13.8 Reference architectures & architecture katas Added

Reference architectures give you a proven starting point; architecture katas give you practice. Start from a published design, then rehearse requirements, characteristics and trade-offs against the clock.

Where to find reference architectures

Architecture katas

Created by Ted Neward: a short brief from a fictional client, a small team, a fixed time box, then a presentation and critique. Like a coding kata, the point is repetition: you get better at trade-offs by making many of them.

Kata prompts for banking and payments are in Section 25; the interview framework is in 20.2.

13.9 Platform engineering and internal developer platforms Added

An internal developer platform (IDP) is a self-service product, built by a platform team for developers, that makes the secure, compliant way to build and run software also the easiest way.

From ticket-ops to self-service

How it works

How to measure it

When to use / when not

// content/GoldenPath.Api/.template.config/template.json
{
  "$schema": "http://json.schemastore.org/template",
  "author": "Platform team",
  "classifications": ["Web", "API", "GoldenPath"],
  "identity": "Acme.GoldenPath.Api",
  "name": "Golden-path API (logging, health, OTel, CI)",
  "shortName": "gp-api",
  "sourceName": "GoldenPath.Api",
  "tags": { "language": "C#", "type": "project" }
}

// The template also ships an Aspire AppHost for local dev
var builder = DistributedApplication.CreateBuilder(args);
var db = builder.AddPostgres("pg").AddDatabase("appdb");
builder.AddProject<Projects.GoldenPath_Api>("api")
       .WithReference(db).WaitFor(db);
builder.Build().Run();

// Developers:  dotnet new install Acme.GoldenPath.Templates
//              dotnet new gp-api -n Payments.Api