# CLAUDE.md — Kept

Kept is a self-hosted personal finance app: accounts and their transactions, bills matched to
payments, tax payments reconciled against what the tax office counted, and balance history.
Paperless-ngx is an optional integration, never a requirement.

## This repository is public

- **Never commit real financial data.** No real account numbers, IBANs, card numbers, statement
  exports, amounts from real documents, names of the maintainer's banks, employers, addresses or
  people. Test fixtures are synthetic and live in `src/lib/testing/fixtures/`; use documented
  example IBANs only.
- **Code is format-based, not institution-based.** Importers are named after file formats
  (`camt053`, `csv`), never after a bank. Institution-specific CSV column mappings are user
  configuration stored in the database, not code.
- The `leak-guard` hook blocks locally configured private terms (`.private-terms`, gitignored).
  If it fires, remove the data — never weaken the hook or add the term to a tracked file.
- Commit messages and PR texts follow the same rules. Never mention AI tools in them.

## Commands

```bash
bun dev                  # dev server
bun run verify           # format:check + lint + check + test — run before every commit
bun run format           # prettier --write
bun run lint:fix         # eslint --fix
bun run check            # svelte-kit sync + svelte-check
bun run test             # vitest (unit, SQLite)
bun run test:coverage
bun run test:pg          # the suite on PostgreSQL (needs KEPT_TEST_DATABASE_URL; CI runs it too)
bun run build && bun run start
bun run db:generate      # after editing src/lib/server/db/schema.ts: writes drizzle/sqlite and drizzle/postgres
                         # (db:generate:sqlite / db:generate:pg for one dialect)
bun run leak-guard --all # scan the whole tree for private terms
bun run security         # semgrep, bun audit, trivy
```

Bun only — never npm, pnpm or yarn. Hooks run via prek: `prek install` once per clone.

## Stack

Bun · SvelteKit (`svelte-adapter-bun`) · TypeScript strict · Svelte 5 runes · Tailwind CSS v4 ·
shadcn-svelte (`$lib/components/ui/`, add with `bunx shadcn-svelte@latest add <name>`) ·
`@lucide/svelte` · Drizzle ORM on SQLite (`bun:sqlite`, the default) or PostgreSQL 17+ (`Bun.SQL`) ·
files on disk or in S3 (`Bun.S3Client`) · Zod · Vitest · pdfmake for PDF
reports (no Typst, no headless browser).

## Architecture

```
src/lib/money.ts                 Minor-unit money type + parsing/formatting (the only way to handle amounts)
src/lib/server/db/index.ts       facade: getDB() (resolves the open transaction), transaction({ lock }), afterCommit(), first(), isUniqueViolation(), likeContains(); runs migrations on startup
src/lib/server/db/sqlite.ts      SQLite backend (bun:sqlite, WAL, foreign keys) behind a FIFO gate (gate.ts): one connection, one transaction at a time
src/lib/server/db/postgres.ts    PostgreSQL backend (Bun.SQL pool, advisory locks, migration lock)
src/lib/server/db/config.ts      readDatabaseConfig(): DATABASE_URL / DATABASE_PATH / KEPT_DB_*, validated with Zod
src/lib/server/db/dialect.ts     which dialect this process uses ("sqlite" | "pg"), from DATABASE_URL; no bun: imports (drizzle-kit loads it)
src/lib/server/db/columns.ts     dialect-switched schema builders — the only way to declare columns
src/lib/server/db/schema.ts      Drizzle schema — one file, written with columns.ts; every table has created_at/updated_at
src/lib/server/db/search.ts      escapeLike(), likeContains(): portable case-insensitive text search
src/lib/server/storage/          BlobStore (put/get/has/delete/list) for user files: fs.ts (default), s3.ts, config.ts (KEPT_STORAGE*, KEPT_S3_*), getStore()
src/lib/server/auth/             local users (Bun.password argon2id), sessions in the database
src/lib/server/importers/        file format → NormalizedStatement[] (pure, no DB access)
src/lib/server/imports/          upload → preview → confirm flow, history/undo, CSV mapping profiles
src/lib/server/ledger/           institutions, accounts, transactions, snapshots, balances
src/lib/server/bills/            bills, documents, QR-bill/PDF extraction, bill ↔ payment matching
src/lib/server/dashboard/        aggregate queries for the dashboard
src/lib/server/events.ts         generic in-process events (integrations subscribe; core emits)
src/lib/server/integrations/     optional adapters (paperless/) — the core never imports these
src/lib/server/reports/          pdfmake document builders
src/lib/{money,iban,references}.ts  client-safe helpers for amounts, IBANs, QRR/SCOR references
drizzle/{sqlite,postgres}/       generated migrations, one folder per dialect (never edit by hand)
src/routes/                      UI + API (`src/routes/api/`)
src/lib/testing/fixtures/        synthetic sample files for importer tests
```

## Invariants

- **Money is `Minor` (integer minor units) plus an ISO 4217 currency code.** Never floats, never
  `Number(amountString)`. Parse with `parseAmount`, format with `formatAmount`.
- **Booking/value dates are `YYYY-MM-DD` strings**; instants are `timestamp_ms` integers.
- **Importers are pure**: `(file contents, options) → NormalizedTransaction[]`. Each result
  carries a stable `externalId` (bank reference, or a hash of the raw row when the file has none)
  so re-importing overlapping files never duplicates transactions.
