ADR 0004: The engine is Fastify + pg; NestJS lives in the SDK

Status: superseded by ADR 0005 · accepted 2026-09-02 (deviation from the plan, which said NestJS + Prisma). The engine this describes is at the git tag node-server-final; the SDK’s Nest module, below, is unaffected.

Context

The design plan proposed NestJS 11 and Prisma 7 for the server to match instastack. Building it showed two frictions. The engine’s hot path is raw SQL by nature (FOR UPDATE SKIP LOCKED, jsonb state, window functions for rate-limited resume), so Prisma would wrap every important query in $queryRaw anyway. And Nest’s DI needs emitDecoratorMetadata, which the fast test tooling (vitest/esbuild) does not emit, pushing tests toward slower ts-jest configuration for no engine benefit.

Decision

The server is plain TypeScript on Fastify with pg and SQL migration files. Schema lives in apps/server/src/db/migrations/*.sql; queries are visible SQL. NestJS is supported where applications meet Foliot: @foliot/sdk/nest exports a FoliotModule and controller, alongside the Express adapter.

Consequences

• The engine is small and legible: one query per behaviour, no generated client.
• instastack services integrate through the Nest module, which is the part they see.
• Anyone changing the engine reads SQL, not an ORM schema.