# ADR 0002 — Hexagonal (ports & adapters) architecture

**Status:** accepted (2026-06-10). Refines ADR 0001 (Echo + bulwarkauth idioms
stay; the overall structure becomes hexagonal).

## Context

Phase 0 first shipped as a bulwarkauth-style layered app (`api/`, `internal/
library`, `internal/view`). Fritz directed that the architecture be **hexagonal**.
The reading room has a clean port shape: it is driven by HTTP and it drives two
outbound dependencies (a demarkus world over QUIC, a markdown renderer) — exactly
what ports & adapters models. Phase 1 will swap the transport (direct QUIC → MCP
over the broker) and add an OAuth session; isolating the core from transport makes
that a one-adapter change.

## Decision

Ports & adapters. Dependencies point inward only (adapters → ports → core).

```
cmd/demarkus-library/        composition root (wires adapters into the core)
internal/core/
  domain/    document.go     entities + sentinel errors; NO external imports
  port/      port.go         inbound + outbound port interfaces (domain types only)
  service/   reading.go      application core; implements inbound ports via outbound ports
internal/adapter/
  inbound/web/               Echo handlers/routes/view (driving / primary adapter)
  outbound/world/            demarkus QUIC fetch client → port.WorldGateway
  outbound/markdown/         goldmark + bluemonday → port.Renderer
```

Ports:
- **Inbound (driving):** `port.ReadingService` — `Read(path) (domain.Document, error)`.
  The web adapter depends on this interface, not the concrete service.
- **Outbound (driven):** `port.WorldGateway` — `Fetch(path) (domain.RawDocument,
  error)`; `port.Renderer` — `Render(markdown string) (string, error)`.

Rules enforced (also encoded in `.coderabbit.yaml` path_instructions):
- `domain` imports only the stdlib + other core packages — no Echo, no demarkus
  client/protocol, no html/template, no goldmark.
- Ports speak domain types only (never `protocol.Response`, `fetch.Result`,
  `echo.Context`, `template.HTML`).
- Transport status → domain error translation lives in the `world` adapter; the
  core never sees a `protocol.Status`.
- Sanitized-HTML-as-string crosses the renderer port; the web adapter alone marks
  it `template.HTML`.
- Each implementation carries a `var _ port.X = (*T)(nil)` assertion.

bulwarkauth idioms retained: Echo v5, `NewX(...)` constructors returning values,
`<domain>_handlers.go` / `<domain>_routes.go` naming (inside the web adapter),
env-driven `AppConfig`, slog JSON.

## Consequences

- Phase 1's broker MCP gateway is a new `outbound/<adapter>` implementing
  `port.WorldGateway` (plus an OAuth session) — swapped at the composition root,
  core untouched.
- The core is testable with fakes for both outbound ports (no live world); the
  `world` adapter is tested for status mapping with a fake fetch client.
- Slightly more packages/indirection than a flat layered app — justified by the
  imminent transport swap and the strict XSS/transport boundary.
- CodeRabbit enforces the dependency rule per-path; PR scopes are the layer names
  (`domain`, `port`, `service`, `web`, `world`, `markdown`, `cmd`).