Cheat sheet: Software architecture

What software architecture is

“Load-bearing walls, with a note taped on”

Architecture is the parts that everything else rests on, and the note says why each wall is there.

Avoid

• Architecture as a technology list
• Splitting code but not data
• No recorded reasons

The architect's role

“Wide, not deep; near the code, not in its way”

Know a little about a lot, stay close to the code, and never be the thing the team waits for.

Avoid

• Owning critical-path code
• The ivory tower
• Recommending what you know

Negotiating, presenting and leading

“Translate, divide, demonstrate”

Turn demands into costs, split them into the parts that need them, and let evidence settle disputes.

Avoid

• Accepting buzzwords as requirements
• The rule without the reason
• The control freak and the armchair architect

Identifying architecture characteristics

“Not a feature, shapes the structure, can't live without it”

The three tests every characteristic must pass. Then keep only the top three.

Avoid

• Supporting everything
• Confusing scalability with elasticity
• Forgetting feasibility

Defining and measuring characteristics

“No number, no characteristic”

Every top characteristic gets a measure, a percentile or a rate, and a condition.

Avoid

• Headroom for a burst
• Averages as targets
• Measuring only the servers

Trade-off analysis

“Weigh, don't count”

A scorecard counted out of context is precise and wrong. Weight every criterion by this system's needs.

Avoid

• The out-of-context scorecard
• Analysis paralysis
• Only two options

Modularity, cohesion and coupling

“Things that change together, live together”

That's cohesion. And the more things lean on a part, the more stable and abstract it must be.

Avoid

• The shared kernel of everything
• Train-wreck calls
• Splitting by technical type

Inside a service: SOLID, patterns, hexagonal

“Plugs point in”

Business rules own the sockets; every database, vendor and test is a plug that points inwards.

Avoid

• Ports shaped like the vendor
• Interfaces everywhere
• The anemic domain

Finding the components

“Name components after verbs, not nouns”

Enrolment, checkout, publishing: things the system does. Not Student, Course, Payment: things it stores.

Avoid

• The entity trap
• Code in parent namespaces
• One giant "core" component

Domain-Driven Design: strategic design

“Where the word changes, the border goes”

Draw a bounded context wherever the same word starts to mean something different, and translate at the border.

Avoid

• Contexts per entity
• DDD tactics without strategy
• The accidental conformist

Domain-Driven Design: tactical design

“One box, one key, numbers for the rest”

An aggregate is changed in one transaction through its root; everything outside it is referenced by ID and updated by events.

Avoid

• Aggregates as table joins
• Bypassing the root
• Calling slow systems inside the transaction

Architecture quantum and the domain

“Shared pipes, one house”

Share a database or wait on a call, and two services become one quantum.

Avoid

• The distributed monolith
• Synchronous calls across different characteristics
• One enterprise-wide model

Teams and architecture

“The kitchen shapes the dish”

The way teams are split and talk is the way the system will be split and talk; design both together.

Avoid

• Microservices without the teams
• Shared ownership
• Permanent collaboration

Monolithic vs distributed

“Every arrow is a phone call”

In a distributed design, each arrow can be slow, fail, be overheard or reach the wrong place. Price every one.

Avoid

• Retries without idempotency
• Chatty calls across the network
• Hard-coded addresses

Layered and modular monolith

“Floors or shops”

Layers split by technical job (floors of a department store); modules split by business area (shops in a centre). Both share one building.

Avoid

• Unenforced boundaries
• Ignoring the sinkhole
• Shared tables everywhere

Microkernel

“Console and cartridges”

A stable console, a standard slot, and games that come and go without opening the box.

Avoid

• A contract that leaks
• Plug-ins depending on plug-ins
• No isolation

Service-based and SOA

“Few big departments, one records room”

Service-based: a handful of independent departments sharing one set of records. Reuse everything, and you get SOA's tangle.

Avoid

• One entity library for everything
• Services calling services
• Too many services

Event-driven architecture

“Shout what happened, don't say what to do”

Events are past-tense facts broadcast to whoever cares. Commands go to one receiver.

Avoid

• No error strategy
• Anemic events
• The swarm of gnats

Space-based architecture and caching

“A fridge at every bar”

Each unit serves from its own memory and tells the others what changed; the storeroom catches up later.

