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:
- Replace the Maps with Drizzle calls inline — cheap, but loses the easy-to-test in-memory mode.
- 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 viaserver.decorate('repositories', { … })before route registration. Aclear()method wipes per-test state.Pg<Domain>Repository— Drizzle calls against the real schema. Wired byplugins/repositories.tsin 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.