💰 CashCue

AI-Powered Personal Finance & Tax Optimization Platform

A comprehensive financial management application built with React, TypeScript, and Firebase, featuring real-time Indian stock market integration and AI-driven tax insights.

🔗 Live Demo: https://cashcue.vercel.app/

Features • Demo • Installation • Usage • Tech Stack

🎯 Overview

CashCue is an intelligent financial management platform that helps users track expenses, manage investment portfolios, and optimize taxes using AI-powered insights. With real-time Indian stock market data integration and smart budget tracking, CashCue makes personal finance management effortless.

✨ Features

📊 Portfolio Management

Real-time Stock Prices: Integration with Indian Stock Market API (NSE/BSE)
Auto-refresh: Prices update automatically every 5 minutes
Manual Refresh: On-demand price updates with loading indicators
Market Status: Live display of market hours (9:15 AM - 3:30 PM IST)
Tax Classification: Automatic STCG/LTCG classification
Performance Metrics: Gain/loss tracking, holding period analysis

💸 Expense Tracking

Smart Categorization: 7+ categories (Food, Transport, Healthcare, Utilities, etc.)
SMS Integration: Auto-parse expense SMS messages
Budget Alerts: Real-time budget status and warnings
Visual Analytics: Monthly spending charts and trends
Date-based Filtering: Track expenses by date range

🤖 AI-Powered Insights

Tax Optimization: AI-driven tax-loss harvesting recommendations
Portfolio Health Score: Comprehensive portfolio analysis
Scenario Comparison: What-if analysis for tax planning
Urgent Actions: Highlighted time-sensitive recommendations
Timeline View: Tax planning calendar and deadlines

💰 Budget Management

Monthly Budgets: Set and track monthly spending limits
Category Budgets: Individual budgets for each expense category
Smart Recommendations: AI-powered budget suggestions
Real-time Updates: Live budget status and remaining amounts
Overspending Alerts: Proactive warnings when nearing limits

🎨 User Experience

Dark Theme: Beautiful, modern dark UI optimized for readability
Responsive Design: Works seamlessly on desktop, tablet, and mobile
Real-time Sync: Firebase integration for instant data updates
Secure Authentication: Firebase Auth with email/password

🖼️ Demo

📹 View Demo Videos & Screenshots

🚀 Installation

Prerequisites

Node.js 18+ and npm
Firebase Account with Firestore database
Groq API Key (for AI features)

1. Clone the Repository

git clone https://github.com/amanbangeraa/CashCue.git
cd CashCue

2. Install Dependencies

npm install

3. Configure Environment Variables

Create a .env file in the root directory:

# Groq AI API Key
VITE_GROQ_API_KEY=your_groq_api_key_here

# Firebase Configuration
VITE_FIREBASE_API_KEY=your_firebase_api_key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.firebasestorage.app
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id
VITE_FIREBASE_MEASUREMENT_ID=your_measurement_id

4. Set Up Firebase

Go to Firebase Console
Create a new project (or use existing)
Enable Authentication → Email/Password
Create Firestore Database in production mode
Copy configuration values to .env

5. Start Development Server

npm run dev

Open http://localhost:5173 in your browser.

📖 Usage

First-Time Setup

Sign Up: Create an account using email and password
Add Stocks: Navigate to Portfolio → Add your stock holdings
Track Expenses: Go to Expenses → Add your first expense
Set Budget: Visit Budget → Configure monthly limits

Seeding Demo Data

To quickly populate your portfolio with demo data for testing:

npm run seed-portfolio <your-email> <your-password>

Example:

npm run seed-portfolio demo@test.com MyPassword123

This adds 9 demo stocks (~₹13.5L portfolio) perfect for AI analysis.

Key Workflows

📈 Portfolio Management

Add stocks with ticker symbols (e.g., INFY.NS, RELIANCE.NS)
Prices auto-refresh every 5 minutes
View gain/loss, tax type (STCG/LTCG)
Get AI-powered tax optimization recommendations

💳 Expense Tracking

