newkayak12 Clean Architecture Framework
A disciplined approach to structuring software so that business rules remain independent of frameworks, databases, and delivery mechanisms.
When to Use / When Not to Use
| Use | Skip |
|---|---|
| Designing layer boundaries for a new service | Code-level naming and function size (use clean-code) |
| Business logic is coupled to HTTP or ORM | Domain modeling with bounded contexts (use domain-driven-design) |
| Swap database or framework is too hard | Simple scripts or prototypes |
| Writing testable use cases |
Process
- Assess current state — Score the architecture 0–10; identify dependency rule violations
- Draw concentric circles — Entities → Use Cases → Interface Adapters → Frameworks/Drivers
- Identify violations — Find import arrows pointing outward; list them
- Apply Dependency Inversion — Define interfaces in inner circles; implementations in outer circles
- Validate — Confirm business logic tests run with no framework imports
Scoring
Goal: 10/10. Rate architecture 0–10. A 10/10 means business rules can be tested with no database, web server, or framework present.
The Clean Architecture Framework
1. Dependency Rule and Concentric Circles
Source code dependencies always point inward. Nothing in an inner circle can know anything about an outer circle.
| Context | Pattern | Example |
|---|---|---|
| Layer direction | Inner circles define interfaces; outer circles implement them | UserRepository interface in Use Cases; PostgresUserRepository in Adapters |
| Data crossing | DTOs or simple structs cross boundaries, not ORM entities | Use Case returns UserResponse DTO, not an ActiveRecord model |
| Framework isolation | Wrap framework calls behind interfaces | EmailSender interface hides whether you use SendGrid or SES |
| Database independence | Repository pattern abstracts persistence | Business logic calls repo.save(user), never raw SQL |
See: references/dependency-rule.md
2. Entities and Use Cases
- Entities encapsulate enterprise-wide business rules; no framework dependencies
- Use Cases contain application-specific rules; orchestrate Entities; accept Request Models and return Response Models
| Context | Pattern | Example |
|---|---|---|
| Entity design | Encapsulate rules with no framework dependencies | Order.calculateTotal() knows nothing about HTTP |
| Use Case boundary | Define Input Port and Output Port interfaces | CreateOrderInput interface; CreateOrderOutput interface |
| Request/Response | Simple data structures cross the boundary | CreateOrderRequest { items, customerId } — no ORM models |
| Single responsibility | One Use Case per application operation | PlaceOrder, CancelOrder, RefundOrder as separate classes |
See: references/entities-use-cases.md
3. Interface Adapters and Frameworks
Interface Adapters convert data between Use Cases and external agencies. Frameworks belong in the outermost circle.
| Context | Pattern | Example |
|---|---|---|
| Controller | Translates delivery mechanism to Use Case input | OrderController.create(req) builds CreateOrderRequest |
| Presenter | Translates Use Case output to view model | OrderPresenter.present(response) formats data for JSON |
| Gateway | Implements repository interface using a specific DB | SqlOrderRepository implements OrderRepository |
| Plugin architecture | Main component wires dependencies at startup | main() instantiates concrete classes and injects them |
See: references/adapters-frameworks.md
4. Component Principles
- REP: classes in a component should be releasable together
- CCP: classes that change for the same reason belong in the same component
- ADP: no cycles in the component dependency graph
- SDP: depend in the direction of stability
See: references/component-principles.md
5. SOLID Principles
| Principle | Core Rule | Common Violation |
|---|---|---|
| SRP | One reason to change | Employee handles pay, reporting, and persistence |
| OCP | Extend by adding new code, not modifying existing | Adding if branches for new types |
| LSP | Subtypes usable through base type | Square extends Rectangle breaks setWidth() contract |
| ISP | Don't force clients to depend on unused methods | Fat interface forces importing unneeded methods |
| DIP | High-level modules depend on abstractions | OrderService imports StripeClient directly |
See: references/solid-principles.md
6. Boundaries and Boundary Anatomy
- Full boundary: reciprocal interfaces on both sides (Input Port + Output Port)
- Partial boundary: strategy or facade pattern
- Humble Object: split behavior at a boundary — testable logic separate from hard-to-test infrastructure
See: references/boundaries.md
Quick Diagnostic
| Question | If No | Action |
|---|---|---|
| Can you test business rules without a database or web server? | Business rules coupled to infrastructure | Extract entities and use cases behind interfaces |
| Do source code dependencies point inward on every import? | Dependency Rule violated | Introduce interfaces; invert the offending dependency |
| Can you swap the database without changing business logic? | Persistence leaking inward | Implement Repository pattern |
| Are Use Cases independent of the delivery mechanism? | Use Cases know about HTTP | Remove delivery-specific types; use plain DTOs |
| Is the framework confined to the outermost circle? | Framework is your architecture | Wrap framework calls behind interfaces |
Output Template
When designing or reviewing an architecture, provide:
- Score (0–10) with justification
- Dependency violations found (import path + direction)
- Refactoring plan (interfaces to extract, classes to move)
- Before/after diagram (Mermaid or ASCII)
What Claude Does / What You Do
| Claude | You |
|---|---|
| Draws the concentric circle diagram | Share existing module structure |
| Identifies dependency rule violations | Confirm business rules and domain entities |
| Defines interface contracts at each boundary | Implement concrete classes in outer circles |
| Writes Use Case input/output DTOs | Wire dependencies in Main/composition root |
Reference Files
- dependency-rule.md
- entities-use-cases.md
- adapters-frameworks.md
- component-principles.md
- solid-principles.md
- boundaries.md
Related Skills
develop:clean-code— code-level quality within each layerdevelop:domain-driven-design— domain modeling and bounded contextsdevelop:architecture-designer— structural and deployment-level decisions