Expense.AI

A Personal Finance Manager and Budgeting tool that leverages AI to provide intelligent spending insights, automated transaction processing, and smart financial recommendations.

Overview

Expense.AI is an intelligent personal finance management platform that combines powerful expense tracking with AI-driven insights. Built with modern technologies and a focus on user experience, it helps users understand their spending patterns, manage budgets effectively, and make smarter financial decisions.

The platform leverages Google's Gemini AI to analyze financial data and provide personalized recommendations, while maintaining a clean, intuitive interface built with React and powered by Convex's real-time backend infrastructure.

Features

Core Functionality

🔐 Secure Authentication - Anonymous and multi-auth support via Convex Auth
💳 Transaction Management - Upload, track, and manage financial transactions
📊 Bank Statement Processing - Automated CSV/file upload for bulk transaction import
📈 Budget Management - Set and track category-based budgets with real-time spending updates
🎯 Savings Goals - Define and monitor progress toward financial milestones

AI-Powered Features

🤖 Smart Insights - AI-generated spending patterns, budget alerts, and savings recommendations using Google Gemini
🔍 Anomaly Detection - Identify unusual spending patterns and potential financial risks
💡 Personalized Recommendations - Contextual financial advice based on spending behavior

Dashboard & Visualization

📅 Advanced Filtering - Date range and category-based filtering with single source of truth
📊 Spending Charts - Visual representation of expenses by category and time period
🏠 Dashboard - Comprehensive overview of financial health and key metrics
📱 Responsive Design - Mobile-first UI built with Tailwind CSS

Tech Stack

Frontend

Tool	Version	Purpose
React	^19.0.0	UI library
TypeScript	~5.7.2	Type safety
Vite	^6.2.0	Build tool & dev server
Tailwind CSS	~3	Styling
Sonner	^2.0.3	Toast notifications

Backend

Tool	Version	Purpose
Convex	^1.31.2	Backend platform & database
Convex Auth	^0.0.80	Authentication
Google Gemini	^1.34.0	AI insights generation

Development

Tool	Version	Purpose
ESLint	^9.21.0	Code linting
Prettier	^3.5.3	Code formatting
TypeScript ESLint	^8.24.1	TS linting rules

Project Structure

Expense.AI/
├── src/                          # Frontend React application
│   ├── components/               # React components
│   │   ├── AppContent.tsx        # Main app layout
│   │   ├── Dashboard.tsx         # Dashboard view
│   │   ├── TransactionList.tsx   # Transaction display
│   │   ├── BudgetManager.tsx     # Budget management
│   │   ├── SavingsGoals.tsx      # Savings goal tracking
│   │   ├── SpendingChart.tsx     # Data visualization
│   │   ├── InsightsPanel.tsx     # AI insights display
│   │   ├── StatementUpload.tsx   # File upload handler
│   │   ├── DateFilterTabs.tsx    # Date filtering UI
│   │   ├── MonthSlider.tsx       # Month navigation
│   │   └── ...                   # Other UI components
│   ├── contexts/                 # React Context API
│   │   └── DateFilterContext.tsx # Global date filtering state
│   ├── hooks/                    # Custom React hooks
│   │   └── useDateFilter.ts      # Date filter hook
│   ├── lib/                      # Utilities
│   │   ├── dateUtils.ts          # Date manipulation
│   │   └── utils.ts              # General utilities
│   ├── App.tsx                   # Root component
│   ├── main.tsx                  # Entry point
│   └── index.css                 # Global styles
│
├── convex/                       # Backend (Convex functions)
│   ├── schema.ts                 # Database schema definition
│   ├── auth.ts                   # Authentication handlers
│   ├── auth.config.ts            # Auth configuration
│   ├── transactions.ts           # Transaction mutations & queries
│   ├── budgets.ts                # Budget management functions
│   ├── savings.ts                # Savings goal functions
│   ├── statements.ts             # Bank statement processing
│   ├── insights.ts               # AI insight generation
│   ├── gemini.ts                 # Google Gemini integration
│   ├── router.ts                 # HTTP route definitions
│   ├── http.ts                   # HTTP handler
│   ├── utils.ts                  # Backend utilities
│   ├── tsconfig.json             # TS config for backend
│   └── _generated/               # Auto-generated Convex types
│
├── public/                       # Static assets
├── index.html                    # HTML template
├── vite.config.ts                # Vite configuration
├── tsconfig.json                 # Root TS configuration
├── tailwind.config.js            # Tailwind configuration
├── eslint.config.js              # ESLint configuration
├── postcss.config.cjs            # PostCSS configuration
├── package.json                  # Dependencies & scripts
└── README.md                     # This file

