FundSight RP

FundSight RP is a Next.js 16 financial command-center app with authenticated user accounts, PostgreSQL persistence, protected routes, and Docker/CI deployment.

The app now reads report/chart data from persisted user records (not hardcoded mock arrays) and is structured for production deployment.

Tech Stack

• Next.js 16 (App Router + Proxy middleware)
• React 19
• Better Auth
• PostgreSQL (pg)
• Playwright (E2E smoke tests)

Production Runtime Requirements

Copy .env.example to .env and set all required values.

Mandatory:

• DATABASE_URL
• BETTER_AUTH_SECRET
• BETTER_AUTH_URL
• NEXT_PUBLIC_APP_URL

Recommended:

• APP_URL
• TRUSTED_ORIGINS

Optional:

• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• NEXT_PUBLIC_ENABLE_DEMO_MODE
• NEXT_PUBLIC_DEMO_EMAIL
• NEXT_PUBLIC_DEMO_PASSWORD

Notes:

• In production, BETTER_AUTH_SECRET is required and startup will fail if it is missing.
• TRUSTED_ORIGINS should include every deployed frontend origin that can initiate auth flows.

Local Development

npm ci
npm run db:migrate
npm run dev

Verification Commands

npm run lint
npm run typecheck
npm run build
npm run test:e2e

Implemented Production Upgrades

• Removed report/chart mock arrays and now derive report datasets from persisted transactions/budget/net-worth records.
• Enforced BETTER_AUTH_SECRET in production runtime (no unsafe fallback secret in production).
• Added partial JSON updates for user financial stores to prevent full-row overwrite races.
• Added explicit 404 behavior for mutation routes when target records do not exist.
• Added request schema validation (zod) and rate limiting for mutating APIs.
• Added request-ID propagation (x-request-id) and structured API logging helpers.
• Added undo support for destructive actions (transactions, accounts, subscriptions, savings goals, loans).
• Added full CRUD for savings goals, loans, accounts, transactions, and subscriptions.
• Added service-worker based PWA offline shell support and offline fallback page.
• Added mobile + PWA E2E checks in Playwright.

API Surface (Current)

• GET|PATCH /api/budget
  • template apply (50/30/20, zero_based, envelope)
  • budget settings and rollover controls
  • variance alerts and weekly cashflow
• GET|POST|PATCH|DELETE /api/loans
  • debt strategy plans (snowball/avalanche)
  • refinance comparison
  • loan due alerts
  • DTI trend points
• GET|POST|PATCH|DELETE /api/savings/goals
  • create, update, delete, and summarize savings goals
• GET|POST|PATCH|DELETE /api/user/accounts
  • account create/edit/delete flows
• GET|POST|PATCH|DELETE /api/tools/subscriptions
  • subscription/bill management with edit toggles and field updates
• GET|POST|PATCH|DELETE /api/transactions
  • filtered listing + CSV export (format=csv)
  • bulk reconcile/categorize/delete
  • saved views
  • transaction auto-categorization rules
  • CSV import (action: import_csv)
  • category mapping import (action: import_category_mappings)
• POST /api/undo
  • restores latest supported destructive action
• GET|POST|DELETE /api/net-worth/snapshots
  • snapshot timeline with notes/reasons and DTI context
• GET /api/insights/management
  • consolidated management insights (budget variance, cashflow, debt strategy, quality checks)
• GET /api/ops/metrics
  • authenticated runtime + database latency metrics for monitoring pipelines

Roadmap Status

• Completed:
  • P0 production hardening and correctness fixes
  • Budget templates + rollover + variance + weekly planned-vs-actual cashflow
  • Debt strategy + refinance simulator + due alerts + DTI trend APIs
  • Transaction filters/saved views/rules/reconciliation + CSV export APIs
  • Full CRUD on savings goals, loans, subscriptions, and accounts
  • Undo APIs and command palette quick action (including goal/loan deletes)
  • Net-worth snapshots API and management-insights API
  • PWA install metadata + service worker offline fallback
  • Encrypted backup/restore scripts and runbook
• Remaining:
  • Wire /api/ops/metrics into external dashboard/alerting tooling
  • Schedule backup scripts in your deployment environment (cron/runner)

Production Deployment Checklist

1. Set all required environment variables, especially BETTER_AUTH_SECRET.
2. Run migrations with npm run db:migrate.
3. Build and start with npm run build && npm run start (or Docker).
4. Verify health endpoint: GET /api/health.
5. Verify auth flow: sign-up, sign-in, protected route redirect.
6. Verify persisted user data flows for budget, savings, loans, subscriptions, reports.

Central DB Provisioning (kt-central-db)

Use the helper script to create app role/database in the shared central Postgres:

POSTGRES_SUPERPASS='<central-postgres-password>' \
APP_DB_PASSWORD='<new-app-password>' \
APP_DB_NAME='fundsight_rp' \
APP_DB_USER='fsrp_user' \
bash scripts/provision-central-db.sh

Then set:

DATABASE_URL=postgresql://fsrp_user:<password>@kt-central-db:5432/fundsight_rp

Docker Deployment

docker compose up -d --build
docker compose ps

The app binds to 127.0.0.1:3110 and exposes health on /api/health.

CI/CD

• .github/workflows/ci.yml
  • lint, typecheck, build, e2e
• .github/workflows/docker-build.yml
  • builds and pushes GHCR image on main/master/tag pushes

Additional Docs

• docs/FEATURE-CATALOG.md
• docs/PRODUCTION-ROADMAP.md
• docs/BACKUP-RESTORE.md