architecture-patterns

<!-- directive-density: intentional (teaches anti-patterns; NEVER markers describe real layering violations, not aspirational guidance) -->

# Architecture Patterns

Consolidated architecture validation and enforcement patterns covering clean architecture, backend layer separation, project structure conventions, and test standards. Each category has individual rule files in `references/` loaded on-demand.

## Quick Reference

| Category | Rules | Impact | When to Use |
|----------|-------|--------|-------------|
| [Clean Architecture](#clean-architecture) | 3 | HIGH | SOLID principles, hexagonal architecture, ports & adapters, DDD |
| [Project Structure](#project-structure) | 2 | HIGH | Folder conventions, nesting depth, import direction, barrel files |
| [Backend Layers](#backend-layers) | 3 | HIGH | Router/service/repository separation, DI, file naming |
| [Test Standards](#test-standards) | 3 | MEDIUM | AAA pattern, naming conventions, coverage thresholds |
| [Right-Sizing](#right-sizing) | 2 | HIGH | Architecture tier selection, over-engineering prevention, context-aware enforcement |

**Total: 13 rules across 5 categories**

## Quick Start

```python
# Clean Architecture: Dependency Inversion via Protocol
class IUserRepository(Protocol):
    async def get_by_id(self, id: str) -> User | None: ...

class UserService:
    def __init__(self, repo: IUserRepository):
        self._repo = repo  # Depends on abstraction, not concretion

# FastAPI DI chain: DB -> Repository -> Service
def get_user_service(db: AsyncSession = Depends(get_db)) -> UserService:
    return UserService(PostgresUserRepository(db))
```

```
# Project Structure: Unidirectional Import Architecture
shared/lib  ->  components  ->  features  ->  app
(lowest)                                    (highest)

# Backend Layers: Strict Separation
Routers (HTTP) -> Services (Business Logic) -> Repositories (Data Access)
```

## Clean Architecture

SOLID principles, hexagonal architecture, ports and adapters, and DDD tactical patterns for maintainable backends.

| Rule | File | Key Pattern |
|------|------|-------------|
| Hexagonal Architecture | `${CLAUDE_SKILL_DIR}/references/clean-hexagonal-ports-adapters.md` | Driving/driven ports, adapter implementations, layer structure |
| SOLID & Dependency Rule | `${CLAUDE_SKILL_DIR}/references/clean-solid-dependency-rule.md` | Protocol-based interfaces, dependency inversion, FastAPI DI |
| DDD Tactical Patterns | `${CLAUDE_SKILL_DIR}/references/clean-ddd-tactical-patterns.md` | Entities, value objects, aggregate roots, domain events |

### Key Decisions

| Decision | Recommendation |
|----------|----------------|
| Protocol vs ABC | Protocol (structural typing) |
| Dataclass vs Pydantic | Dataclass for domain, Pydantic for API |
| Repository granularity | One per aggregate root |
| Transaction boundary | Service layer, not repository |
| Event publishing | Collect in aggregate, publish after commit |

## Project Structure

Feature-based organization, max nesting depth, unidirectional imports, and barrel file prevention.

| Rule | File | Key Pattern |
|------|------|-------------|
| Folder Structure & Nesting | `${CLAUDE_SKILL_DIR}/references/structure-folder-conventions.md` | React/Next.js and FastAPI layouts, 4-level max nesting, barrel file rules |
| Import Direction & Location | `${CLAUDE_SKILL_DIR}/references/structure-import-direction.md` | Unidirectional imports, cross-feature prevention, component/hook placement |

### Blocking Rules

| Rule | Check |
|------|-------|
| Max Nesting | Max 4 levels from src/ or app/ |
| No Barrel Files | No index.ts re-exports (tree-shaking issues) |
| Component Location | React components in components/ or features/ only |
| Hook Location | Custom hooks in hooks/ or features/*/hooks/ only |
| Import Direction | Unidirectional: shared -> components -> features -> app |

## Backend Layers

FastAPI Clean Architecture with router/service/repository layer separation and blocking validation.

| Rule | File | Key Pattern |
|------|------|-------------|
| Layer Separation | `${CLAUDE_SKILL_DIR}/references/backend-layer-separation.md` | Router/service/repository boundaries, forbidden patterns, async rules |
| Dependency Injection | `${CLAUDE_SKILL_DIR}/references/backend-dependency-injection.md` | Depends() chains, auth patterns, testing with DI overrides |
| File Naming & Exceptions | `${CLAUDE_SKILL_DIR}/references/backend-naming-exceptions.md` | Naming conventions, domain exceptions, violation detection |

### Layer Boundaries

| Layer | Responsibility | Forbidden |
|-------|---------------|-----------|
| Routers | HTTP concerns, request parsing, auth checks | Database operations, business logic |
| Services | Business logic, validation, orchestration | HTTPException, Request objects |
| Repositories | Data access, queries, persistence | HTTP concerns, business logic |

## Test Standards

Testing best practices with AAA pattern, naming conventions, isolation, and coverage thresholds.

| Rule | File | Key Pattern |
|------|------|-------------|
| AAA Pattern & Isolation | `${CLAUDE_SKILL_DIR}/references/testing-aaa-isolation.md` | Arrange-Act-Assert, test isolation, parameterized tests |
| Naming Conventions | `${CLAUDE_SKILL_DIR}/references/testing-naming-conventions.md` | Descriptive behavior-focused names for Python and TypeScript |
| Coverage & Location | `${CLAUDE_SKILL_DIR}/references/testing-coverage-location.md` | Coverage thresholds, fixture scopes, test file placement rules |

### Coverage Requirements

| Area | Minimum | Target |
|------|---------|--------|
| Overall | 80% | 90% |
| Business Logic | 90% | 100% |
| Critical Paths | 95% | 100% |
| New Code | 100% | 100% |

## Right-Sizing

Context-aware backend architecture enforcement. Rules adjust strictness based on project tier detected by `scope-appropriate-architecture`.

**Enforcement procedure:**
1. Read project tier from `scope-appropriate-architecture` context (set during brainstorm/im