Skip to content

Architecture Frameworks

The tools and habits I rely on when making, validating and communicating an architectural decision. None of them is heavyweight: the aim is to get the value of the practice without the ceremony.

Decision-Making

Section titled “Decision-Making”

Trade-off Analysis means making the options and the competing quality attributes explicit, rather than leaving the trade-offs implicit. I rarely go as far as a formal weighted matrix. Depending on the decision, I’ll use a spike to test an option in code, a whiteboard session to work through the options with the team, or, where the audience is less technical, a conversation with stakeholders framed in terms of outcomes and risk (see Stakeholder Communication). Watch out for: a heavyweight process applied to every decision, which turns analysis into paralysis (see Avoid Paralysis by Analysis).

Architecture Decision Records (ADRs), popularised by Michael Nygard, are short documents that capture a single decision (its context, the decision itself, and its consequences) so the reasoning survives past the people who made the call. An ADR is never rewritten; a changed decision gets a new one that supersedes it (see Documenting Architecture Without It Going Stale). As a small team, we don’t write them as often as I’d like, but a significant or hard-to-reverse decision should always have one. Watch out for: writing them after the fact as justification, rather than at the point of decision.

Validating & Evolving

Section titled “Validating & Evolving”

Fitness Functions are automated checks that continuously verify an architectural characteristic still holds: for example, a build rule enforcing Clean Architecture’s dependency direction, or an ArchUnitNET rule stopping one module depending on another it shouldn’t. The term comes from Neal Ford, Rebecca Parsons and Patrick Kua’s Building Evolutionary Architectures. See Use the Compiler to Enforce Dependency Rules for how I apply this. Watch out for: fitness functions that only report, or run manually, rather than failing the build.

Communicating

Section titled “Communicating”

C4 Model (Context, Container, Component, Code), created by Simon Brown, is a set of levelled diagrams for communicating a system’s structure to different audiences, from a Context diagram for stakeholders who need the big picture down to a Code diagram for an engineer working in one module. Alongside whiteboard sketches, it’s usually all the diagramming I need (see The Code Is the Model). Watch out for: diagrams that drift out of sync with the system (see Documenting Architecture Without It Going Stale).

References

Section titled “References”