- **Every query is scoped to the current user.** No endpoint returns another user's data.
- **External input is parsed with Zod** (forms, API bodies, imported files, integration payloads).
- **Paperless is an adapter.** Nothing outside `integrations/paperless/` knows about Paperless;
  a bill may reference a Paperless document id, but works without one.
- **Transactions are `transaction(async (tx) => …)` from `$lib/server/db`.** Inside, `getDB()` resolves to
  the same `tx`; a nested call is a savepoint. Await every query. **No network or file I/O inside a
  transaction body** (the whole database waits behind it, FIFO): do I/O before it, or in `afterCommit()`,
  which also carries events (`emitBillChanged`) and log lines that must only follow a commit. CPU-heavy work
  (detection, hashing) runs outside too: read, compute, then a short transaction that re-checks and writes.
  **Never await a promise or query builder that was created outside the current transaction from inside
  its body**: if it needs the database it queues behind the transaction that is waiting for it, and both
  hang until the gate timeout. `afterCommit` hooks are awaited before `transaction()` returns, so keep
  them short; long I/O belongs in a detached task the hook starts. Work still running when a transaction
  rolls back fails ("rolled back") instead of writing outside it, savepoints started side by side run one
  after the other, and a transaction open longer than the watchdog (60 s) is rolled back by the database layer
  (PostgreSQL: `transaction_timeout`, `KEPT_DB_TRANSACTION_TIMEOUT_MS`).
- **Always await queries.** Builders are awaited, never run with `.all()/.get()/.run()/.values()/.execute()`;
  a forgotten `await` drops the query. Lint enforces both (`no-floating-promises` with `checkThenables`,
  `kept/no-query-terminals`, by receiver type).
- **No raw SQL outside the `db/` helpers.** Use drizzle builders and `likeContains()`, `first()`, `alias`. A raw
  `sql` fragment is allowed only when it is portable and passes `kept/no-pg-only-api` (the lint rule lists
  what is banned); dialect-specific SQL belongs in `db/`.
- **User files go only through `BlobStore`** (`getStore()` from `$lib/server/storage`): uploaded bills and
  pending imports are never written with `node:fs` or an S3 client directly, so both storage backends
  keep working. The watch folder and scheduled SQLite backups are the only other code that touches user files on disk.
- **Queries must run on SQLite and PostgreSQL.** Columns come from `db/columns.ts` only; PostgreSQL-only
  drizzle APIs and `::` casts in raw SQL are banned by lint outside `db/`. Aggregates and raw
  `sql<number>` go through `.mapWith(Number)` (PostgreSQL returns int8 and numeric as strings), and a
  timestamp is read as a Date column (`max(col)`), never as a raw `sql<number>`. Text search uses
  `likeContains()`, not `like`; SQLite-only functions (`strftime`, `ifnull`, `group_concat`, scalar
  `min/max`, `char`, `rowid`) are banned by lint. A cross-row invariant (check, then write across rows)
  takes `transaction(fn, { lock })`: a no-op on SQLite, an advisory lock on PostgreSQL. One key per
  transaction (enforced in tests): ledger, transfer, import, trade and snapshot writes share
  `ledgerLock` (`ledger/lock.ts`), bills and allocations `billsLock`. Every list a
  user sees has a total `ORDER BY`. Migrations: `bun run db:generate` writes both `drizzle/sqlite/` and
  `drizzle/postgres/` (never edit either by hand except for data fix-ups); `DATABASE_URL=postgres://…`
  selects PostgreSQL (see `db/config.ts`). `bun run test:pg` runs the whole suite on PostgreSQL
  (`KEPT_TEST_DATABASE_URL=postgres://…` to a server of its own; each test file gets a database cloned
  from a migrated template), and CI runs it on every push. Tests that only make sense on SQLite say why.
- **No swallowed errors.** No empty `catch`, no `catch { return null }` without logging and a
  user-visible outcome.
- Never log transaction descriptions, counterparties, IBANs or amounts.
- Never log the `message` of a database error: drizzle's `DrizzleQueryError` carries the SQL and the bound
  values (password hashes, TOTP secrets). Log `describeError(err)` / `errorCode(err)` from `$lib/server/errors`.

## Svelte 5

Runes only: `$state`, `$derived`, `$effect`, `$props`, `{@render children()}`. No `export let`,
no `$:`, no `<slot />`, no stores for component state. Use Tailwind classes and `cn()` from
`$lib/utils`; no component CSS files.

## Testing

- Unit tests sit next to the code (`foo.ts` → `foo.test.ts`).
- Importers and matching are tested against synthetic fixtures covering edge cases: overlapping
  files, missing references, foreign currencies, reversals, negative amounts.
- Bug fixes start with a failing test.

## Subagents (`.claude/agents/`)

| Agent        | Scope                                                                                     |
| ------------ | ----------------------------------------------------------------------------------------- |
| `backend`    | schema, migrations, auth, ledger, bills, matching, reports, API routes, Paperless adapter |
| `importer`   | file-format parsers + their synthetic fixtures and tests                                  |
| `frontend`   | Svelte pages and components, forms, tables, charts                                        |
| `reviewer`   | read-only review of a change against these invariants and the privacy rules               |
| `researcher` | read-only research on external systems, standards and APIs; returns a cited report        |

Split a feature by layer: backend first (with tests), then frontend, then `reviewer`.

## Git

Conventional commits (`feat:`, `fix:`, `refactor:`, `chore:`, `docs:`, `test:`, `ci:`).
Run `bun run verify` before committing. Never commit `.private-terms`, `.env` or anything in `data/`.