FinAssure — Financial Companion Platform

A comprehensive personal finance management platform for the modern Indian investor.

🌐 Live Demo: [Deploy your own using the guide below]

📖 Table of Contents

Project Overview
Use Case
Features
Tech Stack
Project Structure
Getting Started
Database Setup
Deployment
API Integrations
AI Features

🎯 Project Overview

FinAssure is a full-stack, AI-powered personal finance management web application built for the Indian market. It consolidates every aspect of an individual's financial life — income, expenses, investments, loans, portfolio tracking, and financial news — into a single, premium dashboard experience.

The platform features a stunning dark-mode-first UI with glassmorphism aesthetics, real-time data via financial APIs, AI-powered tools (chatbot, receipt scanner, savings advisor), and automated email reminders for bill payments. It is designed to be production-ready and deployed on Vercel with Supabase as the backend database.

This project was developed as a Community Engagement Project (CEP) during a software internship, demonstrating a full-stack SaaS implementation using modern web technologies.

💡 Use Case

FinAssure is built for individual users and students who want to:

Replace multiple apps (expense trackers, investment dashboards, news feeds) with one unified platform
Track Indian market investments in real-time — stocks, mutual funds, fixed deposits — with live NAV and price data
Never miss a bill payment with smart, priority-based email reminders
Get AI-driven financial advice without paying for a financial advisor
Understand their financial health through a scientifically calculated scoring system
Manage loans with EMI calculators and bank comparisons
Stay informed with curated financial news aggregated from multiple sources

✨ Features

🏠 Dashboard

Financial Health Score — A 0–100 score calculated from income, expenses, savings rate, debt-to-income ratio, and investment coverage
Real-time net worth, monthly income/expense summary, and savings rate
Interactive charts: Expense breakdown (Pie), Income vs. Expense trend (Line), Portfolio Performance (Bar)
Recent activity feed with timestamped transactions

💼 Portfolio Tracker

Add and track Stocks, Mutual Funds, and Fixed Deposits in one place
Live price fetching via TwelveData and Financial Modeling Prep (FMP) APIs
P&L calculation with color-coded gain/loss indicators
Filter and sort by asset type, value, or date

📈 Investments

Live Mutual Fund Tracker — Real-time NAV data via MFAPI.in with search by scheme code
Fixed Deposit Comparator — AI-powered current FD rates from top 10 Indian banks
SIP Calculator — Calculate future wealth with step-up SIP, sliders, and animations
Add mutual funds directly from tracker to portfolio

🏦 Loan Management

Loan Comparison Engine — Browse and compare Home, Car, Personal, Education, Business, and Gold loans across banks
EMI Calculator — Slider-based EMI calculator with total payment breakdown
Smart loan recommendations with "Best Rate" badges

💰 Income Manager

Log income from multiple sources (Salary, Freelance, Business, etc.)
Monthly period filtering with totals
Full transaction history with delete capability

💸 Expense Tracker

Log expenses by category (Food, Transport, Shopping, Bills, Health, etc.)
AI Receipt Scanner — Upload a photo of a receipt and auto-extract amount, merchant, and category using OCR + OpenRouter AI
Category breakdown with visual proportions
Search, filter by category, and date range selection
Expense history view for monthly deep-dives

⏰ Smart Reminders

Create payment reminders with title, amount, due date, type, and priority (High / Medium / Low)
Priority-based lead time: High (7 days), Medium (5 days), Low (3 days)
Automated Email Alerts sent via Nodemailer — beautifully designed, cyberpunk-themed HTML emails
Overdue tracking (alerts up to 3 days after due date)
Mark as done with completion tracking

📰 Financial News

Aggregated financial news from multiple sources via News API
Featured top story + news grid layout
Open articles in new tab; source and time-ago badges

🤖 AI Tools Suite

FinAssure AI Financial Advisor — Chatbot powered by OpenRouter (Llama 3.3 70B, Gemini 2.0 Flash, Qwen 2.5 72B with auto-fallback)
Answer Verification Module — Validates financial answers against academic standards; enforces Definition → Law/Logic → Benefits → Conclusion structure
Savings Suggestions Engine — Analyzes spending patterns and generates 5–7 personalized, actionable saving strategies
FD Rate Intelligence — AI-sourced current fixed deposit rates

