102 lines
5.0 KiB
Markdown
102 lines
5.0 KiB
Markdown
---
|
|
name: clean-architecture
|
|
description: MANDATORY — always active. Apply Clean Architecture, hexagonal architecture, and SOLID principles when designing system boundaries, modules, or microservices. Use when structuring a new service, deciding what a component should own, untangling framework coupling. Always enforce the Dependency Rule — business rules must not depend on frameworks, databases, or UI. Detects from code context and project files — not dependent on specific language keywords.
|
|
---
|
|
|
|
# Clean Architecture
|
|
|
|
Keep business rules independent of frameworks, databases, and UI.
|
|
|
|
## The Dependency Rule
|
|
|
|
**Source code dependencies must point inward.** Nothing in an inner circle can know about something in an outer circle.
|
|
|
|
```
|
|
┌──────────────────────────────┐
|
|
│ Framework / DB / UI / IO │ ← outer: frameworks, drivers, devices
|
|
│ ┌──────────────────────────┐ │
|
|
│ │ Interface Adapters │ │ ← presenters, controllers, gateways
|
|
│ │ ┌──────────────────────┐ │ │
|
|
│ │ │ Application (Use Cases) │ │ ← orchestrate business flows
|
|
│ │ │ ┌──────────────────┐ │ │ │
|
|
│ │ │ │ Domain / Entities│ │ │ │ ← pure business rules, no deps
|
|
│ │ │ └──────────────────┘ │ │ │
|
|
│ │ └──────────────────────┘ │ │
|
|
│ └──────────────────────────┘ │
|
|
└──────────────────────────────┘
|
|
```
|
|
|
|
## Key Rules
|
|
|
|
1. **Domain layer** contains business entities and value objects. Zero framework imports. Zero database imports. Pure types and functions.
|
|
2. **Application layer** contains use cases — orchestrate domain objects to fulfill business flows. Depends only on domain. Declares ports (interfaces) for IO.
|
|
3. **Interface adapters** translate between use cases and the outside world — controllers, presenters, gateways. Depends on application layer + frameworks.
|
|
4. **Infrastructure/Framework layer** implements the ports declared by the application layer — database repos, HTTP clients, message queues.
|
|
5. **Screaming Architecture:** the project structure should scream "this is a [domain context]" — not "this is a Spring/Next.js/Django project."
|
|
|
|
## How to Check
|
|
|
|
- Can you swap the database without changing business logic? If not, boundary is violated.
|
|
- Can you unit-test a use case without spinning up a framework? If not, your use case depends on infrastructure.
|
|
- Do business entities import anything from the web framework or ORM? If so, revert that dependency.
|
|
|
|
## Practical Patterns
|
|
|
|
### Port-Adapter
|
|
```typescript
|
|
// Domain/Application port (declared here, implemented outside)
|
|
interface UserRepository {
|
|
findById(id: string): Promise<User | null>;
|
|
}
|
|
// Infrastructure adapter (implemented in infra layer)
|
|
class PostgresUserRepository implements UserRepository { ... }
|
|
```
|
|
|
|
### Use Case
|
|
```typescript
|
|
class CreateOrderUseCase {
|
|
constructor(private readonly repo: OrderRepository) {}
|
|
async execute(input: CreateOrderInput): Promise<Order> {
|
|
const order = Order.create(input.items, input.customerId);
|
|
return this.repo.save(order);
|
|
}
|
|
}
|
|
```
|
|
|
|
### Dependency Injection
|
|
Wire dependencies at the composition root — never in use cases or domain.
|
|
```typescript
|
|
// Composition Root
|
|
const orderRepo = new PostgresOrderRepository(db);
|
|
const createOrder = new CreateOrderUseCase(orderRepo);
|
|
```
|
|
|
|
## SOLID (Quick Ref)
|
|
|
|
- **SRP:** A class has one reason to change (one actor).
|
|
- **OCP:** Open for extension, closed for modification (polymorphism + strategy).
|
|
- **LSP:** Subtypes must be substitutable for their base types.
|
|
- **ISP:** Don't depend on interfaces you don't use (keep interfaces focused).
|
|
- **DIP:** Depend on abstractions, not concretions. Business rules don't import frameworks.
|
|
|
|
## Deeper Reference
|
|
|
|
When the task calls for it, load:
|
|
|
|
- **[references/solid.md](references/solid.md)** — Full SOLID treatment (SRP, OCP, LSP, ISP, DIP). Component principles (REP, CCP, CRP, ADP, SDP, SAP). Examples for each principle, historical evolution, and practical tests for violations.
|
|
|
|
## Ask When Ambiguous
|
|
|
|
When the module boundary is unclear, ask rather than guessing:
|
|
- "Should this live in domain or application layer? Is it a pure business rule or an orchestration concern?"
|
|
- "Is this a port (interface declared by application) or an adapter (implementation in infrastructure)?"
|
|
- If you're not sure which layer a piece of logic belongs to, flag it with a brief question. A wrong boundary assumption is expensive to refactor later.
|
|
|
|
## Anti-patterns
|
|
|
|
- ❌ Business logic in route handlers or controllers
|
|
- ❌ ORM entities directly exposed to the UI
|
|
- ❌ Database queries mixed into use cases
|
|
- ❌ Framework decorators on domain entities
|
|
- ❌ "Everything is a CRUD" — missing use case layer
|