personal-finance-notion

activetype/moc

Personal Finance Notion

Doc boundary: narrative, decisions, backlog, changelog, and runbooks live in this vault under Projects/personal-finance-notion/. Architecture, data model, feature deep-dives, integrations specs, and testing notes belong in the app repo's docs/ (see app AGENTS.md and docs/README.md). Vault is for why and what's next; repo docs/ is for how it works today.

TL;DR

Personal Finance Notion is a solo-built Next.js 15 (App Router + Turbopack) personal finance tracker with MongoDB + Mongoose: track transactions across multiple bank accounts, manage income/expense categories with budgets, visualize cash flow on a chart-heavy dashboard, plan future purchases via wishlist, and pull in transactions through an AI-assisted bulk-import pipeline (OpenRouter). Ships as a PWA with offline-first writes via an IndexedDB outbox and exposes a bearer-authenticated integrations API so an external AI agent can push parsed BCA bank-email transactions on a schedule. LumenDev internal product line — mg is both developer and client.

Outcome

  • Problem: scattered personal-finance tracking across bank apps, spreadsheets, and Notion exports — no unified view of cash flow, budgets, or net worth across accounts.
  • Desired outcome: a single, fast, offline-capable tracker that ingests transactions (manual + AI-parsed from bank emails), enforces category budgets, and answers "where did the money go this month" in one screen.
  • Success metric: > TODO — define (e.g. % of transactions captured automatically vs. manual, time-to-add a transaction, daily active use streak).
  • Scope (in): transactions (income/expense/transfer), bank accounts, categories + budgets, dashboard charts, wishlist, bulk AI import, PWA offline writes, integrations API for agent push.
  • Scope (out): multi-user/sharing, investment-portfolio tracking, payment integrations (Stripe/Plaid), email delivery, mobile-native apps.

Status

  • Current phase: pre-launch · Auth.js Phases A–D complete 2026-05-24
  • Next milestone: UX p0 ([[Projects/personal-finance-notion/backlog/p0-search-filter-transactions|search/filter]], [[Projects/personal-finance-notion/backlog/p0-recurring-transactions|recurring]]) + auth follow-ups (p1/p2). Ops: [[Projects/personal-finance-notion/backlog/p2-csp-enforce-production|CSP enforce on production]] after staging soak.
  • Target date: 2026-W23 / W24
  • Health: green (auth migration + hardening code shipped; CSP enforcing is ops-only)

Quick Links

  • [[Projects/personal-finance-notion/context/index|Project context]]
  • [[Projects/personal-finance-notion/decisions/index|Decisions]]
  • [[Projects/personal-finance-notion/backlog/index|Backlog]]
  • [[Projects/personal-finance-notion/changelog/index|Changelog]]
  • [[Projects/personal-finance-notion/runbooks/index|Runbooks]]

Implementation references (dated snapshots — see repo docs/architecture/ for always-current):

  • [[Projects/personal-finance-notion/context/auth-as-built-2026-05-19|Auth as-built — 2026-05-19]] (after Phase C ship)

Open Decisions

  • [[Projects/personal-finance-notion/decisions/adr-2026-05-18-authjs-migration|ADR 2026-05-18 — Migrate auth to Auth.js v5]] — accepted (supersedes auth section of 2026-05-17 stack snapshot)
  • [[Projects/personal-finance-notion/decisions/adr-2026-05-17-stack-snapshot|ADR — Stack snapshot (2026-05-17)]] — accepted (as-built record)

Active Backlog

✅ Auth.js migration (Phases A–D) — see backlog/done/ and [[Projects/personal-finance-notion/decisions/adr-2026-05-18-authjs-migration|ADR 2026-05-18]].

  • [[Projects/personal-finance-notion/backlog/done/p0-authjs-phase-a-foundation|Phase A]] (d5b94ce) · [[Projects/personal-finance-notion/backlog/done/p0-authjs-phase-b-features|Phase B]] (ea61b6a) · [[Projects/personal-finance-notion/backlog/done/p0-authjs-phase-c-hardening|Phase C]] (01d9ac3) · [[Projects/personal-finance-notion/backlog/done/p0-authjs-phase-d-pre-launch-hardening|Phase D]] (2026-05-24)

Audit C1–C4 closed 2026-05-24 (moved to backlog/done/):

  • ✅ [[Projects/personal-finance-notion/backlog/done/p0-c1-password-reset|C1 · Password reset]]
  • ✅ [[Projects/personal-finance-notion/backlog/done/p0-c2-email-verification|C2 · Email verification]]
  • ✅ [[Projects/personal-finance-notion/backlog/done/p0-c3-signup-enumeration|C3 · Signup enumeration]]
  • ✅ [[Projects/personal-finance-notion/backlog/done/p0-c4-api-error-leakage|C4 · API error leakage]] — f21f71d

Auth follow-ups (spun out of C1–C3 gaps, 2026-05-24):

  • [[Projects/personal-finance-notion/backlog/p1-password-reset-rate-limits|p1 · Password reset rate limits]]
  • [[Projects/personal-finance-notion/backlog/p1-email-verification-resend-ui|p1 · Email verification resend UI]]
  • [[Projects/personal-finance-notion/backlog/p1-signup-timing-equalization|p1 · Signup timing equalization]]
  • [[Projects/personal-finance-notion/backlog/p2-auth-token-flow-edge-e2e|p2 · Auth token edge-case E2E]]
  • [[Projects/personal-finance-notion/backlog/p2-signup-enumeration-e2e|p2 · Signup enumeration E2E]]
  • [[Projects/personal-finance-notion/backlog/p2-csp-enforce-production|p2 · CSP enforce on production]]