👥 Consultants Directory

Browse verified financial consultants with ratings, specializations, and contact info
Filter by expertise (investment, tax, insurance, etc.)

⚙️ Settings

Profile settings — Name, avatar upload with cropping, and bio
Security settings — Password change, session management
Bank account settings — Link bank details for context-aware advice
Notification preferences — Control email reminder behavior
Dark mode toggle (system-wide, persisted)

🔐 Authentication

Email/password sign-up and log-in via Supabase Auth
Session persistence with protected routes
Terms of Service page

🛠️ Tech Stack

Layer	Technology
Frontend Framework	React 18 with React Router v7
Styling	TailwindCSS v3 + shadcn/ui (Radix UI primitives)
Database & Auth	Supabase (PostgreSQL + Auth + Storage)
AI / LLM	OpenRouter (Llama 3.3, Gemini 2.0, Qwen 2.5)
Charts	Recharts
Build Tool	CRACO (Create React App Override)
Email / Backend	Node.js + Nodemailer (SMTP)
Deployment	Vercel (Frontend + Serverless Cron)
Analytics	Vercel Analytics + Speed Insights
HTTP Client	Axios
OCR	Tesseract.js (Receipt scanning)
Forms	React Hook Form + Zod validation

External APIs Used

API	Purpose
MFAPI.in	Free mutual fund NAV data (Indian MFs)
TwelveData	Real-time stock price data
Financial Modeling Prep	Stock fundamentals and quotes
NewsAPI	Financial news aggregation
API Ninjas	Commodities & additional data
OpenRouter	Multi-model AI with free tier fallbacks

📁 Project Structure

