finance-app/CLAUDE.md

CLAUDE.md

Guidance for Claude Code when working in this repository.

Project Overview

Personal finance tracker. Bank statements are ingested via an N8N workflow (in the smarthome repo at docker/automation/workflows/cc-statement-processor-paperless.json) that sends PDFs to Gemini 2.5 Flash for extraction, then inserts into PostgreSQL.

• App: Next.js 16 App Router, TypeScript, Tailwind CSS
• DB: PostgreSQL container postgres-personal, database personal, user personal
• Auth: X-Forwarded-User header (email) set by Traefik → participants.email. In dev/fallback: participant id=1 ("Me")
• Runs at: port 3000 inside container, exposed on host port 4100, proxied at https://finance.bosecamp.com

Common Commands

Deployment is push-to-deploy via Komodo (since 2026-07-19): pushing to main on Gitea triggers the deploy-finance Procedure, which runs DeployStack --build on the finance stack (files_on_host over docker/finance/ in the smarthome repo). Just commit and push — no manual deploy needed.

# Manual fallback only (from smarthome repo root), e.g. if Komodo is down
docker compose --env-file docker/common.env --env-file docker/finance/.env \
  -f docker/finance/docker-compose.yml up -d --build

# IMPORTANT: docker restart does NOT pick up a new image — push to main (or use the compose command above)

# DB access
docker exec postgres-personal psql -U personal -d personal

# View logs
docker logs finance -f

Architecture

Key Files