Avoid

• Ignoring collisions
• Unbounded data in memory
• Forgetting the pump

Microservices

“Own your stock, use the front door”

Every service owns its data; everyone else comes in through its API or listens to its events.

Avoid

• The distributed monolith
• Too fine, too early
• Business logic in shared libraries

Pipeline and serverless

“Stations in a line, machines on demand”

A pipeline is independent stations joined one way; serverless switches the machines on only when a car arrives.

Avoid

• Unbounded fan-out into a fixed resource
• Functions calling functions synchronously
• A pipeline with hidden side doors

Choosing and combining styles

“Characteristics choose, constraints veto”

The top characteristics shortlist the styles; team, budget and domain rule some out.

Avoid

• Style first, characteristics later
• Ignoring team capacity
• The big-bang rewrite

Frontend architecture: micro-frontends, BFF and rendering

“One storefront, many departments”

Customers see one shop; teams own their own departments, each with its own stockroom (BFF).

Avoid

• Micro-frontends as a fashion
• Horizontal splits
• Shared global state

Integration styles

“Post, cabinet, phone, in-tray”

The four ways offices share information, and the four integration styles: file, shared database, RPC, messaging.

Avoid

• Integrating through another system's tables
• Non-idempotent file imports
• Synchronous calls to unreliable partners

Synchronous vs asynchronous

“Wait only for what you need to show”

If the next screen needs the answer, wait for it. Everything else is a note left for later.

Avoid

• Synchronous chains
• Replies without correlation IDs
• Aggressive polling

Messaging patterns

“Hand in, store, deliver: guard all three”

A message can be lost at each step. Confirm the send, persist the store, acknowledge after the work.

Avoid

• Acknowledge, then process
• Global ordering by accident
• Poison messages

Orchestration and choreography

“Conductor or dance floor”

A conductor knows the score and stops the music on a mistake; a dance floor scales but nobody sees the whole room.

Avoid

• No failure design
• The god orchestrator
• Hidden choreography

Resilience and observability

“Trip the breaker, label the fuse box”

Contain failures with breakers, timeouts and bulkheads; make them findable with logs, metrics and traces.

Avoid

• No timeouts
• Retry storms
• One shared pool

Cloud-native architecture and cost

“Any taxi, meter running”

Build so any instance can be replaced at any moment, and design knowing the meter is always on.

Avoid

• Lift and shift, then surprise
• Optimising before measuring
• Ignoring data transfer

AI and LLM components in an architecture

“Gate it, ground it, guard it, grade it”

A gateway in front, retrieval for facts, guardrails around, evals to measure.

Avoid

• No evals
• Provider SDKs everywhere
• Retrieval that ignores permissions

Data in distributed architectures

“One writer, many readers, never through the back door”

Every table has one owner that writes it. Everyone else reads through its API, its events, or a copy built from them.

Avoid

• Reporting through the back door
• CQRS everywhere
• Lazy migration with no end

Analytical data architecture

“Food hall, not central kitchen”

Each domain cooks and serves its own data as a product; the hall provides the kitchen equipment and enforces the hygiene rules.

Avoid

• The data swamp
• Pipelines that read private tables
• Mesh as a reorganisation

Distributed transactions and sagas

“Book, book, fail, cancel, cancel”

A saga moves forward one commit at a time, and on failure walks back, undoing each in reverse.

Avoid

• Irreversible steps first
• Non-idempotent compensations
• No home for stuck sagas

Contracts and versioning

“Add, don't change; read only what you need”

Producers add; consumers tolerate. Everything else needs expand and contract or a new version.

Avoid

• In-place breaking changes
• Strict consumers of growing contracts
• Version sprawl

Fitness functions and governance

“If it isn't checked, it isn't true”

Every important architecture decision gets an automated check, or it will quietly stop being true.

Avoid

• Rules without checks
• Flaky fitness functions
• Only triggered checks

Architecture decisions and ADRs

“Write down the why, and the price”

Every significant decision gets its reasons and its costs recorded where the next person will look.

Avoid

• Only the outcome
• One-sided consequences
• No compliance

Assessing architecture risk

“Score alone, argue together”

Rate risks individually, then let the disagreements lead the conversation.

Avoid

