---
title: "Architecture and design principles"
chapter: "05"
---

# Architecture and design principles

Principles are decision heuristics, not laws. Apply them to the forces in context and record exceptions. A principle that cannot change a decision or be checked is only a slogan.

## Core ideas and patterns

| Idea | What it solves | Cost, limit, or warning |
|---|---|---|
| **Separation of concerns** | Places independently changing concerns behind boundaries | Excessive separation creates indirection |
| **High cohesion** | Keeps related behavior and data together | Cohesion depends on the reason for change |
| **Low coupling** | Limits knowledge and change propagation | Some coupling is essential; make it explicit |
| **Information hiding** | Hides volatile decisions behind stable interfaces | Leaky abstractions export hidden complexity |
| **Single responsibility** | Gives a unit one primary reason to change | Tiny classes/services can fragment a cohesive model |
| **Open/closed and dependency inversion** | Allows extension around stable policies | Premature abstraction increases cost |
| **DRY** | Maintains one authoritative representation of knowledge | Similar code may represent different domain rules |
| **KISS and YAGNI** | Prefer the simplest sufficient design | Simple is measured against required qualities, not line count |
| **Least privilege and secure defaults** | Restrict authority and start safe | Operational escape paths still need governance |
| **Fail fast and graceful degradation** | Expose invalid state early while preserving bounded service | Fail-fast at the wrong boundary creates outages |
| **Idempotency** | Makes repeated intent safe | Requires stable identity and retention policy |
| **Mechanism versus policy** | Separates reusable capability from changing rules | Policy still needs clear ownership |

## How to apply it

Turn principles into local questions: What changes together? Who owns this truth? What authority is needed? What happens on repetition? Which policy will vary? What is the smallest boundary that contains the invariant? Apply principles at code, service, data, infrastructure, and organization levels.

## Evidence, not opinion

Use dependency checks, architecture tests, ownership rules, API compatibility tests, privilege reviews, duplicate-request tests, and change-coupling metrics. Record justified exceptions in ADRs.

## Small example

A shared “customer” library violates DRY less than it appears: billing and support may use the same fields but different meanings and lifecycles. Separate domain models preserve knowledge even when code repeats.

## Feynman check

Explain the design to a new engineer without using the pattern names. State the
problem, the forces that conflict, the chosen boundary or mechanism, what can
fail, and the evidence that would prove the choice still works.