Audit findings remap: [[Projects/personal-finance-notion/context/audit-2026-05-17-auth|Auth audit 2026-05-17]] — C1–C4 done; M1/M3 superseded by Auth.js; L1 shipped Phase C.

Hardening backlog (post-launch):

  • [[Projects/personal-finance-notion/backlog/p1-auth-hardening-medium|Auth hardening (medium) — M1–M5]] — p1 (M1+M3 dropped post-migration)
  • [[Projects/personal-finance-notion/backlog/p2-auth-backlog-low|Auth backlog (low) — L1–L7]] — p2 (L1 elevated; L2–L7 still apply)

UX backlog (queued behind launch work):

  • [[Projects/personal-finance-notion/backlog/p0-search-filter-transactions|Search/filter transactions on home page]] — p0
  • [[Projects/personal-finance-notion/backlog/p0-recurring-transactions|Recurring transactions]] — p0
  • [[Projects/personal-finance-notion/backlog/p1-add-transaction-form-ux|Add Transaction form UX polish]] — p1
  • [[Projects/personal-finance-notion/backlog/p1-custom-range-dashboard|Custom date-range filter on dashboard]] — p1
  • [[Projects/personal-finance-notion/backlog/p1-home-page-production-latency|Home page (/) production latency]] — p1

More items in docs/todo.md (app repo) and [[Projects/personal-finance-notion/backlog/index|backlog index]].

Recent Changes

  • 2026-05-24 — Moved Auth.js Phases A–D and audit H1–H4 to backlog/done/; active follow-ups: p1 auth gaps + p2 E2E/CSP enforce.
  • 2026-05-23 — [[Projects/personal-finance-notion/changelog/2026-05-23-import-duplicate-timezone|Bulk import fuzzy duplicate detection uses user timezone]] — checkBulkImportDuplicates matches civil calendar day from User.settings.timezone (not UTC-only); new zonedDayBoundsFromEpoch helper.
  • 2026-05-19 — [[Projects/personal-finance-notion/changelog/2026-05-19-integration-api-keys|Integration API redesign — per-user keys]] (01d9ac3). Legacy PREFIX + User._id Bearer scheme retired; new IntegrationKey model with sha256-hashed keys, expiry, revocation, last-used tracking; create/list/revoke UI on /config/user. Was audit L1.
  • 2026-05-19 — [[Projects/personal-finance-notion/changelog/2026-05-19-authjs-phase-b-features|Auth.js v5 Phase B shipped]] (ea61b6a). Google OAuth with auto-link, email verification gate, password reset with session revocation (sessionsValidAfter), enumeration-safe C3 full fix, Resend transactional email, custom mongoose adapter.
  • 2026-05-18 — [[Projects/personal-finance-notion/changelog/2026-05-18-authjs-phase-a-foundation|Auth.js v5 Phase A foundation shipped]] (d5b94ce). Bespoke JWT stack collapsed to a 60-line shim; Credentials provider + middleware + AuthContext compat hook + ~50 consumers compile unchanged.
  • 2026-05-18 — [[Projects/personal-finance-notion/changelog/2026-05-18-authjs-migration-decision|Auth.js migration decision + Day-1 audit fixes]] (f21f71d: C4 + H4). H3 absorbed by Phase A; C3 partial mask bundled into d5b94ce.
  • 2026-05-17 — [[Projects/personal-finance-notion/changelog/2026-05-17-vault-hub-created|Vault project hub created]] and linked from [[Areas/LumenDev/LumenDev]].
  • 2026-05-09 — [[Projects/personal-finance-notion/changelog/2026-05-09-model-alias-hybrid-overview|@model alias fix + hybrid API/actions overview]] (a105f08, PR #46).
  • 2026-05-03 — [[Projects/personal-finance-notion/changelog/2026-05-03-integrations-bulk-api|Integrations bulk API + AI agent docs]] (ffa39d9, dc48ece, 815bdc7).
  • 2026-04-19 — [[Projects/personal-finance-notion/changelog/2026-04-19-offline-first-writes|Offline-first writes + entity outbox]] (b92f1ef, adcddd7).
  • 2026-04-04 — [[Projects/personal-finance-notion/changelog/2026-04-04-import-chunking-image-processing|Bulk import: chunking + image + LLM cache]] (9feacd3, 38a20e0).

Risks & Blockers

  • CSP enforcing in production — policy ships report-only; flip CSP_ENFORCE=true after staging soak ([[Projects/personal-finance-notion/backlog/p2-csp-enforce-production|p2 note]]).
  • MongoDB availability (local/prod) — app expects MONGODB_URI; outages break all reads/writes.
  • OpenRouter API key + free-tier model availability — bulk AI import depends on OPENROUTER_API_KEY and the configured OPENROUTER_MODEL fallback chain; rate limits or model deprecation can break imports.
  • No automated test coverage on AI import flow — tests/ covers E2E core paths via Playwright, but LLM normalization is verified manually; regressions in prompt/model behavior won't be caught by CI.
  • Bus factor of 1 — sole developer; no recoverable knowledge outside vault + repo docs/.

Next Actions

  • [ ] Promote top three docs/todo.md items into backlog/p0-*.md notes — mg
  • [ ] File a stack-snapshot ADR (decisions/adr-2026-05-17-stack-snapshot.md) mirroring lumendev-invoice's pattern — mg
  • [ ] Decide success metric (capture rate, time-to-add, etc.) and record above — mg

Related

  • App repository (local): /Users/mg/Project/personal-finance-notion
  • Entry points: AGENTS.md (env + bootstrap), DESIGN.md (design tokens), docs/README.md (documentation index)
  • Integration docs: docs/integrations/ (AI agent push, BCA email pipeline)
  • Implementation rules: .cursor/skills/ (forms, error handling, E2E, caching, typing)
  • [[Areas/LumenDev/LumenDev]]