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.