Skip to the content
Software Made Clear
About

Architecture · 8 nodes

Architecture in the real world

Boundaries, transactions and the organisational reasons behind both. Every node here came out of a system that was already running when I arrived.

Browse the reading order
Is this path right for me?

ASSUMES

That you have worked in a codebase you did not start, and it hurt.

GIVES YOU

A vocabulary for arguing about boundaries without reaching for a framework.

LEADS TO

Distributed basics, once the boundaries have a network between them.

Nothing is tracked and nothing is locked — the map exists so you can see where an article sits.

Suggested start Written Not written yet Optional or subtopic

  1. NODE 01 · REQUIRED Suggested start

    Where the boundaries are

    See how bounded contexts keep different meanings separate, translate external API facts at the edge, and avoid a shared model that spreads confusion.

    • Ubiquitous language
    • Context maps

  2. NODE 02 · REQUIRED Written

    Transaction boundaries

    Choose which changes must commit together, keep remote calls outside local transactions, and test the failure gap with an interactive outbox example.

    • Unit of work
    • Aggregate size

  3. NODE 03 · REQUIRED Written

    Events, and what they promise

    Find out what an event actually guarantees once it leaves the service that raised it, and which of those promises the consumer has to absorb itself.

    • At-least-once
    • What the consumer must tolerate

  4. NODE 04 · REQUIRED Written

    Idempotency keys and safe retries

    Give every retry a key, store its result in the same transaction as the effect, and stop worrying whether a lost response means the work happened twice.

    • Idempotency keys
    • Replay windows

  5. NODE 05 · OPTIONAL Written

    When a broker is the wrong answer

    See three real systems that reached for a queue to patch a missing transaction boundary, and what broke later because a broker cannot supply one.

    • Queues as coupling
    • Backpressure

  6. NODE 06 · REQUIRED Written

    Strangler-fig migration

    Replace a running production system without stopping it, and see the routing and data-ownership decisions that actually determine whether it survives.

    • Routing at the edge
    • Data ownership

  7. NODE 07 · REQUIRED Written

    Writing the decision down

    Record why an architecture choice was made, which assumptions could change it, and when to review it without rewriting the history of the decision.

    • Decision records
    • Diagrams that survive

  8. NODE 08 · OPTIONAL Written

    Configuration across deployments

    Keep one build while changing deployment settings. Try missing values and a preview pointing at production, then review secret delivery and rotation.

    • Code vs config
    • Secrets and rotation