• Ignoring unknowns
• Group anchoring
• Lists without decisions

Security architecture

“Badge at every door”

Every request proves who it is and what it may do, every time, wherever it comes from.

Avoid

• Trusting the internal network
• Shared credentials
• Security as the last review

Analysing an existing architecture

“Survey the house, not the brochure”

Measure the code and its history; the diagram is what someone hoped the system would be.

Avoid

• Analysing only the present
• Metrics as targets
• Refactoring cold code

Managing technical debt

“Borrow on purpose, repay where you walk”

Take debt deliberately and write it down; pay it back in the code you change most, where the interest is highest.

Avoid

• Debt as a synonym for "code I don't like"
• The once-a-year clean-up
• Hiding the shortcut

Migration, refactoring and roadmaps

“One floor at a time, hotel stays open”

Migrate in slices behind a routing layer, each slice in production before the next begins.

Avoid

• The elephant migration
• Technical justification only
• Forgetting to finish

Architecture antipatterns

“Name it to notice it”

Antipatterns hide because each step feels reasonable. A name lets the team see the pattern.

Avoid

• No decisions at all
• Pattern collecting
• Scars as rules

Diagramming and documenting

“Title, key, labels, one zoom level”

Four checks before any diagram leaves your hands.

Avoid

• Unlabelled arrows
• Mixed levels
• No key

Enterprise architecture

“Plan the roads, not the houses”

Enterprise architects decide what connects systems and what must be common; teams design inside.

Avoid

• Modelling before acting
• Standards without reasons
• Ignoring interfaces

Technology strategy and economics

“Build your edge, buy the rest”

Spend engineers only on what makes the business different; buy products and rent commodities for everything else, and look again as the market moves.

Avoid

• Building commodities
• First-year thinking
• Portability everywhere

From senior engineer to architect

“Write it, pre-wire it, ride the elevator”

Put the reasoning in a document, win the key people one at a time before the meeting, and translate the decision for every floor, up and down.

Avoid

• Still the best coder on the team
• Surprising people in meetings
• One language for everyone

An ADR that avoided a lock-in trap

Lessons

• Lock-in hides in features, not only in APIs
• The advice process found what the authors couldn't
• Write the drivers down
• Must-haves are knockouts, not weights

Replacing a review board that slowed everyone down

Lessons

• Review early and with context, or not at all
• Seek advice, not permission
• Tier by reversibility and reach
• Make "who is affected" findable

Spotify: Backstage and golden paths

Lessons

• Platforms reduce cognitive load
• Make the right thing the easy thing
• A catalogue with owners is governance infrastructure
• Golden State is a fitness function for drift

From zero to a million users: one startup's cloud bill

Lessons

• Project the bill in the design doc
• Tag from day one
• Runaway costs are architecture-shaped
• Count the people before leaving serverless

Prime Video: from serverless to one process

Lessons

• Logical and physical architecture are separate decisions
• Distribution has a price per hop
• Per-operation pricing scales with chattiness, not with value
• It's one service, not a verdict

37signals leaves the cloud

Lessons

• Elasticity is a characteristic you pay for
• Capex against opex
• The facts made it work
• Commitments delay savings

Segment: back from microservices

Lessons

• Solve the real problem at the right level
• Shared libraries across services are a hidden monolith
• Granularity has a cost per service
• The enabler was a test suite, not an architecture

Shopify: the modular monolith

Lessons

• Modularity and distribution are separate decisions
• Organise by domain, not by technical layer
• A boundary that isn't checked isn't a boundary
• Watch the dependency graph, not just the interfaces

Uber: domain-oriented microservices

Lessons

• Bounded contexts above services
• Give dependencies a direction
• Extension points beat shared code edits
• Interfaces absorb churn

GitLab's 2017 database outage

Lessons

• A backup you haven't restored is a hope
• Replicas are not backups
• Failure alerts need a channel that works
• Ownership is architecture

Netflix: active-active across regions

Lessons

• Active-active is a data decision first
• No cross-region calls on the user's path
• Failover you don't exercise doesn't work
• RTO is the sum of the slowest steps

Health data across India and the US

Lessons

• Find where each requirement really comes from
• Data stays, access travels
• Disaster recovery has a country too
• Cells limit the blast radius of everything