FinAssure/
│
├── frontend/                          # React frontend application
│   ├── src/
│   │   ├── App.js                     # Root app, routing, auth wrapper
│   │   ├── index.css                  # Global styles + dark mode tokens
│   │   │
│   │   ├── pages/                     # Top-level route pages
│   │   │   ├── Landing.jsx            # Public landing/marketing page
│   │   │   ├── Login.jsx              # Authentication - Sign In
│   │   │   ├── Register.jsx           # Authentication - Sign Up
│   │   │   ├── Dashboard.jsx          # Main dashboard with health score + charts
│   │   │   ├── Portfolio.jsx          # Asset portfolio tracker (stocks/MF/FD)
│   │   │   ├── Investments.jsx        # MF tracker + FD comparator + SIP calculator
│   │   │   ├── MutualFunds.jsx        # Dedicated MF detail view
│   │   │   ├── Loans.jsx              # Loan comparison + EMI calculator
│   │   │   ├── Income.jsx             # Income logging and history
│   │   │   ├── Expenses.jsx           # Expense tracking + receipt scanner
│   │   │   ├── ExpenseHistory.jsx     # Monthly expense deep-dive history
│   │   │   ├── Reminders.jsx          # Bill reminders management
│   │   │   ├── News.jsx               # Financial news feed
│   │   │   ├── AITools.jsx            # AI chatbot + savings advisor
│   │   │   ├── Consultants.jsx        # Financial consultant directory
│   │   │   ├── Settings.jsx           # User profile & app settings
│   │   │   ├── Terms.jsx              # Terms of Service
│   │   │   └── NotFound.jsx           # 404 page
│   │   │
│   │   ├── components/
│   │   │   ├── DashboardLayout.jsx    # Sidebar + topnav shell for all inner pages
│   │   │   ├── BitcoinLoader.jsx      # Animated splash screen on first load
│   │   │   ├── ProfileModal.jsx       # Avatar crop + profile update modal
│   │   │   ├── SidebarProfile.jsx     # User display in sidebar
│   │   │   ├── Logo.jsx               # App logo component
│   │   │   └── ui/                    # shadcn/ui component library (Radix-based)
│   │   │       └── (button, card, dialog, toast, tabs, chart, etc.)
│   │   │
│   │   ├── context/
│   │   │   └── AuthContext.js         # Supabase auth state + session management
│   │   │
│   │   ├── contexts/
│   │   │   └── CacheContext.jsx       # Global in-memory API response caching
│   │   │
│   │   ├── hooks/
│   │   │   ├── useCachedApi.js        # Hook for cached API calls with loading state
│   │   │   ├── useCachedData.js       # Generic cached data fetcher hook
│   │   │   └── use-toast.js           # Toast notification hook
│   │   │
│   │   ├── services/
│   │   │   ├── apiServices.js         # All Supabase DB read/write operations
│   │   │   ├── openRouterAI.js        # OpenRouter AI (chatbot, receipt scanner, savings)
│   │   │   ├── notificationService.js # Browser notification handling
│   │   │   ├── api.js                 # Axios base instance
│   │   │   └── envDebug.js            # Environment variable diagnostic utility
│   │   │
│   │   ├── lib/
│   │   │   ├── supabase.js            # Supabase client initialization
│   │   │   ├── utils.js               # Tailwind class merge utility (cn)
│   │   │   ├── financialHealth.js     # Financial health score algorithm
│   │   │   ├── dataCache.js           # Low-level cache store implementation
│   │   │   └── cropUtils.js           # Image crop helper for avatar upload
│   │   │
│   │   ├── utils/
│   │   │   ├── dynamicLoans.js        # Loan calculation and recommendation logic
│   │   │   └── corsHelper.js          # API CORS workaround helper
│   │   │
│   │   ├── mockData.js                # Static fallback data (consultants, FD rates, etc.)
│   │   ├── service-worker.js          # PWA service worker (Workbox-based caching)
│   │   └── serviceWorkerRegistration.js
│   │
│   ├── public/                        # Static assets (index.html, favicon, manifest)
│   ├── plugins/
│   │   ├── visual-edits/              # CRACO dev-server plugins for live editing
│   │   └── health-check/              # Webpack health endpoint plugin
│   ├── craco.config.js                # Webpack overrides (polyfills, aliases)
│   ├── tailwind.config.js             # Tailwind theme config
│   ├── package.json                   # Frontend dependencies
│   ├── .env.example                   # Template for environment variables
│   └── vercel.json                    # Frontend-specific Vercel config
│
├── backend/                           # Node.js email reminder service
│   ├── emailReminderTask.js           # Core: fetches reminders + sends HTML emails via SMTP
│   ├── package.json                   # Backend dependencies (nodemailer, supabase-js, dotenv)
│   └── .env.example                   # Template for backend env vars
│
├── api/
│   └── send-reminders.js              # Vercel Serverless Function (cron entry point)
│
├── database/
│   ├── schema/
│   │   └── CREATE_HISTORY_TABLE.sql   # Expense history table creation
│   └── migrations/
│       ├── ADD_DESIGNATION.sql        # Adds designation field to profiles
│       └── DATABASE_SCHEMA_UPDATES.sql # General schema evolution patches
│
├── supabase/                          # Supabase SQL operations
│   ├── SUPABASE_ADD_PHOTO.sql         # Setup for profile photo storage
│   ├── SUPABASE_PERFORMANCE_OPTIMIZATION.sql
│   ├── SUPABASE_PORTFOLIO_FIX.sql
│   ├── SUPABASE_REMAINING_FIXES.sql
│   ├── SUPABASE_REMINDERS_FIX.sql
│   ├── SUPABASE_SECURITY_FIX.sql
│   └── SUPABASE_STORAGE_SETUP.sql     # Supabase Storage bucket setup
│
├── sql/fixes/
│   ├── FIX_MISSING_PROFILES.sql       # Patch for missing user profile rows
│   └── FIX_UPDATED_AT.sql             # Auto-update timestamp trigger fix
│
├── package.json                       # Root-level (Vercel build orchestration)
└── vercel.json                        # Vercel deployment config + cron schedule

🚀 Getting Started

Prerequisites

Make sure you have the following installed:

Node.js v18+ (Download)
npm v9+ (comes with Node.js)
A Supabase account and project (supabase.com)
API keys for the external services listed below

Frontend Setup

# 1. Clone the repository
git clone https://github.com/your-username/FinAssure.git
cd FinAssure

# 2. Navigate to the frontend directory
cd frontend

# 3. Install dependencies (use --legacy-peer-deps due to some Radix/React peer dep mismatches)
npm install --legacy-peer-deps

