🏗️ Clean Architecture

Tools and frameworks (Express, Spring, NestJS, PostgreSQL) are details. A professional architecture allows you to postpone decisions about these details. The “Center” of your application should only contain the business rules that make your project unique.

🧩 SOLID Principles

The five basic principles of object-oriented design and programming.

S: Single Responsibility: A class/module should have one, and only one, reason to change.
O: Open/Closed: Software entities should be open for extension, but closed for modification.
L: Liskov Substitution: Objects of a superclass should be replaceable with objects of its subclasses without breaking the application.
I: Interface Segregation: No client should be forced to depend on methods it does not use.
D: Dependency Inversion: Depend on abstractions, not concretions. (The heart of Hexagonal Architecture).

🔷 Hexagonal Architecture (Ports & Adapters)

The goal is to create a clear separation between the Core Logic and the External World.

The Core (Domain): Contains Business Entities and Use Cases. It has no dependencies on any external library or database.
Ports (Interfaces): Definitions of how the core wants to interact with the world (e.g., UserRepository interface).
Adapters (Implementation): The “glue” code.
- Driving Adapters: Take input from the user (REST Controllers, CLI).
- Driven Adapters: Take output from the Core to the world (SQL Implementation, SMTP Mailer).

🏛️ DDD (Domain-Driven Design)

A methodology for mapping complex business requirements into software.

Strategic Design

Bounded Context: A clear boundary within which a particular domain model is defined and applicable. (e.g., “Product” in the Sales context vs. “Product” in the Inventory context).
Ubiquitous Language: Developers and Business Stakeholders must use the same terms in conversation and in the code.

Tactical Design (The Building Blocks)

Entities: Objects with a unique identity that persists over time (e.g., a User with an ID).
Value Objects: Objects defined only by their attributes (e.g., an Address or Money). They are immutable.
Aggregates: A cluster of associated objects that we treat as a unit for data changes. The Aggregate Root is the only gatekeeper for changes.
Repositories: Abstractions used to retrieve and store Aggregates.

⚖️ The “Clean” Trade-off

Aspect	Classic Layered (N-Tier)	Clean / Hexagonal
Complexity	Low (Fast to start)	High (More boilerplate/files)
Testability	Hard (Database is coupled)	Easy (Core is pure logic)
Evolution	Hard (UI/DB changes leak)	Easy (Replace adapters only)
Ideal For	Simple CRUD / MVPs	Complex Systems / Long-term

When to use Clean Architecture?

Avoid Over-engineering: If you are building a small internal tool that just moves data from a form to a table, Clean Architecture is likely overkill.
Embrace it when: The business logic is complex, the project will last for years, or you anticipate changing your infrastructure (e.g., moving from a Monolith to Microservices).

💡 Note: The most common mistake is “Dogmatism.” Don’t force every single microservice into a full DDD/Hexagonal structure. Apply the level of architectural rigor that matches the complexity of the domain. Sometimes a simple Service/Repository pattern is enough.