Quick Start

Prerequisites

Before you begin, ensure you have the following installed:

Node.js >= 18.0.0 (Download)
npm >= 9.0.0 or yarn >= 3.0.0
Git (for version control)
A Convex account (Sign up free)
A Google API key (for Gemini AI - Get it here)

Verify installations:

node --version  # v18.0.0+
npm --version   # 9.0.0+
git --version   # 2.0.0+

Installation

Clone the repository

git clone https://github.com/Shubhankt1/Expense.AI.git
cd Expense.AI

Install dependencies
```
npm install
```
Set up environment variables

Create a .env.local file in the root directory:
```
cp .env.example .env.local
```
Then configure your environment variables:
```
# Convex backend URL (automatically set by Convex CLI)
VITE_CONVEX_URL=https://your-convex-deployment.convex.cloud

# Google Gemini API
VITE_GOOGLE_API_KEY=your_google_api_key_here
```
Getting your values:
- VITE_CONVEX_URL: Run npx convex dev (see Development section)
- VITE_GOOGLE_API_KEY: Get from Google AI Studio

Development

Start the full development environment (frontend + backend):

npm run dev

This command will:

Start the Convex backend (sync with cloud)
Start the Vite dev server with hot module replacement
Open the app in your browser at http://localhost:5173

Individual commands:

npm run dev:frontend    # Frontend only on :5173
npm run dev:backend     # Backend sync only

Building

Create an optimized production build:

npm run build

This will:

Type-check both frontend and backend
Bundle the frontend with Vite
Output to dist/ directory

Contributing

We welcome contributions! Please see our CONTRIBUTING.md for:

Quick contribution steps:

# 1. Fork the repository
# 2. Create feature branch
git checkout -b feature/amazing-feature

# 3. Make changes and test locally
npm run dev
npm run lint

# 4. Commit following conventional commits
git commit -m "feat: add amazing feature"

# 5. Push and create Pull Request
git push origin feature/amazing-feature

Troubleshooting

Common Issues

1. Convex Connection Failed

Error: Failed to connect to Convex

Solution:

# Ensure backend is running
npm run dev:backend

# Or reinitialize Convex
npx convex dev

2. Missing Environment Variables

Error: VITE_CONVEX_URL is not defined

Solution:

Check .env.local file exists
Ensure VITE_CONVEX_URL and VITE_GOOGLE_API_KEY are set
Restart dev server: npm run dev

3. Port Already in Use

Error: Port 5173 is already in use

Solution:

# Kill process on port 5173
lsof -ti:5173 | xargs kill -9

# Or use different port
npm run dev:frontend -- --port 3000

4. TypeScript Errors

Error: Property does not exist

Solution:

# Regenerate Convex types
npx convex dev

# Clear type cache
rm -rf node_modules/.vite

5. Build Failures

Error during vite build

Solution:

# Run lint check first
npm run lint

# Clear cache and rebuild
rm -rf dist node_modules
npm install
npm run build

Getting Help

References

Documentation

Related Resources

Community

License

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

Author

Shubhank Tyagi

GitHub: @Shubhankt1
Project: Expense.AI

Acknowledgments

Convex for the excellent backend platform
Google AI for Gemini API
The React and TypeScript communities

⬆ Back to top

Made with ❤️ by Shubhank Tyagi

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
.cursor/rules		.cursor/rules
.github/instructions		.github/instructions
convex		convex
src		src
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
components.json		components.json
eslint.config.js		eslint.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.cjs		postcss.config.cjs
setup.mjs		setup.mjs
tailwind.config.js		tailwind.config.js
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Shubhankt1/Expense.AI

Folders and files

Latest commit

History

Repository files navigation

Expense.AI

Table of Contents

Overview

Features

Core Functionality

AI-Powered Features

Dashboard & Visualization

Tech Stack

Frontend

Backend

Development

Project Structure

Quick Start

Prerequisites

Installation

Development

Building

Contributing

Troubleshooting

Common Issues

1. Convex Connection Failed

2. Missing Environment Variables

3. Port Already in Use

4. TypeScript Errors

5. Build Failures

Getting Help

References

Documentation

Related Resources

Community

License

Author

Acknowledgments

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages