Eve library

ADR 0001 — Repository pattern with Memory + Pg implementations

ADR

Revision 1

On this page

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 — Maps + 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.