Architecture

This section is the macro counterpart to Code Craft. Where Code Craft asks "how do I write this line well?", Architecture asks "how should the whole system be put together?" — and the answers live above any specific language, framework, or vendor.

The material here is deliberately technology-agnostic. Concrete tooling — Kafka, Kubernetes, Redis, Postgres — lives under infrastructure/ and database/. This section is about the ideas that survive the next platform migration.

Topics

Distributed Systems

The theory and mechanisms that make multi-node systems correct: CAP, consensus, consistency models, ordering, idempotency, distributed transactions, leader election. If your problem has more than one process, this is the math you cannot escape.

Software Architecture

The styles and patterns for organizing services and code: microservices vs monolith, DDD and bounded contexts, event-driven, CQRS / event sourcing, Clean / Hexagonal layering, BFF. These are design choices — you can pick a different flavor and still ship.

Comparison

Side-by-side comparisons of architectural tools and platforms — workflow orchestration, eventing, and other tooling where the choice itself is an architectural decision.

How These Relate

A useful distinction when something feels like it belongs to both:

If it has a proof or an invariant, it's distributed systems. If it's a way to organize code or services, it's software architecture.

Saga, for example, lives in two places: as a protocol (compensation correctness) in distributed systems, and as a pattern (long-running business workflows) in software architecture.

Scope and Boundaries

How to Read This Section

The two subsections are independent: you can read either without the other and get value. But the topics relate, and which one you start with depends on what you are trying to do.

If You Have Time for One Page

• Starting from scratch in software architecture? Read Software Architecture › Monolith. The default that more systems should have stayed.
• Starting from scratch in distributed systems? Read Distributed Systems › Consistency Models. Every other distributed-systems conversation assumes its vocabulary.

Reading Tracks by Goal

Different starting points use different parts of the chapter. Pick the track whose premise matches yours.

Track A — Designing a new system. Greenfield project, choosing a starting shape.

1. Software Architecture › Monolith — the default; understand it before splitting.
2. Software Architecture › Modular Monolith — the underrated middle ground for most systems.
3. Software Architecture › DDD Strategic Design — bounded contexts decide where your modules go.
4. Software Architecture › Conway's Law — check your team structure supports your architecture.
5. Software Architecture › Anti-Patterns — read this before making the mistakes, not after.

Track B — Splitting an existing monolith. Operational pain has built up; thinking about service extraction.

1. Software Architecture › When to Split — the decision itself, with real vs false signals.
2. Software Architecture › Microservices — what you're committing to and what it costs.
3. Distributed Systems › Idempotency — the everyday tool you'll use at every boundary.
4. Software Architecture › Outbox Pattern — the reliable bridge between database and message bus.
5. Software Architecture › Saga Pattern — multi-service workflows once you've split.

Track C — Building a service that calls other services. Designing or reviewing a new microservice.

1. Distributed Systems › Idempotency — make every external call safe to retry.
2. Distributed Systems › Exactly-Once Semantics — what your messaging layer cannot give you, and what to do instead.
3. Software Architecture › Event-Driven Architecture — the three flavors, and how to pick.
4. Software Architecture › Saga Pattern ↔ Distributed Systems › Saga Protocol — read both sides of saga.
5. Software Architecture › Anticorruption Layer — keep external models from polluting yours.

Track D — Operating distributed infrastructure. On-call for a Kafka, etcd, Cassandra, or similar cluster.

1. Distributed Systems › Failure Models — the taxonomy you need before any post-mortem.
2. Distributed Systems › CAP & PACELC — decode the trade-off you're operating against.
3. Distributed Systems › Raft or Paxos — whichever your cluster runs.
4. Distributed Systems › Leader Election — the single most common source of incidents.
5. Distributed Systems › Membership & Failure Detection — why your cluster thinks a healthy node is dead.

Track E — Picking a database, broker, or workflow engine. Evaluating vendors; trying to decode marketing claims.

1. Distributed Systems › CAP & PACELC — read CP/AP labels honestly.
2. Distributed Systems › Consistency Models — when "strongly consistent" is meaningful.
3. Distributed Systems › Quorum Systems — what R + W > N does and does not give.
4. Distributed Systems › Exactly-Once Semantics — what brokers actually deliver.
5. Comparison › Inngest vs Trigger.dev — for the specific workflow-engine question.

Track F — Diagnosing a system that is not working. The existing architecture has stopped serving the team well.

1. Software Architecture › Anti-Patterns — the diagnostic catalogue.
2. Software Architecture › Conway's Law — many architectural problems are organizational.
3. Distributed Systems › Failure Models — many "weird production issues" are unnamed failure classes.
4. Software Architecture › When to Split — applies both ways: when to split, and when to recombine.

Cross-Chapter Pairs to Read Together

Some topics deliberately split between the two subsections, with a different angle on each side:

If something feels like it belongs in both places, it usually does — read both.

Practitioner Reality Check

A short list of pages that show up in day-to-day engineering work more than the others:

• Idempotency — used in every cross-service call.
• Consistency Models — used in every "is this safe?" conversation.
• CAP & PACELC — used to decode every database's marketing page.
• Failure Models — used in every post-mortem.
• Monolith + When to Split — used in every "should we go to microservices?" conversation.
• Conway's Law — used in every "why doesn't our architecture match the org chart?" conversation.
• Anti-Patterns — used to diagnose what your team is in the middle of doing wrong.

The rest are tools you pull off the shelf when a specific problem calls for them.