File	Purpose
src/lib/db.ts	queryRaw<T>() — the only DB query function; uses pg directly
src/lib/queries.ts	All SQL query functions (no ORM); import queryRaw from @/lib/db
src/lib/hooks.ts	TanStack Query hooks for all API calls
src/lib/auth.ts	getCurrentUser() — reads X-Forwarded-User header
src/lib/categories.ts	Canonical category list (CATEGORIES array + formatCategory())
src/app/api/*/route.ts	API route handlers
src/components/	Shared UI components

Data Flow

• All queries in src/lib/queries.ts use raw SQL via queryRaw from src/lib/db.ts
• API routes call query functions and return NextResponse.json()
• Frontend uses hooks from src/lib/hooks.ts (TanStack Query) — never fetches directly
• Auth is always checked first in every API route: const user = await getCurrentUser(req)

Owner Scoping

All data is scoped by owner_id. The effective owner of a transaction is:

COALESCE(t.owner_id, s.owner_id)

• Statement-linked transactions: owner comes from statements.owner_id
• Manual transactions: statement_id IS NULL, owner stored directly in transactions.owner_id

The effective merchant and category always prefer overrides:

COALESCE(o.merchant_normalized, t.merchant_normalized, t.merchant_name)  -- merchant
COALESCE(o.category_override, t.category)                                 -- category

Database

# Schema inspection
docker exec postgres-personal psql -U personal -d personal -c "\d transactions"

# Apply a migration SQL file
docker exec postgres-personal psql -U personal -d personal < prisma/migrations/<name>/migration.sql

Key Tables

• statements — one row per billing period per bank account
• transactions — line items; statement_id is nullable (NULL = manual entry); reconciled_with_id links a manual tx to its matched statement tx; payment_method (migration 0016) is card | cash | bank_transfer | other, NULL = unknown

Cash and reconciliation

payment_method = 'cash' excludes a transaction from reconciliation via the notCash() fragment in queries.ts. Cash never appears on a statement, so without it a cash entry sits in the pending queue forever being offered matches within 3 days and 1% on amount — and accepting one is silently destructive: reconciled manual rows are filtered out of every query, so the cash spend disappears while the card transaction it matched claims to be that same spend.

Only cash is excluded. Bank transfers do appear on a statement now that transaction accounts are imported, and NULL means unknown — both stay candidates, preserving the behaviour of every pre-existing row.

ATM withdrawals stay categorised as spend rather than transfers. Treating them as transfers only works if every cash purchase is logged; with partial logging it silently deletes the unlogged remainder from spend totals.

• transaction_overrides — user corrections to AI-extracted data (category, merchant, notes)
• transaction_splits — shared expense tracking (participant, share_percent, settled)
• split_payments — recorded cash settlements between participants
• transaction_tags — many-to-many join to tags
• rules — auto-categorisation rules (JSONB conditions + actions)
• rule_apply_runs — audit log of bulk rule-apply runs with full snapshot for revert
• expense_metadata — enrichment from email receipts; transaction_id nullable until reconciled
• participants — people; id=1 is "Me" (the primary user)
• account_owner_mappings — persists bank+account → owner assignments

Import Date (created_at)

transactions.created_at is the import timestamp (DB default now()). In the transactions and shared views, the "Imported" column shows:

• For statement transactions: when the statement was processed by N8N
• For reconciled transactions: the created_at of the original manual/CSV transaction (via LEFT JOIN transactions src ON src.reconciled_with_id = t.id) — so the original import date is preserved post-reconciliation

Use created_at (not transaction_date) to answer "what was added since the last settlement?". Sort by created_at is supported server-side in getTransactions and client-side in the shared view.

Rules System

Conditions are AND-evaluated. Fields: merchant_normalized, description, category, bank_name, amount, transaction_type. Operators: contains, equals, starts_with, gt, lt, not_equals. Actions: set_category, set_merchant, add_tag_ids, apply_split.

contains and equals operators are case-insensitive (both sides .toLowerCase()).

Development Patterns

Adding a new API route

1. Create src/app/api/<resource>/route.ts
2. Always call getCurrentUser(req) first; return 403 if null
3. Write SQL in src/lib/queries.ts using queryRaw
4. Add a TanStack Query hook in src/lib/hooks.ts

Adding a new condition field to rules

Two files only:

• src/app/api/rules/apply/route.ts — add to Condition.field union, TxFields interface, and evaluateCondition() switch
• src/app/rules/page.tsx — add to FIELDS array; add special rendering if needed (e.g. enum dropdown for transaction_type)

Modifying queries

• All JOINs to statements must be LEFT JOIN (manual transactions have no statement)
• Owner filter pattern: WHERE COALESCE(t.owner_id, s.owner_id) = $1
• Bank name pattern: COALESCE(s.bank_name, 'Manual') as bank_name

Analytics queries must import the fragments from src/lib/analytics-sql.ts (STATEMENTS_JOIN, OWNER_SCOPE, EFFECTIVE_CATEGORY, EXCLUDE_NON_SPEND) rather than hand-rolling them. Two failure modes they exist to prevent:

• An INNER JOIN statements + WHERE s.owner_id = $1 silently drops every manual/CSV transaction (statement_id IS NULL).
• Spend must exclude the transfers and investment categories. Once bank statements are imported alongside card statements, a credit-card payment appears twice — as a debit leaving the bank account and as the underlying purchases on the card statement. Excluding transfers is what nets it out. Use the EXCLUDE_NON_SPEND fragment: a bare category NOT IN (...) evaluates to NULL for uncategorised rows and drops them from totals.

Statement types

statements.statement_type is constrained to credit_card | transaction | savings | loan | offset | investment | other. Migration 0013 added a normalize_statement_type() SQL function plus a BEFORE INSERT/UPDATE trigger, so the N8N workflow can keep sending raw free text ('ACCESS ADVANTAGE', 'Business Card') and the DB normalises it on write. The raw extracted value is preserved in account_type.

The TypeScript mirror is src/lib/statement-types.ts — keep the list, the SQL function, and the CHECK constraint in sync when adding a type.

Loans

A loan repayment is not an expense. It is part principal (equity, a balance-sheet move) and part interest (the only part that is spend). Migration 0014 adds:

• transactions.principal_amount / interest_amount — populated only when the lender itemises the split on the repayment row itself
• statements.interest_rate, scheduled_repayment, repayment_frequency, redraw_available, loan_term_months

Two statement shapes, both handled:

1. Separate rows (the common Australian case) — the loan statement lists repayments and "Interest Charged" separately. transaction_type alone is enough: interest rows count as spend, payment rows don't. No split columns needed.
2. Itemised repayment row — some lenders print principal and interest on the repayment line. That row is typed payment, so it would be skipped entirely and its interest lost. The SPEND_ROWS / SPEND_BASE fragments in analytics-sql.ts handle it: a row with a non-null interest_amount counts as spend, valued at interest_amount rather than amount.

The N8N Parse Gemini Result node only accepts a split when both parts are present and they sum to the row amount (±2c) — a half-extracted split would silently misreport spend, so it is discarded rather than trusted.

Loan interest uses the loan_interest category; principal repayments use investment (excluded from spend, surfaced on the investments line in monthly analytics).

Prisma

The schema at prisma/schema.prisma covers all tables. The generated client (gitignored) must be regenerated after schema changes:

cd /mnt/m2cache/appdata/finance-app && npx prisma generate

Docker builds run npx prisma generate automatically. Do not commit src/generated/prisma/ — it is gitignored.

Agent / MCP Access

Agents read this DB through the read-only postgres-personal MCP server (lives in the personal-agent-gateway repo, not here): agent_ro role, SELECT-only, SQLGlot guardrail, 100-row cap, every call audited to mcp_query_log. See docs/agent-access.md for the tool list, the five analysis views, and per-client setup (Claude Code, Codex, Hermes).

Two things to remember when changing the schema: the agent views are created by smarthome/personal-agent/migrations/006_agent_read_role_views.sql (not Prisma) and read transactions/statements/expense_metadata columns directly — rename a column and they break or go stale. And the views are not owner-scoped and do not merge transaction_overrides, so agent numbers can differ from the UI.

Known Gaps / TODOs

See README.md → Known Gaps / TODOs for full details.

Payment provider tracking: merchant_normalized currently conflates payment provider (PayPal, Afterpay, Zip) with the actual merchant. Plan: add payment_provider column, update Gemini prompt to extract it separately, backfill from merchant_name patterns, surface in UI filters.