clean-architecture

name	clean-architecture
description	Clean Architecture layer patterns (Handler → Usecase → Port → Gateway → Driver), mapped to s4rCiv's adapter model and observation/interpretation plane separation. Use when implementing or reviewing layered backend code (source adapters, normalizer, read models, CQRS).

Clean Architecture Layers

Handler -> Usecase -> Port -> Gateway -> Driver

s4rCiv mapping

These layers map onto s4rCiv's adapter-based, CQRS, dual-plane design:

• Driver / Gateway = the HTTP-GET boundary of a source adapter (the only place that touches an external public endpoint) plus the event-store / read-model persistence drivers. Keep collection (raw fetch) and the anti-corruption mapping to standard schemas (AKN / Popolo / OCDS) here.
• Usecase = normalization, diff/classification, and event emission into the append-only log (observation plane) — no direct external dependencies, only Port interfaces.
• Read-model projectors that build the interpretation plane are themselves Usecase-level orchestration over Port interfaces; they are recomputable and must not be a source of truth.
• A new source = a new adapter implementing the same Port contracts (the unit of extension). Keep adapters loosely coupled and versioned.

Layer Rules

Layer	Responsibility	Can Depend On
Handler	HTTP/gRPC entry points, validation, response formatting	Usecase, Port
Usecase	Business logic orchestration, NO external dependencies	Port only
Port	Interface definitions (contracts)	Nothing
Gateway	Anti-corruption layer, external service mapping	Port, Driver
Driver	Database, API, external integrations	External libraries

File Patterns

• **/rest/** or **/handler/** = Handler layer
• **/usecase/** = Usecase layer
• **/port/** = Port layer (interfaces)
• **/gateway/** = Gateway layer
• **/driver/** = Driver layer

Common Violations

• Handler importing Driver directly (must go through Usecase)
• Usecase importing external packages (use Port interfaces)
• Circular dependencies between layers