ADR-0001 — Clean architecture: core owns all contracts

Status: accepted

Context

Kavo must stay usable if the ORM or web framework changes, yet v6 builds exactly one of each (TypeORM, NestJS). The temptation is to let the edges define their own interfaces and have core adapt.

Decision

Every contract (KavoService, RepositoryAdapter, TransactionManager, …) is declared in @kavo/core. Edge packages implement or consume core contracts; core never imports an edge. Dependency inversion is strict and mechanically enforced (dependency-cruiser + project references).

Consequences

• The adapter seam is real: @kavo/typeorm is replaceable by construction, even though no second adapter ships in v6.
• Core contracts must be designed before edge implementations exist — accepted cost of a stable surface.
• A contract change is a core change with lockstep releases (ADR-0004), never a silent edge divergence.