FinFlow-Personal-Finance

███████╗██╗███╗   ██╗███████╗██╗      ██████╗ ██╗    ██╗
██╔════╝██║████╗  ██║██╔════╝██║     ██╔═══██╗██║    ██║
█████╗  ██║██╔██╗ ██║█████╗  ██║     ██║   ██║██║ █╗ ██║
██╔══╝  ██║██║╚██╗██║██╔══╝  ██║     ██║   ██║██║███╗██║
██║     ██║██║ ╚████║██║     ███████╗╚██████╔╝╚███╔███╔╝
╚═╝     ╚═╝╚═╝  ╚═══╝╚═╝     ╚══════╝ ╚═════╝  ╚══╝╚══╝

🚧 Currently Working On This

This project is under active development. Below is the live status of every module.

✨ Features

📋 Expense Tracker

• Add daily expenses with date, category, amount, and description
• Classify every entry as a Need or a Want
• Delete entries with instant UI update
• Visual bar chart breaking down spend by category
• Filter transaction list by type (All / Need / Want)
• Real-time totals for Needs, Wants, and entry count

📊 Dashboard

• Full portfolio wealth snapshot pulled from a single /api/summary call
• Monthly expense area chart built from MongoDB aggregation
• Asset allocation donut chart (Liquid / Stocks / MF / FDs)
• Needs vs Wants progress bars with percentage breakdown
• 50-30-20 Rule health indicator (Needs / Wants / Savings ratios)
• All metrics are live — no hardcoded sample data

📈 Stock Portfolio

• Add holdings with ticker, quantity, average buy price, and sector
• Inline CMP (Current Market Price) editor — click any price to update it
• Automated P&L calculation per stock: (CMP − Avg Price) × Qty
• P&L percentage per holding
• Total invested vs current value vs overall return
• Color-coded green/red for profit/loss

🔵 Mutual Funds

• Track funds by name, type (Equity / Debt / Hybrid / Index / ELSS), and units
• Stores NAV at buy date vs current NAV
• Auto-calculates current value as Units × Current NAV
• Return % displayed per fund
• Aggregated P&L across all funds

🏛️ Fixed Deposits

• Add FDs with bank, principal, interest rate, tenure, and start date
• Compound interest maturity calculator: P × (1 + r)^n
• Visual progress bar showing how far into the tenure you are
• Maturity date auto-calculated from start date + tenure
• Interest earned breakdown per FD

💵 Liquid Cash

• Single balance field synced to MongoDB
• Update with one click — persists across sessions
• Included in total wealth calculation and asset allocation chart

🚀 Wealth Projection (SIP Calculator)

• Three interactive sliders: Monthly SIP amount, Expected return %, Time horizon
• SIP compound growth formula: M × [(1 + r)^n − 1] / r
• API-driven — calculations run server-side at /api/summary/projection
• Sliders are debounced (400ms) to avoid hammering the API
• Area chart showing corpus growth vs amount invested over time
• Milestone cards at 5, 10, 15, 20 year marks
• Wealth multiplier shown (e.g. 6.7×)

🗂️ Project Structure

finance-ecosystem/
│
├── backend/
│   ├── models/
│   │   └── index.js              # All 5 Mongoose schemas with virtual fields
│   ├── routes/
│   │   ├── expenses.js           # CRUD + /analytics aggregation
│   │   ├── stocks.js             # Holdings + /pl + /cmp PATCH
│   │   ├── portfolio.js          # mfRouter + fdRouter + liquidRouter
│   │   └── summary.js            # Full snapshot + /projection
│   ├── server.js                 # Express entry, MongoDB connect, route mount
│   ├── package.json
│   └── .env                      # MONGO_URI, PORT, CLIENT_URL
│
└── frontend/
    ├── src/
    │   ├── api.js                # All axios calls — single source of truth
    │   ├── shared.jsx            # C palette, fmt(), MetricCard, Spinner, ErrorBox
    │   ├── App.jsx               # Shell — sidebar, topbar, page routing
    │   ├── main.jsx              # React root
    │   └── pages/
    │       ├── Dashboard.jsx     # /api/summary + /api/expenses/analytics
    │       ├── ExpenseTracker.jsx# Full CRUD on /api/expenses
    │       ├── Portfolio.jsx     # Stocks / MF / FD / Liquid tabs
    │       └── WealthProjection.jsx # /api/summary/projection + sliders
    ├── index.html
    ├── vite.config.js            # Proxy /api → localhost:5000
    └── package.json

🔌 API Reference

Expenses — /api/expenses

Stocks — /api/stocks

Mutual Funds — /api/mutualfunds

Fixed Deposits — /api/fds

Liquid Cash — /api/liquid

Summary — /api/summary

🧮 Core Calculations

Fixed Deposit Maturity

Maturity = Principal × (1 + Rate/100) ^ (Tenure / 12)
Interest = Maturity − Principal

SIP Corpus (Compound Monthly Growth)

Corpus = Monthly × [(1 + r)^n − 1] / r
  where  r = Annual Rate / 100 / 12
         n = Years × 12

Stock P&L

Current Value = Qty × CMP
P&L Amount   = (CMP − Avg Price) × Qty
P&L %        = (P&L Amount / Invested Value) × 100

50-30-20 Budget Rule

Needs   → target ≤ 50% of monthly income
Wants   → target ≤ 30% of monthly income
Savings → target ≥ 20% of monthly income

🗄️ Data Models

Expense

{
  "userId":   "demo_user",
  "date":     "2025-03-01",
  "category": "Rent",
  "label":    "House Rent",
  "amount":   15000,
  "type":     "need",
  "notes":    ""
}

Stock

{
  "userId":   "demo_user",
  "ticker":   "RELIANCE",
  "qty":      10,
  "avgPrice": 2450,
  "cmp":      2780,
  "sector":   "Energy",
  "exchange": "NSE"
}

Mutual Fund

{
  "userId":     "demo_user",
  "name":       "Axis Bluechip",
  "type":       "Equity",
  "invested":   50000,
  "units":      1234.56,
  "navAtBuy":   40.50,
  "currentNav": 51.40,
  "sipAmount":  5000
}

Fixed Deposit

{
  "userId":    "demo_user",
  "bank":      "SBI",
  "principal": 100000,
  "rate":      7.5,
  "tenure":    12,
  "startDate": "2024-06-01"
}

Liquid

{
  "userId":      "demo_user",
  "balance":     125000,
  "lastUpdated": "2026-03-24T10:00:00.000Z"
}

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm 9+
• MongoDB Atlas account (free tier works)

1 — Install dependencies

# Backend
cd backend && npm install

# Frontend
cd ../frontend && npm install

2 — Configure environment

Create backend/.env:

MONGO_URI=mongodb+srv://<user>:<password>@cluster.mongodb.net/finflow
PORT=5000
CLIENT_URL=http://localhost:5173
NODE_ENV=development

In MongoDB Atlas → Network Access → add 0.0.0.0/0 for development.

3 — Run both servers

# Terminal 1
cd backend && npm run dev      # ✅ FinFlow API running on port 5000

# Terminal 2
cd frontend && npm run dev     # → http://localhost:5173

4 — Verify

🛠️ Tech Stack

📦 Environment Variables

🤝 Contributing

1. Fork the repo
2. Create a feature branch: git checkout -b feat/your-feature
3. Commit your changes: git commit -m "feat: add your feature"
4. Push: git push origin feat/your-feature
5. Open a Pull Request

📄 License

MIT © 2026 FinFlow — Personal Finance Ecosystem