Clean Architecture

Source code dependencies can only point inward — nothing in an inner circle can know anything about an outer circle, keeping the business core stable and reusable.

The database, web layer, and frameworks are delivery mechanisms — a good architect postpones these decisions and keeps business rules independent to avoid a costly technology marriage.

Tying business logic to specific I/O devices is a costly mistake — architecture should be agnostic to whether data comes from cards, terminals, files, or APIs.

Source code dependencies should point only to abstractions — Abstract Factories create the architectural boundary between volatile concrete code and stable policy.

With interfaces, architects make source-code dependencies point against the control flow, granting absolute power over module coupling.

Architecture is important but rarely urgent. Developers must defend good structure against short-term business pressure.

Entities hold critical business rules that exist across the enterprise; Use Cases orchestrate application-specific flows and are isolated from UI and database changes.

Functional programming disciplines assignment. Immutability eliminates race conditions, deadlocks, and concurrent update issues at the architectural level.

Design and architecture are the same thing — their true measure is the effort required to meet client needs while minimizing lifetime cost.

Split hard-to-test from easy-to-test behavior — the Presenter prepares all logic into a testable ViewModel; the View is a humble object that only renders what it receives.

The best architecture fails without disciplined use of access modifiers — the compiler is your strongest ally in enforcing Clean Architecture rules across the team.

Interface Adapters convert data between the format use cases understand and the format external systems need — boundaries are always crossed with simple DTOs, never raw entities or DB rows.

Don't depend on things you don't use — fat interfaces force unnecessary recompilation, coupling, and vulnerability to failures in unrelated code.

A good architect maximizes the number of decisions not yet made — separating policy from details so database and framework choices can be postponed until more is known.

Separate what changes at different rates — UI, application business rules, domain business rules, and database each change for different reasons and should be horizontal layers.

Subtypes must be substitutable for their base types — LSP violations at the architectural level force expensive special-case logic into the design.

Main is the dirtiest, lowest-level component — the entry point that wires all dependencies and hands control to the clean architecture above it.

Components should balance Abstraction (A) and Instability (I) — the Pain Zone (stable+concrete) and Uselessness Zone (abstract+unstable) are architectural anti-patterns to avoid.

Software artifacts should be open for extension but closed for modification — adding new behavior should add code, not change existing code.

OOP didn't invent encapsulation — C had perfect encapsulation before C++ and Java actually weakened it with header file requirements.

Group all responsibility for a clean feature boundary into one package — internal persistence and logic stay private, the compiler enforces what's visible to the rest of the system.

Group code by domain feature — top-level packages reveal the business, every feature is co-located, and searchability dramatically improves as the system grows.

The simplest code organization groups by technical layer (web/service/repository) — easy to start but hides business intent and allows accidental cross-layer shortcuts.

Full architectural boundaries are expensive — partial boundaries using Strategy or Facade patterns preserve future separation points without the full upfront cost.

The peripheral anti-pattern occurs when infrastructure code talks directly to other infrastructure code, bypassing the domain — like the Paris ring road, traffic flows around the city instead of through it.

Level is the distance from inputs and outputs — the farther from I/O, the higher the level. Source code dependencies should always point toward the highest-level, most stable policies.

Polymorphism lets you treat external dependencies — database, UI, I/O — as interchangeable plugins, making core logic device-independent.

The inside is the domain; the outside is infrastructure — outside depends on inside, ports speak the domain's language, and adapters translate between domain and external systems.

Tests don't prove correctness — they prove absence of known incorrectness. Good architecture produces easily falsifiable modules.

The three paradigms — structured, object-oriented, and functional — impose discipline by removing capabilities, not adding them.

REP groups classes released together; CCP groups classes that change together for the same reason — both mirror SRP at the component scale.

A component should be as abstract as it is stable — the most stable components should be pure interfaces so they can be extended without modification.

Your folder structure should reveal what the system does, not what framework it uses — a health system screams 'Health', not 'Rails'.

Depend in the direction of stability — a volatile component should never be depended upon by a stable one, or that stability is permanently compromised.

Services don't define architecture — a service with poor internal structure is just an expensive function call. True architectural boundaries can exist inside a monolith or across services.

A module should be responsible to only one actor — preventing changes for one department from accidentally breaking another.

Dijkstra proved unrestricted goto is harmful. Sequence, selection, and iteration alone are sufficient for correct, decomposable modules.

Tests are the outermost architectural circle — fragile tests that couple to implementation details make the system rigid; a Test API decouples test structure from application structure.

Software derives value from behavior and structure. A perfectly working but rigid system will fail when requirements change.

Use cases are vertical slices that cut through all layers — decoupling them lets each evolve independently without one use case's changes colliding with another's.