Financial Controller MVP
Finds money users are losing and turns each finding into a yes/no decision card. See
docs/spec.md for the full spec and CLAUDE.md for the rules.
How it fits together
docs/architecture.md is the map: the folders and what lives where, how
data moves from a bank to Jane's cards and chat, the rules every change keeps (user scoping,
the audit log, guardrails, advice mode, trial people, the paper account), the scheduled jobs,
and how deploys work.
Setup
- Use Node from
.nvmrc (nvm use).
cp .env.example .env and fill in DATABASE_URL, DIRECT_URL and AUTH_SECRET. Without
RESEND_API_KEY, magic links print to the dev server console; without the Google keys,
the Google button is hidden.npm install (also generates the Prisma client).npx prisma migrate dev to apply migrations.npx playwright install chromium once, for end-to-end tests.- Optional: export
TEST_DATABASE_URL pointing at a scratch database and run
DIRECT_URL=$TEST_DATABASE_URL npx prisma migrate deploy so npm test also runs the
cross-user access test against real Postgres (CI always does).
On Vercel, the vercel-build script applies pending migrations (prisma migrate deploy, using
DIRECT_URL) before production builds only, so preview deployments never change the database.
Importing your own data
Sign in, then go to /import: add an account (with its current balance, which bank exports
leave out), upload CSV exports and confirm. Supported formats live in
src/data-sources/csv/formats.ts; sample files in src/data-sources/csv/__fixtures__/ are
made up. Keep real exports in private/, which git ignores.
To make someone an admin, set their role in the database:
UPDATE users SET role = 'admin' WHERE email = '[email protected]';
Commands
| Command | What it does |
|---|
npm run dev | Start the app on localhost:3000 |
npm test | Unit tests (Vitest) |
npm run test:e2e | End-to-end tests (Playwright) |
npm run lint | ESLint |
npm run typecheck | TypeScript check |
npm run format | Format with Prettier |
npm run checks:answers | Jane's answer checks (spec step 87) against the scratch database in TEST_DATABASE_URL: rules questions only without ANTHROPIC_API_KEY, everything plus Claude's grades (within a spending cap) with it. Saves the run and compares it with the last one. |
