siddharthd
549abd8cca
ci / lint-test (push) Successful in 41s
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.
37 lines
3.2 KiB
Markdown
37 lines
3.2 KiB
Markdown
# 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.
|