# 4. Copy the environment variable template and fill in your values
cp .env.example .env
# → Edit .env with your keys (see Environment Variables section below)

# 5. Start the development server
npm start

The app will be available at http://localhost:3000

To build for production:

npm run build

Backend Setup

The backend is a standalone Node.js service for sending email reminders. It runs as a Vercel Serverless Function in production, but can be run locally for testing.

# From the project root, navigate to backend
cd backend

# Install dependencies
npm install

# Copy and fill in the environment template
cp .env.example .env
# → Edit .env with your Supabase service role key and SMTP credentials

# Run the email reminder task manually (for testing)
node emailReminderTask.js

Environment Variables

Frontend (`frontend/.env`)

# Supabase (Required)
REACT_APP_SUPABASE_URL=https://your-project.supabase.co
REACT_APP_SUPABASE_ANON_KEY=your_anon_key_here

# AI — OpenRouter (Required for AI Tools)
REACT_APP_OPENROUTER_API_KEY=sk-or-...

# Stock Data — TwelveData (Required for Portfolio live prices)
REACT_APP_TWELVEDATA_API_KEY=your_twelvedata_key
REACT_APP_TWELVEDATA_MARKETS_KEY=your_markets_key

# Financial Data — FMP (Optional, Portfolio fallback)
REACT_APP_FMP_API_KEY=your_fmp_key

# News — NewsAPI (Required for News page)
REACT_APP_NEWS_API_KEY_1=your_news_api_key_1
REACT_APP_NEWS_API_KEY_2=your_news_api_key_2  # Fallback key

# Commodities (Optional)
REACT_APP_API_NINJAS_KEY=your_api_ninjas_key
REACT_APP_COMMODITIES_API_KEY=your_commodities_key

# Build settings
DISABLE_ESLINT_PLUGIN=true
WDS_SOCKET_PORT=443
ENABLE_HEALTH_CHECK=false

Backend (`backend/.env`)

# Supabase — Use SERVICE ROLE KEY (not anon key) for backend access
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# SMTP Email (e.g., Gmail with App Password)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_USER=your_email@gmail.com
SMTP_PASS=your_app_specific_password

Gmail SMTP Setup: Go to your Google Account → Security → App Passwords. Generate a password for "Mail" and use it as SMTP_PASS. Do NOT use your regular Gmail password.

🗄️ Database Setup

FinAssure uses Supabase (hosted PostgreSQL). Run the following SQL files in your Supabase SQL Editor in order:

1. Core Tables (run these first in Supabase)

The main tables required are:

profiles — User profile data (linked to Supabase auth)
expenses — Individual expense records
income — Income entries
investments — Portfolio assets (stocks, MF, FD)
reminders — Bill/payment reminders
expense_history — Monthly expense snapshots

2. Run Schema Files

-- Run in Supabase SQL Editor:

-- Core schema
-- (Create tables manually via Supabase Table Editor, or request schema.sql)

-- After core tables, run migration patches:

# Order to run SQL files:
database/schema/CREATE_HISTORY_TABLE.sql
database/migrations/DATABASE_SCHEMA_UPDATES.sql
database/migrations/ADD_DESIGNATION.sql
supabase/SUPABASE_STORAGE_SETUP.sql
supabase/SUPABASE_SECURITY_FIX.sql
supabase/SUPABASE_ADD_PHOTO.sql
supabase/SUPABASE_REMINDERS_FIX.sql
supabase/SUPABASE_PORTFOLIO_FIX.sql
supabase/SUPABASE_REMAINING_FIXES.sql
supabase/SUPABASE_PERFORMANCE_OPTIMIZATION.sql
sql/fixes/FIX_MISSING_PROFILES.sql
sql/fixes/FIX_UPDATED_AT.sql

3. Supabase Storage

Run supabase/SUPABASE_STORAGE_SETUP.sql to create the storage bucket for user avatar uploads. Then configure your bucket policies in the Supabase dashboard (Storage → Policies) to allow authenticated users to upload and read their own images.

☁️ Deployment

FinAssure is configured for zero-config Vercel deployment.

Deploy to Vercel

# Install Vercel CLI
npm install -g vercel

# From the project root
vercel

# For production deployment
vercel --prod

Vercel will use vercel.json at the root to:

