fms-api

Express + TypeScript reference implementation for FFMS REST modules. Copy .cursor/rules/ffms-backend-express.mdc, ffms-api-stack.mdc, and ffms-api-engineering.mdc as the authority.

Layout

• src/app.ts — createApp(env) for server + Vitest/Supertest (no listen).
• src/features/<name>/ — *.routes.ts, *.controller.ts, *.service.ts, *.repository.ts, *.schemas.ts.
• src/db/ — Drizzle client + schema/ (align migrations with docs/schema/ffms_postgresql.sql).

Reference modules:

Module	Route	Notes
health	GET /api/v1/health	No database.
contributions	GET /api/v1/contributions	D2 list by memberId + optional cycleYear / cycleMonth; requires DATABASE_URL.

Run

cp .env.example .env
npm install
npm run dev

Git hooks (Husky)

Hooks and config live only under this package (fms-api/.husky, lint-staged.config.mjs).

• prepare runs node scripts/husky-prepare.mjs, which finds the git root and runs husky pointing at fms-api/.husky when this repo is a monorepo with a parent .git, or at .husky when fms-api is the repository root.
• .husky/pre-commit → lint-staged (ESLint + Prettier on staged files here).
• .husky/pre-push → npm run typecheck, npm test, and npm run build.

Run npm install from fms-api/ after clone so hooks install. In CI, set HUSKY=0 (and/or CI=true) to skip the install step.

Tests

npm test        # Vitest once (used in pre-push)
npm run test:watch

• Unit: Zod schemas, health service/controller, contributions service/controller (src/**/*.test.ts).
• HTTP integration: createApp + Supertest (src/create-app.http.test.ts) — no listen(), per ffms-api-stack.mdc.

Repository integration tests against real Postgres are optional (see engineering rules); not included here.

Error JSON (for fms-web i18n)

Errors use a stable code string where possible:

{ "code": "VALIDATION_FAILED", "message": "…" }

Supertest (manual example)

import request from "supertest";
import { createApp } from "./app";
import { loadEnv } from "./config/env";
import { initDb } from "./db";

const env = loadEnv();
initDb(env.DATABASE_URL);
const app = createApp(env);

const res = await request(app).get("/api/v1/health").expect(200);

Add Vitest + supertest per .cursor/rules/ffms-api-stack.mdc for CI.