ann-lite-api

Backend API powering Ann Lite content, users, donations, transparency and blockchain verification.

Repository 2 of 6 in the Ann Lite platform. Consumed by ann-lite-web and (soon) ann-lite-admin.

Tech stack

Layer	Choice	Version
Runtime	Node.js	20+
Framework	Fastify	5.11.3
Language	TypeScript (strict)	5.7.3
ORM / DB	Prisma + PostgreSQL	6.2.1 / 17
Auth	argon2id + JWT (@fastify/jwt)	—
Validation	zod	3.24.1
Blockchain	viem (Celo)	2.21.58
Tests	Vitest + Supertest-style Fastify inject()	3.0.4

All versions pinned in package.json.

Getting started

npm ci
cp .env.example .env
# Fill in JWT_ACCESS_SECRET / JWT_REFRESH_SECRET:
#   openssl rand -base64 48
docker compose up -d          # starts local Postgres
npx prisma generate
npx prisma migrate dev        # creates the database schema
npm run prisma:seed           # optional: adds sample dev content
npm run dev

API listens on http://localhost:4000. OpenAPI/Swagger UI is available at http://localhost:4000/docs outside production.

Scripts

Command	What it does
npm run dev	Local dev server with hot reload
npm run build	Compile TypeScript to dist/
npm start	Run the compiled server
npm run lint / format / typecheck	Code quality checks
npm test	Vitest unit + integration tests (needs Postgres)
npm run prisma:migrate	Create/apply a migration in development
npm run prisma:seed	Load sample development content

What's real vs. what's pending

This is a complete, working backend architecture — auth, RBAC, content, donations, transparency, audit logging — not a mockup. Two things are deliberately not wired to real external services yet, and fail closed (return a clear 503, never fake success) until they are:

1. Card payments — no concrete payment provider is registered (see TODO.md). POST /v1/donations/intent with method: "card" returns 503 payment_provider_unconfigured until one is.
2. Crypto verification — needs CELO_RPC_URL and CELO_TREASURY_ADDRESS configured. Until then, crypto intents and verification return 503.

Both are fully implemented against documented, real interfaces (src/lib/payment-provider.ts, src/lib/celo-verifier.ts) — connecting them is a configuration and credentials task, not a coding task.

Security highlights

See SECURITY.md for the full list. Headline points: argon2id password hashing, RBAC with an explicit permission allow-list, donation status only ever set server-side (webhook or on-chain verification — never client-declared), rate limiting, input validation on every route, no donor PII in logs or the public transparency endpoint.

Testing status (honest, per project rules)

Generated in a network-isolated environment: npm install, npx prisma generate, npm test (needs Postgres), and npm run build could not be executed here. The code is complete and believed correct against the pinned dependency APIs, but unverified — run the commands above (CI also runs them against a real Postgres service container) before treating this as production ready.

Creating the GitHub repository

cd ann-lite-api
git init
git add .
git commit -m "Initial commit: ann-lite-api v1.0.0"
git branch -M main

gh repo create ann-lite/ann-lite-api \
  --public \
  --description "Backend API powering Ann Lite content, users, donations, transparency and blockchain verification." \
  --source=. --remote=origin --push

git tag -a v1.0.0 -m "Ann Lite API v1.0.0"
git push origin v1.0.0

gh release create v1.0.0 --title "Ann Lite API v1.0.0" --notes-file CHANGELOG.md

License

MIT — see LICENSE.