# ADR-0001: Clean Architecture

## Status
Accepted

## Context
NexusCRM is a complex CRM platform with multiple integration points (REST API, MCP, EventBus). We needed an architecture that:
- Separates business logic from infrastructure
- Enables testability without database dependencies
- Allows swapping implementations (e.g., different DBs)
- Maintains clear boundaries between layers

## Decision
We adopt **Clean Architecture** with the following layers:

```
backend/internal/
├── domain/         # Business entities, ports (interfaces)
├── features/       # Use cases, business logic
├── application/    # Service orchestration
├── infrastructure/ # Database, external services
└── interfaces/     # REST handlers, middleware
```

**Key principles:**
1. **Dependency Rule**: Dependencies point inward (interfaces → domain)
2. **Port-Adapter Pattern**: `domain/ports/` defines interfaces, `infrastructure/` implements
3. **Feature-Based Organization**: Related logic grouped in `features/`

## Consequences

**Positive:**
- Easy to test features in isolation
- Clear separation of concerns
- Infrastructure changes don't affect business logic
- New team members understand boundaries quickly

**Negative:**
- More files and directories
- Indirection may seem excessive for simple CRUD
- Learning curve for developers unfamiliar with the pattern

**Trade-offs accepted:**
- Prefer explicitness over brevity
- Accept some boilerplate for testability