Files

T

ci / lint-test (push) Successful in 41s

Details

docs: point work tracking at the board, not ACTIONS.md

Status for this app now lives on the Vikunja board (saved filter
finance-app), which replaced the smarthome repo's ACTIONS.md on 2026-07-30.

Notes the thing a single-label filter hides: a ticket can carry several
system labels — the receipt→pantry work is finance-app, pantry-app and
email-ingestion at once — so the finance filter is a view, not the boundary
of what will touch this codebase.

Also records the one dated item here: postgres-personal runs PostgreSQL 14,
EOL 2026-11-12, and it holds statements, transactions, orders and
expense_metadata.

2026-07-30 23:12:50 +10:00

3.2 KiB

Raw Blame History

Repository Guidelines

Project Structure & Module Organization

Application code lives in src/. Next.js App Router pages and API route handlers belong in src/app/; reusable UI components are in src/components/; database access, query functions, hooks, authentication, and domain helpers are in src/lib/. Tests are separated into src/__tests__/unit/ and src/__tests__/integration/. PostgreSQL schema and numbered SQL migrations live under prisma/, static assets under public/, operational scripts under scripts/, and design notes under docs/.

Keep data flow consistent: API routes call query functions in src/lib/queries.ts, which use queryRaw() from src/lib/db.ts; client components access APIs through TanStack Query hooks in src/lib/hooks.ts.

Task tracking is the Vikunja board at https://tasks.bosecamp.com (project Work, saved filter finance-app), which replaced the smarthome repo's ACTIONS.md on 2026-07-30. Update the ticket in the same change as the code. See CLAUDE.md → "Work tracking".

Build, Test, and Development Commands

npm ci installs the locked dependency set (Node 22 is used in CI).
npm run dev starts the local Next.js development server.
npm run build creates a production build; npm start serves it.
npm run lint runs the Next.js ESLint configuration. Existing lint debt makes CI lint advisory, but new code should pass.
npm test runs fast unit tests.
npm run test:setup prepares the PostgreSQL test database using .env.test.
npm run test:integration runs database-backed tests.
npm run test:all runs both test suites.

Coding Style & Naming Conventions

Use strict TypeScript, two-space indentation, semicolons, and double quotes, matching existing files. Name React components and types in PascalCase, functions and variables in camelCase, and files/routes in kebab-case. Use the @/ alias for imports from src/. Preserve owner scoping and prefer transaction overrides with COALESCE in financial queries. Every API route must authenticate before accessing data.

Testing Guidelines

Vitest is the test framework. Name tests *.test.ts and place pure logic tests under unit/; put PostgreSQL-dependent behavior under integration/. Add regression coverage for query, rule, reconciliation, and category changes. No numeric coverage threshold is configured; focus on meaningful edge cases and run npm run test:all before submitting database-related changes.

Database, Security & Configuration

Add schema changes as the next numbered prisma/migrations/NNNN_description/migration.sql. Never commit .env, .env.test, raw statements in dump/, or other financial data. Consult CLAUDE.md and relevant docs/ notes before changing splits, settlements, loans, reconciliation, or statement accounting.

Commits & Pull Requests

History follows concise Conventional Commit-style subjects such as feat(rules): preview rule changes, fix(trips): ..., and docs: .... Keep commits focused. Pull requests should explain behavior and data-model impact, link related issues, list validation commands, and include screenshots for UI changes. Ensure unit tests and the production build pass; call out any known lint warnings or migration steps.

3.2 KiB Raw Blame History