Finance Planner

A comprehensive personal finance management application built with Next.js, designed to help users track, analyze, and optimize their financial health through intelligent budgeting, investment monitoring, and AI-powered insights.

🚀 Features

Core Financial Management

• Dashboard: Comprehensive financial overview with interactive charts and key metrics
• Income Tracking: Record and monitor various income sources with recurring support
• Expense Management: Categorize and track expenses with detailed reporting
• Budget Planning: Create and monitor monthly budgets with visual progress indicators
• Account Management: Track multiple account types (cash, bank accounts, e-wallets)
• Investment Portfolio: Monitor investments, track transactions, and analyze performance
• Financial Goals: Set and track progress towards savings goals
• Debt Management: Track outstanding debts and payment schedules

Advanced Features

• Multi-Currency Support: Handle multiple currencies with real-time exchange rate conversion
• AI-Powered Budget Recommendations: Get personalized budget suggestions based on your financial data, location, and goals
• Historical Analysis: Leverage past financial data for better planning and insights
• Interactive Charts: Visualize spending patterns, income distribution, and investment performance
• Responsive Design: Fully responsive interface that works on desktop and mobile devices
• Dark/Light Theme: Toggle between themes for comfortable viewing

Budget Categories

The app supports comprehensive expense categorization including:

• Food & Drink
• Housing
• Utilities
• Transportation
• Clothing
• Leisure & Travel
• Technology
• Pets
• Health & Wellness
• Education
• Entertainment
• Gifts & Donations
• Personal Care
• Debt Payments
• Savings & Investments
• Miscellaneous

🛠 Tech Stack

Frontend

• Next.js 15 - React framework with App Router
• React 19 - UI library
• TypeScript - Type-safe JavaScript
• Tailwind CSS - Utility-first CSS framework
• shadcn/ui - Modern UI component library built on Radix UI
• Recharts - Data visualization library
• Lucide React - Icon library

Backend & Database

• Supabase - PostgreSQL database with real-time capabilities and authentication
• Supabase Auth - User authentication and authorization
• Edge Functions - Serverless functions for API endpoints

AI & Integrations

• Google Generative AI - AI-powered budget recommendations
• OpenAI - Alternative AI provider for enhanced insights
• Exchange Rate API - Real-time currency conversion

Development Tools

• ESLint - Code linting
• PostCSS - CSS processing
• TypeScript - Type checking

📋 Prerequisites

Before running this application, make sure you have:

• Node.js 18.x or later
• npm, yarn, pnpm, or bun package manager
• A Supabase account and project

🚀 Getting Started

1. Clone the Repository

git clone <repository-url>
cd finance-planner

2. Install Dependencies

npm install
# or
yarn install
# or
pnpm install
# or
bun install

3. Environment Setup

Create a .env.local file in the root directory with your Supabase credentials:

NEXT_PUBLIC_SUPABASE_URL=your-supabase-project-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key

# AI API Keys (optional - for enhanced AI features)
GOOGLE_GENERATIVE_AI_API_KEY=your-google-ai-api-key
OPENAI_API_KEY=your-openai-api-key

4. Database Setup

The application uses Supabase as its database. You'll need to:

1. Create a new Supabase project
2. Run the database migrations (located in supabase/migrations/)
3. Configure authentication settings
4. Set up the required tables and functions

5. Run the Development Server

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 with your browser to see the application.

📁 Project Structure

finance-planner/
├── src/
│   ├── app/                    # Next.js app router pages
│   │   ├── (app)/             # Protected app routes
│   │   │   ├── dashboard/     # Main dashboard
│   │   │   ├── income/        # Income management
│   │   │   ├── spending/      # Expense tracking
│   │   │   ├── budgets/       # Budget planning
│   │   │   ├── accounts/      # Account management
│   │   │   ├── investments/   # Investment portfolio
│   │   │   ├── goals/         # Financial goals
│   │   │   └── settings/      # User settings
│   │   ├── api/               # API routes
│   │   │   └── ai/            # AI-powered endpoints
│   │   ├── auth/              # Authentication pages
│   │   └── globals.css        # Global styles
│   ├── components/            # Reusable UI components
│   │   ├── ui/                # Base UI components (shadcn/ui)
│   │   ├── dashboard/         # Dashboard-specific components
│   │   ├── forms/             # Form components
│   │   ├── layout/            # Layout components
│   │   └── [feature]/         # Feature-specific components
│   ├── lib/                   # Utility libraries
│   │   ├── supabase/          # Supabase client configuration
│   │   ├── ai/                # AI service integrations
│   │   └── utils.ts           # General utilities
│   ├── services/              # Business logic services
│   ├── types/                 # TypeScript type definitions
│   └── config/                # Configuration files
├── supabase/                  # Supabase configuration
│   ├── migrations/           # Database migrations
│   └── functions/            # Edge functions
├── public/                   # Static assets
└── package.json              # Dependencies and scripts

🔧 Available Scripts

• npm run dev - Start the development server
• npm run build - Build the application for production
• npm start - Start the production server
• npm run lint - Run ESLint for code linting

🎯 Key Components

Dashboard

The main dashboard provides:

• Financial health overview
• Income vs spending analysis
• Budget performance tracking
• Investment allocation charts
• Quick actions for common tasks

AI Budget Recommendations

The AI-powered budget recommendation system:

• Analyzes user income, expenses, and location
• Considers household size and financial goals
• Provides personalized budget allocations
• Uses historical data when available
• Supports custom instructions for specific needs

Multi-Currency Support

• Supports multiple currencies with USD as base reporting currency
• Real-time exchange rate fetching
• Automatic currency conversion for all financial data
• User-preferred currency settings

🔐 Authentication

The application uses Supabase Auth for user authentication, providing:

• Secure user registration and login
• Password reset functionality
• Session management
• Protected routes

📊 Data Visualization

Built-in charts and graphs include:

• Spending distribution pie charts
• Income trend line charts
• Budget progress bars
• Investment performance charts
• Financial health indicators

🌐 Deployment

Vercel (Recommended)

1. Connect your GitHub repository to Vercel
2. Add environment variables in Vercel dashboard
3. Deploy automatically on push

Other Platforms

The application can be deployed to any platform supporting Next.js:

• Netlify
• Railway
• Self-hosted with Docker

🤝 Contributing

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

📝 License

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

🙋 Support

If you have any questions or need help:

• Open an issue on GitHub
• Check the documentation
• Review the codebase for implementation details

🔄 Future Enhancements

Planned features include:

• Advanced financial reporting and analytics
• Integration with financial institutions (Plaid, etc.)
• Mobile app companion
• Advanced AI insights and predictions
• Multi-user household accounts
• Export functionality for tax preparation