index

activetype/context-index

Personal Finance Notion — project context

What it is

Solo-built personal finance tracker for mg (LumenDev internal product line). Centralizes transactions across multiple bank accounts, enforces per-category budgets, visualizes cash flow on a dashboard, and ingests transactions via an AI-assisted bulk-import pipeline. Ships as an offline-capable PWA so transactions can be added on-the-go and synced when reconnected. Despite the "Notion" in the project name, there is no active Notion integration — @notionhq/client is in dependencies but unused; the integration that matters is OpenRouter + a scheduled external agent that scrapes BCA bank emails and pushes transactions through a bearer-authenticated REST API.

Technical anchor (verified from app repo)

Framework: Next.js 15 App Router with Turbopack, React 18, TypeScript. Code under src/. Single service: npm run dev on port 3000.
Data: MongoDB + Mongoose. Models under src/lib/models/ (alias @model/*) — userModel, bankModel, transactionModel, transactionCategoryModel, transactionTemplateModel, wishlistModel, rateLimitModel, refreshTokenSessionModel, tokenBlacklistModel.
Mutations / queries: primarily Server Actions under src/lib/actions/ (alias @actions/*). REST is reserved for the external integrations surface.
API surface: REST under src/app/api/integrations/v1/ — bearer-token authenticated; used by external AI agents to push parsed transactions (bulk + preview).
Auth: JWT via jose, password hashing via bcryptjs, HTTP-only cookies; route protection via Edge middleware (src/middleware.ts). Token blacklist model handles signout/revocation.
Validation: React Hook Form + Zod; schemas under src/lib/validations/.
UI: Tailwind CSS + shadcn/ui (Radix primitives in src/components/ui/), Lucide + Heroicons. Charts via ApexCharts and Recharts.
PWA / offline: next-pwa service worker. Offline outbox uses IndexedDB under src/lib/offline/ — writes queue locally and reconcile via sync worker on reconnect. E2E specs in tests/e2e/offline-*.spec.ts.
AI imports: OpenRouter via src/lib/imports/ — chunked LLM normalization, LLM response cache, image downscale for receipt uploads.
Testing: Playwright E2E (POM pattern under tests/pom/) + Vitest unit tests. Commands: npm run test:e2e, npm run test:unit.
Env: MONGODB_URI, JWT_SECRET_KEY (32+ chars), NODE_ENV, OPENROUTER_API_KEY, OPENROUTER_MODEL. Template in .env.example.

Integrations

OpenRouter — LLM provider for bulk-import normalization (categorization, field cleaning, currency parsing). Default routes through a free model with a documented fallback chain (see commit 815bdc7).
BCA email AI agent (external) — scheduled to run daily at 21:00 against the user's BCA notification emails, parses transactions, proposes categories, and POSTs to /api/integrations/v1/transactions/bulk with bearer auth. Spec: docs/integrations/ai-agent-push-transactions.md.
Notion — legacy name only; @notionhq/client is in package.json deps but not wired into the current codebase.

Audits

[[Projects/personal-finance-notion/context/audit-2026-05-17-auth|2026-05-17 — Auth audit (pre-launch)]] — 4 CRITICAL + 4 HIGH findings blocking public multi-user launch.

Hub

[[Projects/personal-finance-notion/personal-finance-notion|MOC]]