Clean Architecture Design
Clean architecture aims to keep the direction of dependencies stable: inner layers express business rules, while outer layers adapt to frameworks, databases, and user interfaces. In practice, that means a payment rule written as domain logic should not import a web controller, an ORM model, or a message-bus client. When the dependency graph stays pointed inward, refactors become less risky and tests stop needing heavy infrastructure.
A concrete example: a “RefundPolicy” that decides whether a refund is allowed should expose a method like canRefund(orderId, reason) and return a domain result. The web layer can translate HTTP requests into domain inputs, then translate domain outputs back into HTTP responses. If the policy imports HTTP types or database entities, the rule becomes harder to test and harder to reuse.
Clean architecture also clarifies what belongs where. Domain code holds invariants and decision logic; application code coordinates use cases; infrastructure code handles persistence, external APIs, and file systems. This separation does not prevent you from using frameworks; it prevents frameworks from leaking into the rules that should remain stable.
Main Pain Points
Teams often treat “layers” as a visual diagram rather than a dependency rule. When a controller calls a repository directly and the repository calls back into the controller’s DTOs, the project accumulates hidden coupling that breaks during change. Another common failure involves placing business logic into controllers or services that also know about persistence details, which turns every feature into a database migration exercise.
Dependency direction is the real constraint. If your domain layer imports infrastructure interfaces that mention concrete technologies, you reverse the dependency flow. A typical smell appears when domain code references ORM annotations, SQL strings, or cloud SDK models. The code still compiles, but the architecture stops protecting you from change.
Supporting technologies create additional pressure. ORMs such as Hibernate or Entity Framework can encourage “anemic” domain models that mirror tables, while message brokers like Kafka or RabbitMQ can tempt teams to embed serialization formats into business logic. Even test tooling can distort boundaries: if unit tests require a running database because the domain depends on repositories, the tests become slow and brittle.
There is also a practical mismatch between “clean” boundaries and real performance needs. For example, a domain rule that needs aggregated data may tempt developers to query the database inside the rule. That approach works, but it erodes the separation that makes the rule portable. You can keep the boundary by moving data retrieval into application code and passing the needed facts into the domain rule.
Solutions And Advice
Define Boundaries With Use Cases
Start by writing use cases as small application services that orchestrate domain operations. Each use case should accept plain inputs and return plain outputs, with no direct dependency on HTTP, SQL, or broker clients. In a Java project, that might mean a PlaceOrderUseCase that depends on domain interfaces like OrderRepository and domain services like PricingPolicy, while the web controller depends on the use case.
Keep the use case boundary narrow: one use case per user intent or workflow step. If a single service handles “create order,” “charge card,” “send email,” and “update CRM,” you will struggle to test failure modes. A mild frustration many teams hit: they copy-paste orchestration logic across controllers, then later try to “clean it up” by moving it into a shared service that still imports web-specific types.
As a side observation, teams sometimes adopt a convention like “application package contains only use cases and ports,” then enforce it with static checks. In one project I reviewed, a simple rule in the build pipeline (for example, failing if domain imports infrastructure) caught architectural drift early. Version numbers matter for tooling; the exact mechanism depends on your stack and build system.
Use Ports And Adapters For IO
Model external interactions as ports (interfaces) and implement them as adapters. The domain and application layers depend on ports, while infrastructure provides adapters. A port might be OrderRepository with methods like loadById and save, while an adapter uses your ORM or SQL client.
To keep boundaries honest, define ports in the application layer or domain layer depending on who owns the contract. If the contract describes business concepts, place it near the domain. If it describes a technical capability needed by use cases, place it near application. This choice affects dependency direction and test setup.
For tests, use fake adapters that return deterministic data. A unit test for a use case should not require a live database; it should use a fake repository and a fake clock. If you need time-based behavior, inject a clock interface rather than calling System.currentTimeMillis() or new Date() directly.
Keep Entities From Becoming DTOs
Domain entities should represent business concepts and invariants, not database rows. DTOs belong at boundaries: between web and application, between application and messaging, or between application and external APIs. If you reuse the same class for both persistence and domain rules, you often end up with setters that violate invariants or with fields that exist only because a table needs them.
A practical tactic: treat persistence models as separate from domain models. With JPA or Entity Framework, you can map persistence entities to domain entities using mappers in infrastructure. That mapper can translate between database identifiers and domain value objects. It adds code, but it prevents the ORM from dictating your domain shape.
When you use value objects, keep them small and immutable. A value object like Money should carry currency and amount, and it should validate invariants at construction time. If you allow invalid states, you push validation into random places and the architecture stops being a guardrail.
Measure Coupling With Dependency Graphs
Clean architecture fails quietly when dependencies creep across boundaries. Use tooling to inspect the dependency graph. In Java, tools like jdepend, jQAssistant, or build-time checks can flag forbidden imports. In .NET, analyzers and dependency graph tools can help. In JavaScript/TypeScript, ESLint rules and project references can enforce import boundaries.
Set a target: for example, “domain must not import infrastructure,” and “infrastructure may import application ports but not domain services that should remain pure.” Then track violations over time. If you see a growing list of exceptions, the architecture is already paying interest.
One small but useful habit: review pull requests for dependency direction before reviewing business logic. That order catches the common pattern where a developer adds a new feature and accidentally imports a framework type into a domain module. It rarely works the way the docs say because teams copy patterns from controllers and services without checking imports.
Case Examples
Refund Rule With Inward Dependencies
An anonymized e-commerce team separated a refund policy from their web API. The domain module contained RefundPolicy and value objects like RefundReason. The application use case loaded order facts through a repository port, then called the policy with those facts. The web controller handled HTTP status codes and request parsing, but it never imported ORM entities.
After the change, unit tests for refund decisions ran without a database. Integration tests still covered the full stack, including persistence and serialization, but they focused on fewer scenarios. The team reported fewer regressions when changing the database schema because the policy no longer depended on table structure.
Message Consumer Without Business Coupling
A logistics platform used a message broker to process shipment events. The team created an application use case ProcessShipmentEvent that accepted a domain event representation. The consumer adapter handled broker-specific concerns: deserialization, retries, and dead-letter routing. The domain logic depended on ports for lookups and updates, not on Kafka or RabbitMQ client classes.
When the team changed the message schema version, only the adapter needed updates. The domain rule remained stable because it consumed normalized facts. The cost was additional mapping code between broker payloads and domain event objects, which the team accepted because it kept failure handling and business decisions separate.
Comparison Checklist
| Decision Area | Clean Architecture Tends To | Common Alternative | How To Check |
|---|---|---|---|
| Dependency Direction | Outer layers depend on inner rules | Rules import framework or persistence types | Scan imports; forbid domain→infrastructure |
| Use Case Shape | Small orchestrators with plain inputs/outputs | Controllers contain business decisions | Count HTTP/ORM types referenced in use cases |
| Persistence Models | Separate from domain entities | ORM entities double as domain objects | Look for setters that violate invariants |
| Testing Strategy | Unit tests avoid live infrastructure | Unit tests require DB/broker | Measure test runtime; flag tests needing containers |
Checklist for a code review that takes 20–30 minutes: confirm the domain module has no imports from web, ORM, or broker packages; confirm use cases accept plain inputs and return plain outputs; confirm adapters translate between external payloads and domain facts; confirm unit tests for use cases run without a database or message broker. If any step fails, the architecture is already paying a tax.
Common Mistakes
One mistake involves “moving code” without changing dependencies. Teams refactor a controller into a service, then keep the same imports and data models. The result looks cleaner in folder structure but remains coupled in practice. Another mistake places business logic into application services that also perform persistence queries and serialization, which makes the logic harder to test and harder to reuse.
Another recurring issue is over-abstraction. Ports and interfaces multiply quickly, and developers end up writing adapters that do little more than pass through data. When that happens, the architecture adds ceremony without improving change safety. A mild frustration shows up when new developers cannot tell which interface is the real contract and which one exists only because of a previous refactor.
Teams also underestimate the cost of mapping. If you separate persistence models from domain models, you must translate identifiers, handle nullability differences, and map enums carefully. Those details belong in infrastructure or dedicated mappers, not in domain rules. When mapping logic leaks into domain code, you end up with domain objects that know about database constraints.
Finally, teams sometimes treat “clean” as a one-time migration. Architecture boundaries need ongoing enforcement through reviews and automated checks. If you rely only on documentation, drift returns after the first few features land. I have seen projects where a single missing import rule caused a slow spread of framework types into domain modules, and the cleanup later required a larger rewrite.
FAQ
What Counts As A Use Case?
A use case represents a specific workflow the system performs, such as “place order” or “request refund.” It coordinates domain operations and calls ports for data access, while it stays free of HTTP, SQL, and broker client types.
How Do Ports Differ From Services?
Ports are contracts that describe what the application needs from the outside world, usually as interfaces. Services contain behavior; adapters implement ports and translate between external formats and domain facts.
Where Should DTOs Live?
DTOs belong at boundaries, such as request/response models in the web layer or message payload models in the messaging adapter. Domain entities and value objects should not depend on DTO shapes.
Does Clean Architecture Reduce Performance?
It can add mapping and extra calls, but it does not inherently reduce performance. The main risk comes from moving queries into the wrong layer; keep data retrieval in application code and pass aggregated facts into domain rules.
How Can I Enforce Boundaries?
Use dependency checks that fail builds on forbidden imports, and add review criteria for module dependencies. Tools vary by stack; for example, ESLint import rules in TypeScript or build-time import checks in Java can catch drift early.
Author's Insight
Clean architecture works best when dependency direction is treated as a measurable constraint rather than a diagram. The most reliable improvements come from separating domain rules from IO concerns and from keeping use cases free of framework types. Mapping between persistence models, message payloads, and domain objects adds work, yet it prevents invariants from being shaped by storage details.
Evidence-based practice here means using dependency graph checks, writing unit tests that do not require live infrastructure, and tracking boundary violations over time. When teams skip enforcement, the architecture degrades through small, repeated imports that look harmless in a single pull request.
Tooling choices depend on your language and build system; a rule that works in one stack may not translate directly. A practical next step is to pick one boundary rule, enforce it automatically, and measure how often it gets violated in the next few weeks.
Key Takeaways
- Keep dependencies pointing inward: domain rules should not import web, ORM, or broker types.
- Model workflows as use cases with plain inputs/outputs, and move IO into adapters.
- Separate persistence models and message payloads from domain entities to protect invariants.
- Enforce boundaries with automated import/dependency checks and unit tests that avoid live infrastructure.
- Expect mapping code; place it in infrastructure so domain logic stays stable.