Build the frontend using npm install --prefix frontend --legacy-peer-deps && cd frontend && CI=false npm run build
Output the built files from the build/ directory
Run the cron job at 30 3 * * * (3:30 AM UTC daily) to send email reminders via the /api/send-reminders serverless function

Environment Variables on Vercel

In your Vercel project dashboard → Settings → Environment Variables, add all the keys from both frontend/.env and backend/.env (without the REACT_APP_ prefix where indicated for server-side vars).

🔌 API Integrations

Feature	API	Free Tier
Mutual Fund NAVs	MFAPI.in	✅ Completely free
Stock Prices	TwelveData	✅ 800 req/day
Stock Fundamentals	FMP	✅ Limited free
Financial News	NewsAPI	✅ 100 req/day
AI (Chatbot, Advisor)	OpenRouter	✅ Free models available
Commodities	API Ninjas	✅ Free tier

🤖 AI Features

FinAssure's AI is powered by OpenRouter with automatic model fallbacks:

Priority Order:
1. meta-llama/llama-3.3-70b-instruct:free
2. google/gemini-2.0-flash-exp:free
3. qwen/qwen-2.5-72b-instruct:free
4. google/gemini-2.0-flash-thinking-exp:free
5. meta-llama/llama-3.1-70b-instruct:free

If a model is rate-limited (429) or unavailable (503/404), the system automatically retries with the next model — ensuring maximum uptime with zero cost.

AI Capabilities

Tool	Description
FinAdvisor Chatbot	Conversational financial advisor with academic answer verification
Receipt Scanner	OCR + AI extraction of merchant, amount, category from receipt photos
Savings Advisor	Analyzes your spending patterns and generates personalized savings strategies
FD Rate Oracle	Retrieves current Fixed Deposit rates from top Indian banks via AI knowledge

🏛️ Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    VERCEL EDGE                           │
│  ┌───────────────────┐   ┌─────────────────────────┐   │
│  │  React Frontend   │   │  Serverless Functions   │   │
│  │  (Static Build)   │   │  /api/send-reminders    │   │
│  └────────┬──────────┘   └──────────┬──────────────┘   │
│           │                         │ (Cron: 3:30AM)    │
└───────────┼─────────────────────────┼──────────────────┘
            │                         │
     ┌──────▼─────────────────────────▼──────┐
     │           SUPABASE                    │
     │  ┌────────┐ ┌───────┐ ┌───────────┐  │
     │  │  Auth  │ │  DB   │ │  Storage  │  │
     │  └────────┘ └───────┘ └───────────┘  │
     └───────────────────────────────────────┘
            │
     ┌──────▼──────────────────────────┐
     │        EXTERNAL APIs            │
     │  TwelveData | MFAPI | NewsAPI   │
     │  FMP | OpenRouter AI            │
     └─────────────────────────────────┘

Built with ❤️ for the Indian financial ecosystem.

FinAssure — Know your money. Grow your money.

Name		Name	Last commit message	Last commit date
Latest commit History 73 Commits
.gemini/artifacts		.gemini/artifacts
.vscode		.vscode
api		api
backend		backend
database		database
frontend		frontend
sql/fixes		sql/fixes
supabase		supabase
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation

FinAssure — Financial Companion Platform

📖 Table of Contents

🎯 Project Overview

💡 Use Case

✨ Features

🏠 Dashboard

💼 Portfolio Tracker

📈 Investments

🏦 Loan Management

💰 Income Manager

💸 Expense Tracker

⏰ Smart Reminders

📰 Financial News

🤖 AI Tools Suite

👥 Consultants Directory

⚙️ Settings

🔐 Authentication

🛠️ Tech Stack

External APIs Used

📁 Project Structure

🚀 Getting Started

Prerequisites

Frontend Setup

Backend Setup

Environment Variables

Frontend (frontend/.env)

Backend (backend/.env)

🗄️ Database Setup

1. Core Tables (run these first in Supabase)

2. Run Schema Files

3. Supabase Storage

☁️ Deployment

Deploy to Vercel

Environment Variables on Vercel

🔌 API Integrations

🤖 AI Features

AI Capabilities

🏛️ Architecture Overview

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Frontend (`frontend/.env`)

Backend (`backend/.env`)

Packages