FinPilot - AI Money Mentor

FinPilot is a hackathon-ready full-stack MVP for Indian users who want a clean snapshot of their financial health, FIRE readiness, emergency buffer, and tax-saving opportunities.

Folder Structure

finpilot/
  frontend/
    index.html
    package.json
    postcss.config.js
    tailwind.config.js
    vite.config.js
    src/
      App.jsx
      index.css
      main.jsx
      components/
        ChatUI.jsx
        EmergencyBar.jsx
        FireChart.jsx
        HealthGauge.jsx
        Navbar.jsx
        RecommendationFeed.jsx
      pages/
        Dashboard.jsx
        FirePlanner.jsx
        Landing.jsx
        Onboarding.jsx
        Profile.jsx
      services/
        api.js
  backend/
    main.py
    database.py
    requirements.txt
    seed_data.py
    agents/
      __init__.py
      action_agent.py
      fire_agent.py
      health_score_agent.py
      profiling_agent.py
      tax_agent.py
    models/
      __init__.py
      schemas.py
    services/
      __init__.py
      score_calculator.py
      sip_calculator.py
      tax_calculator.py

Features

• Chat-style onboarding flow
• Deterministic money health score with score breakdown
• FIRE target corpus and SIP planning
• Simplified Indian tax regime comparison with 80C suggestions
• OpenAI-backed health, FIRE, tax, and advisor agents with deterministic math underneath
• SQLite persistence with no authentication

Backend Setup

cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload

Backend runs on http://127.0.0.1:8000.

By default, SQLite is stored at %LOCALAPPDATA%\FinPilot\finpilot.db on Windows so the app avoids OneDrive file-lock issues. You can override it with FINPILOT_DB_PATH.

Optional LLM setup

Set OPENAI_API_KEY if you want all backend agents to run in full AI mode.

set OPENAI_API_KEY=your_key_here
set LLM_MODEL=gpt-4o-mini
set FINPILOT_DB_PATH=C:\path\to\finpilot.db

If no API key is present, FinPilot uses deterministic fallback insights and recommendations so the demo still works locally.

Frontend Setup

cd frontend
npm install
npm run dev

Frontend runs on http://127.0.0.1:5173.

If needed, override the backend URL with:

set VITE_API_BASE_URL=http://127.0.0.1:8000

Seed Demo Data

cd backend
python seed_data.py

This inserts a sample user and prints the generated user_id.

Deploy with Render + Vercel

This repo is prepared for a split deployment:

• Backend on Render using render.yaml
• Frontend on Vercel using frontend/vercel.json

Backend on Render

1. Push the repo to GitHub.
2. In Render, create a new Blueprint from the repo.
3. Render will create the finpilot-api service from render.yaml.
4. Set these backend environment variables:
   • OPENAI_API_KEY if you want LLM-generated recommendation text
   • LLM_MODEL=gpt-4o-mini
   • CORS_ORIGINS=https://your-frontend-domain.vercel.app
5. Deploy the backend.

Included backend settings:

• Build command: pip install -r requirements.txt
• Start command: uvicorn main:app --host 0.0.0.0 --port $PORT
• Health check: /health
• SQLite path: /var/data/finpilot.db
• Persistent disk mount: /var/data

Frontend on Vercel

1. Import the same GitHub repo into Vercel.
2. Set the project root directory to frontend.
3. Add this environment variable:
   • VITE_API_BASE_URL=https://your-render-backend.onrender.com
4. Deploy.

The included frontend/vercel.json adds the SPA rewrite required for React Router deep links.

Important note

Render's docs state that persistent disks require a paid compatible service, and services without a disk use an ephemeral filesystem. That means the Render backend should run on at least a starter service if you want SQLite data to persist.

Official docs used

• Render Blueprints: https://render.com/docs/blueprint-spec
• Render FastAPI deploys: https://render.com/docs/deploy-fastapi
• Render persistent disks: https://render.com/docs/disks
• Vercel Vite deploys: https://vercel.com/docs/frameworks/frontend/vite
• Vercel rewrites: https://vercel.com/docs/rewrites

API Routes

POST /onboarding

Request:

{
  "age": 29,
  "salary": 95000,
  "expenses": 42000,
  "savings": 180000,
  "investment": 320000,
  "risk_level": "Medium",
  "goal": "FIRE"
}

Response:

{
  "message": "Financial plan created successfully.",
  "dashboard": {
    "user_id": 1,
    "profile": {
      "age": 29,
      "salary": 95000.0,
      "expenses": 42000.0,
      "savings": 180000.0,
      "investment": 320000.0,
      "risk_level": "Medium",
      "goal": "FIRE",
      "health_score": 84.32,
      "fire_corpus": 12600000.0,
      "required_sip": 8368.54,
      "tax_saving": 30000.0,
      "emergency_required": 252000.0
    }
  }
}

GET /dashboard/{user_id}

Returns the full dashboard payload for the selected user.

POST /recalculate

Request:

{
  "user_id": 1,
  "salary": 110000,
  "expenses": 45000,
  "goal": "House"
}

GET /recommendations/{user_id}

Response:

{
  "user_id": 1,
  "recommendations": [
    {
      "title": "Increase your monthly SIP",
      "description": "Use surplus cash flow to move closer to your target corpus.",
      "priority": "High",
      "created_at": "2026-03-28T11:00:00"
    }
  ]
}

Financial Logic Notes

• Emergency target = monthly expenses x 6
• Money health score uses deterministic weights out of 100
• FIRE target corpus = yearly expenses x 25
• SIP future value formula:

FV = P x ((1 + r)^n - 1) / r

• Indian tax slabs are simplified exactly as provided in the prompt