TrueBalance - Finance Tracker + AI Chatbot Intake

Production-ready full-stack Next.js app (App Router, JavaScript) with:

• Auth0 authentication
• MongoDB persistence
• Gemini intake extraction + Gemini financial analysis
• Optional Backboard-powered chatbot memory
• Dashboard health scoring + schedule-aware projection graph pipeline

Stack

• Next.js (App Router)
• JavaScript only
• Tailwind CSS
• Auth0 (@auth0/nextjs-auth0)
• MongoDB (mongodb)
• Gemini (@google/generative-ai)
• Backboard (backboard-sdk) for optional persistent chat context memory
• QuickChart Graph API (external chart rendering)

Core Flows

• / is public marketing.
• After login:
  • Existing finance document -> /dashboard
  • No finance document -> /onboarding
• Onboarding is first-time collection only.
• /update supports manual CRUD + Gemini intake with Review & Confirm.
• Finance writes trigger Gemini re-analysis automatically.
• Dashboard includes a finance advice chatbot grounded in a fresh MongoDB read per request, with optional Backboard memory.

Gemini Responsibilities

A) Intake Extraction

• Endpoint: POST /api/gemini/intake
• Parses free text into structured expenses, debts, and income.
• Parses user payoff intent into paymentScheduleMonths per debt.
• Parses debt payment cadence into paymentFrequency per debt (weekly, biweekly, monthly, quarterly, annually, custom).
• Requires customPaymentFrequencyDescription when cadence is custom.
• Supports multiple debts in one message.
• Returns warnings for ambiguous fields.
• Never auto-saves data.

B) Analysis

• Endpoint: POST /api/gemini/analyze
• Analyzes full current finance dataset (all debts included).
• Returns:
  • Insights
  • Risk flags
  • Projection parameters
  • Dynamic financial-health factor weights
  • Score explanation + suggestions

Prediction Graph Pipeline

1. User selects strategy (Aggressive, Balanced, Conservative, Custom)
2. Backend runs Gemini analysis against latest MongoDB finance data
3. Gemini returns dynamic strategy profiles + default recommendation (data-driven)
4. Backend derives deterministic projection dataset from recommended parameters while applying each debt's paymentScheduleMonths and paymentFrequency
5. Backend calls QuickChart API (https://quickchart.io/chart/create)
6. Frontend renders returned graph image URL + interactive chart

UI requirement implemented:

• No graph shown before analysis+graph API complete.
• While waiting, typewriter text shows exactly:
  • Generating your graph, just a moment

Routes

Pages:

• /
• /onboarding
• /dashboard
• /prediction
• /update

API:

• GET /api/finance
• POST /api/finance
• PUT /api/finance
• DELETE /api/finance/debt?id=...
• POST /api/chat
• POST /api/gemini/intake
• POST /api/gemini/analyze
• POST /api/prediction/graph

Auth0 SDK routes (mounted by middleware):

• /auth/login
• /auth/logout
• /auth/callback
• /auth/profile
• /auth/access-token

Data Model

users

• auth0Sub (unique)
• email
• createdAt
• updatedAt

finances

• auth0Sub (unique)
• expenses
  • rentMortgage
  • gas
  • otherExpenses[] (id, name, amount)
• debts[]
  • id, type, lenderName, balance, interestRate, minPayment, paymentScheduleMonths (required), paymentFrequency (required), customPaymentFrequencyDescription (required when paymentFrequency=custom), paymentDueDate, notes, createdAt, updatedAt
• income
  • monthlyIncome
• metadata
  • onboardingCompleted
  • createdAt
  • updatedAt

finance_analysis

• auth0Sub (unique)
• insights
• riskFlags[]
• recommendedParameters
• strategyProfiles (dynamic, per user)
• defaultStrategy
• healthScore (score, factor weights, contributors, explanation, suggestions)
• financeUpdatedAt
• updatedAt

Setup

1. Install

npm install

2. Environment

cp .env.example .env.local

Fill:

• MONGODB_URI
• MONGODB_DB
• APP_BASE_URL
• AUTH0_DOMAIN
• AUTH0_CLIENT_ID
• AUTH0_CLIENT_SECRET
• AUTH0_SECRET
• GEMINI_API_KEY
• BACKBOARD_API_KEY (optional; enables persistent chatbot context memory)
• BACKBOARD_LLM_PROVIDER and BACKBOARD_MODEL_NAME (optional overrides; must be supported by your Backboard account)
• QUICKCHART_API_KEY (optional; only if required by your QuickChart plan)

3. MongoDB

• Local URI: mongodb://localhost:27017
• Database: finance_app

4. Auth0 configuration

Use a Regular Web Application with local origin http://localhost:3000.

Required Auth0 settings:

• Allowed Callback URLs: http://localhost:3000/auth/callback
• Allowed Logout URLs: http://localhost:3000/
• Allowed Web Origins: http://localhost:3000
• Token Endpoint Auth Method: client_secret_post

Given tenant/client setup:

• AUTH0_DOMAIN=dev-jqz7dk5ci1n1f4ei.us.auth0.com
• AUTH0_CLIENT_ID=cUsZplyKLJmlvrOYoBviY9Lw4vgJxeMz

Generate secret:

openssl rand -hex 32

5. Run

npm run dev

Open http://localhost:3000.

Demo User Flow

1. Sign up/login from /.
2. First-time user goes to /onboarding.
3. Use Gemini intake, review extracted data, confirm save.
4. Redirect to /dashboard with stats + health score + Gemini explanation.
5. Go to /update and test:
   • Manual edits
   • Gemini intake with multiple debts in one message
   • Include planned payoff durations (e.g. 18 months, 2 years)
   • Include payment cadence details (e.g. monthly, biweekly, custom)
   • Review & Confirm -> Save
6. Return to /dashboard and confirm updated insights/score.
7. Go to /prediction, pick strategy, generate graph and insights.

Reliability Notes

• Gemini calls use defensive JSON parsing + retries.
• Gemini analyze/intake log sanitized input metadata.
• Finance and analysis routes are auth-protected and scoped by auth0Sub.
• Analysis refresh runs on create/update/delete and stale dashboard reads.
• If BACKBOARD_API_KEY is set, chatbot context is persisted in Backboard per user (auth0Sub -> assistant/thread mapping in MongoDB).
• If Backboard is unavailable or not configured, chatbot generation falls back to direct Gemini responses.