Crystal Fountain pledge platform

Pledge platform for the Crystal Fountain Development Project, the building fund for Newlife SDA Church, Nairobi. Members and well-wishers record a pledge toward the KES 550,000,000 target, get a reference number and a QR code, and see live campaign progress.

A pledge is a promise to give, not a payment. The treasurer's receipt is the only receipt.

Project rules live in CLAUDE.md. Read that before changing anything.

Resolved versions

Every dependency is pinned to an exact version in package.json. No carets, no tildes. .npmrc sets save-exact=true so future installs stay pinned.

Package	Version
next	15.5.25
react	19.2.8
typescript	5.9.3
tailwindcss	4.3.3

React DOM tracks react at 19.2.8. shadcn/ui was initialised with the radix-nova preset and the neutral base colour.

Requirements

• Node 20 or newer
• pnpm 11.21.0 (see packageManager in package.json)
• A Neon Postgres database

Setup

pnpm install
cp .env.example .env.local
# fill in DATABASE_URL and NEXT_PUBLIC_SITE_URL
pnpm dev

src/env.ts validates the environment with Zod and is imported once from the root layout, so a missing variable fails the build rather than a request in front of a user.

Scripts

Script	What it does
pnpm dev	Development server on http://localhost:3000
pnpm build	Production build. Uses --turbopack, see below
pnpm start	Serve the production build
pnpm lint	ESLint
pnpm db:generate	Generate SQL migrations from src/db/schema.ts
pnpm db:migrate	Apply migrations to the database in .env.local

The build must run with --turbopack. Plain next build produced an incompatible routes manifest on the church's camp meeting site and the same gotcha applies here.

Layout

drizzle.config.ts       drizzle-kit config, reads .env.local
src/env.ts              Zod validated environment
src/db/index.ts         Neon WebSocket pool plus Drizzle client, exports db, Db and Tx
src/db/schema.ts        Drizzle schema, empty for now
src/server/             Business logic. Plain functions taking a Db handle and typed input
src/server/money.ts     bigint minor unit helpers, percentages rounded once at the end
src/server/services/    Service functions
src/server/contracts/   Zod input and output contracts, shared client and server
src/app/api/            Thin route handlers. Parse, call the service, format
src/components/ui/      shadcn/ui components: button, input, card, label

Business logic in src/server/ never touches Request, Response, cookies or next/headers. That keeps the domain portable if the API is later split out to Fastify.

Environment

Key	Purpose
DATABASE_URL	Neon Postgres connection string, pooled endpoint
NEXT_PUBLIC_SITE_URL	Public origin of the site, no trailing slash

.env.local is gitignored. .env.example lists every key with no values.