# CLAUDE.md

Guidance for agents working in `app_backend`, the replacement Upharm API.

## Workspace

- `../backend` is the legacy Express/Mongoose API and the behavioral reference.
- `../frontend` is the legacy SvelteKit member application.
- `../admin` is the legacy SvelteKit administration application.
- `app_backend` is the new Express/TypeScript/Prisma/SQLite API.

## Migration rules

- Move one domain at a time and keep legacy `/v1` and `/v2` response contracts
  compatible until the Next.js clients are ready.
- No legacy data is migrated: the SQLite database starts empty and all ids are UUIDs.
- Use Prisma transactions whenever a legacy operation updates multiple documents.
- Do not run `prisma migrate dev` or destructive migration commands in production.
- The replacement API must not introduce Mongoose or MongoDB dependencies.
- Never commit `.env`, credentials, customer uploads, or generated Prisma Client.

## Commands

- `npm run db:validate` validates the relational schema.
- `npm run db:generate` generates the Prisma client.
- `npm run typecheck` checks TypeScript without emitting files.
- `npm run build` generates Prisma Client and builds the application.
- `npm test` runs the non-database baseline checks.

See `docs/UPHARM_MYSQL_MIGRATION.md` for the phased migration sequence (written for MySQL;
the runtime database is now SQLite — the original MySQL schema and migration are kept in `docs/archive/mysql/`).

## SQLite notes

- `DATABASE_URL` is a `file:` URL; relative paths resolve from `prisma/`.
- `createMany({ skipDuplicates })` and `mode: "insensitive"` are not supported — de-duplicate input instead.
- Unique text columns are case-sensitive: always normalize emails before reading or writing.
- WAL, busy_timeout and foreign_keys pragmas are applied in `src/lib/prisma.ts`.