agentic-dev/docs/decisions/adr-009-integrations-folder-naming.md

ADR-009: Rename adapters/ to integrations/

Status: Accepted Date: 2026-05-04

Context

The source spec (monorepo-architecture-spec-detailed-v5.md) uses adapters/cms and adapters/api for Payload and tRPC integration points. Clean Architecture also uses adapters/ (or interface-adapters/) for transport-agnostic controller layer. The name collision is confusing.

Decision

Use integrations/ for role-based plug points (Payload and tRPC). Keep interface-adapters/ for the Clean Architecture controller layer.

Result:

packages/<feature>/src/
  interface-adapters/controllers/  ← Clean Architecture layer (transport-agnostic)
  integrations/
    cms/                           ← Payload collections/globals
    api/                           ← tRPC routers

Consequences

• No naming collision — intent is unambiguous
• integrations/ semantically captures "external system integration" better than adapters/
• Minor deviation from source spec, documented here as deliberate choice
• All new features follow this naming consistently

Alternatives Considered

• Keep adapters/: Collision with Clean Architecture terminology is confusing
• Use external/: Less specific; doesn't convey "Payload and tRPC"
• Rename Clean Architecture layer to controllers/: Could work; less standard