oikos/docs/adr/0016-hexagonal-ports-adapters.md

ADR 0016 — Hexagonal (ports & adapters) architecture for the oikos backend

Status: accepted (2026-08-15) · Plan: plans/2026-08-15-hexagonal-architecture.md

Context

The oikos backend grew as delivery-layer packages with business logic inside them. internal/httpapi (~3500 LOC) and internal/mcp (~2100 LOC, 67 tools) each embed raw SQL next to validation, policy, and audit writes — two parallel silos re-implementing the same use-cases. The scheduler is a ~1100-LOC monolith mixing probe dispatch, health aggregation, signal transitions, and metric writes. There is one accidental port/adapter pair (secrets.Backend) and one inverted dependency (internal/db imports checkdefaults). Use-cases have no home: every new consumer (REST handler, MCP tool, scheduler pass) copy-pastes query + policy + audit logic, and behavior drifts between paths that must agree — the run/approve/execute lifecycle exists in three variants.

A staff-level review of the refactor plan settled the open questions: one hexagon (not per-binary), nomos stays an external agent client over the wire, aggregate-scoped repository methods instead of a UnitOfWork port, reads bypass services via a shared ReadModels port, and the client (web SPA + desktop) moves to its own repository before the backend churn starts.

Decision

Adopt ports & adapters across the backend, delivered in ten shippable phases:

• internal/core/domain (pure model, stdlib only), internal/core/app (application services = use-cases), internal/core/ports (driven-port interfaces). Core imports nothing from adapters; adapters and cmd/* import core.
• All I/O behind named ports implemented by adapters under internal/adapters/: postgres (repositories), ssh (CommandExecutor), probes/* (one Checker per check kind), remote (TargetResolver), secrets, events (EventPublisher/SSE), plus the driving adapters httpapi, mcpserver, scheduler, execworker, cli.
• One repository method = one transaction = one aggregate's atomic boundary (§3.6 of the plan). Inputs carry audit/event entries and derived checks; no pgx.Tx crosses into core; no UnitOfWork port.
• Commands flow through core/app services; invariant-free reads flow adapter → ReadModels → presenter with no service hop (CQRS-lite).
• REST and MCP keep their existing wire formats and become thin driving adapters over the same services; presenters stay per-adapter.
• nomos never links core: it consumes oikos exclusively through MCP/REST. Its Phase 8 cleanup defines nomos-local ports (LLMClient, HomelabClient, SessionStore) outside core/ports.
• The Gitea webhook receiver and the desktop shell are leaf utilities — documented, not restructured.
• Dependency rules are enforced with depguard from Phase 0 (rule 3, the internal/nomos bans, activates when that package exists in Phase 8).

Consequences

• No API, MCP-tool, DB-schema, or wire-format changes ride along; behavior parity is guarded by the existing handler contract tests plus a repository conformance suite asserting atomicity and check-then-act per command method.
• internal/db shrinks to connection/migrations/sqlcgen inside the postgres adapter; the db → checkdefaults inversion disappears with SeedService.
• Each phase merges green (make lint test generate-check, make test-db where repositories change) with a patch version bump; per-phase abort criteria revert a merge that breaks transaction semantics. Minor bump at Phase 9 completion.
• Cost accepted: ~10 phases of import churn, sqlc path updates under make generate-check, and a temporary period where old and new package locations coexist (depguard denies core→adapter imports from Phase 0 so the new tree can never grow the old inversions).
• Risk trade-off recorded in the plan: a repository method whose tx span is too narrow is a bug class this design makes possible; the conformance suite is the mitigation, and the check-then-act sites enumerated in the plan (approval decide, entity transition, check derivation, execution claim) are its first assertions.