# ADR 0001 — Repository pattern with Memory + Pg implementations

**Status:** Accepted (2026-05-05) · Reaffirmed 2026-05-06

## Context

The Arete API was originally written with module-scope `Map<string, …>` stores
embedded directly in each Fastify route file. That made tests fast (no database
needed) but blocked production deployment because the data disappeared on every
restart.

A separate "wire it to Postgres" pass would either:

1. Replace the Maps with Drizzle calls inline — cheap, but loses the
   easy-to-test in-memory mode.
2. Introduce a façade — slightly more code per domain, gain the ability to swap
   backends.

## Decision

Every domain exposes a single TypeScript `interface` for its persistence
operations. Two classes implement it:

- `Memory<Domain>Repository` — `Map`s + arrays, used by tests via
  `server.decorate('repositories', { … })` before route registration. A
  `clear()` method wipes per-test state.
- `Pg<Domain>Repository` — Drizzle calls against the real schema. Wired by
  `plugins/repositories.ts` in production.

Routes call `fastify.repositories.<domain>.<method>` and never know which
implementation answered.

## Consequences

- Tests stay self-contained and fast (no Postgres required).
- New domains follow a documented template — coach + gamification migrations
  completed in hours rather than days.
- The interface is the contract. When a method shape changes, both
  implementations must be updated, which keeps them in sync.
- A small amount of repetition: each operation is described twice (in Memory +
  Pg). This is preferred to an abstract base because the in-memory
  implementation often runs faster paths (e.g. `.findIndex`) that would be
  wasteful for the SQL backend.

## Alternatives considered

- **Drizzle-only (no Memory)** — would force every test to spin up Postgres or
  use a heavy mocking layer. Rejected.
- **Sqlite in tests** — avoids the abstraction at the cost of a separate schema
  dialect (jsonb in particular). Rejected.
- **Raw SQL via `pg`** — would lose the type safety Drizzle provides for the
  (already large) 48-table schema. Rejected.

## Reference

Concrete templates: `apps/arete/api/src/repositories/users.ts` (the canonical
example) and the matching test
`apps/arete/api/__tests__/repositories-users.test.ts`.
