clean-architecture

Start with the Quick Diagnostic: check whether business rules can be tested without a database or framework and whether dependencies point inward. For each violation, define an interface in the inner circle, move the concrete implementation outward, and wire it in the Main composition root.

The Dependency Rule states that source code dependencies must only point inward, from frameworks toward use cases and entities. Nothing in an inner circle may reference names, classes, or data formats from an outer circle; dependency inversion through interfaces enforces this.

Entities encapsulate enterprise-wide business rules that would exist without software, while use cases contain application-specific rules orchestrating data flow to and from entities. Each use case is a single operation like PlaceOrder, implemented as an Interactor with input and output ports.

No. Keep domain entities free of ORM annotations and database concerns, and maintain a separate persistence model in the adapter layer. Gateways map between the two, so schema changes never force business rule rewrites.

No. A microservice with a shared database or shared data model is a distributed monolith. Services are deployment boundaries; each service still needs its own internal concentric circles following the Dependency Rule to be a genuine architectural boundary.

Use a partial boundary, such as a strategy pattern or facade, when the anticipated need to swap implementations does not justify the cost of reciprocal ports and DTOs. Reserve full boundaries for points of likely volatility like persistence and external services.