Add expenses manually or via SMS simulator
Categorize spending across 7+ categories
View monthly charts and trends
Get budget warnings in real-time

🎯 Tax Analysis

View portfolio on Dashboard
AI analyzes holdings and generates insights
Review tax-loss harvesting opportunities
Implement recommendations before March 31

🛠️ Tech Stack

Frontend

React 19.2 - UI library
TypeScript 5.9 - Type safety
Vite 7.3 - Build tool
Tailwind CSS 3.4 - Styling
Recharts 3.7 - Data visualization
Lucide React - Icons

Backend & Services

Firebase 12.9
- Authentication (Email/Password)
- Firestore (Real-time database)
Indian Stock Market API - Real-time NSE/BSE prices
Groq SDK - AI-powered insights

Utilities

date-fns - Date manipulation
tsx - TypeScript execution

📁 Project Structure

cashCue/
├── src/
│   ├── components/          # React components
│   │   ├── ai/             # AI insight components
│   │   ├── auth/           # Authentication
│   │   ├── budget/         # Budget management
│   │   ├── dashboard/      # Dashboard widgets
│   │   ├── expenses/       # Expense tracking
│   │   ├── income/         # Income sources
│   │   ├── portfolio/      # Stock portfolio
│   │   ├── shared/         # Shared components
│   │   └── ui/             # UI primitives
│   ├── context/            # React Context providers
│   ├── lib/                # Firebase configuration
│   ├── pages/              # Main page components
│   ├── services/           # Business logic
│   │   ├── aiAnalyzer.ts   # AI insights
│   │   ├── indianStockAPI.ts # Stock API
│   │   ├── smsParser.ts     # SMS parsing
│   │   └── autoExpenseTracker.ts
│   ├── types/              # TypeScript types
│   ├── utils/              # Helper functions
│   └── styles/             # Design system
├── public/                 # Static assets
├── seed-portfolio.ts       # Demo data seeder
├── .env                    # Environment variables
├── package.json            # Dependencies
├── tsconfig.json           # TypeScript config
├── vite.config.ts          # Vite config
└── tailwind.config.js      # Tailwind config

🔧 Available Scripts

Command	Description
`npm run dev`	Start development server
`npm run build`	Build for production
`npm run preview`	Preview production build
`npm run lint`	Run ESLint
`npm run seed-portfolio`	Seed demo portfolio data

🌐 API Integration

Indian Stock Market API

Base URL: https://military-jobye-haiqstudios-14f59639.koyeb.app

Features:

Free, no authentication required
NSE (.NS) and BSE (.BO) support
Real-time price data
Search functionality

Example Usage:

// Get stock data
GET /stock/INFY.NS

// Search stocks
GET /search?query=infosys

// Multiple stocks
GET /stocks?symbols=INFY.NS,TCS.NS,RELIANCE.NS

🔐 Security

✅ Environment variables for sensitive data
✅ Firebase Authentication
✅ Firestore security rules (user-scoped data)
✅ No API keys exposed in frontend
⚠️ Note: Never commit .env to version control

🚀 Deployment

Vercel (Recommended)

Push code to GitHub
Import project in Vercel
Add environment variables
Deploy!

Manual Build

npm run build
# Deploy dist/ folder to any static hosting

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Aman Bangera

GitHub: @amanbangeraa
Repository: CashCue

🙏 Acknowledgments

Indian Stock Market API - Free stock data
Firebase - Backend infrastructure
Groq - AI inference
Recharts - Data visualization
Lucide - Beautiful icons

📞 Support

For issues or questions:

🐛 Open an Issue
💬 Discussions: Use GitHub Discussions
📧 Email: Contact via GitHub

Made with ❤️ using React, TypeScript, and Firebase

⭐ Star this repo if you find it helpful!

Name		Name	Last commit message	Last commit date
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
eslint.config.js		eslint.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
push-schema.sh		push-schema.sh
seed-portfolio.ts		seed-portfolio.ts
tailwind.config.js		tailwind.config.js
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vercel.json		vercel.json
vite.config.ts		vite.config.ts

Latest commit

History

Folders and files

Repository files navigation