Personal Financial Management with AI-Powered Insights

EasyFinance is a comprehensive personal finance management application that combines traditional budgeting tools with cutting-edge AI technology to help users make smarter financial decisions.

• 📊 Dashboard Analytics - Visualize your financial health
• 💰 Income & Expense Tracking - Monitor your cash flow
• 📈 Budget Allocation - Smart budget planning with visual charts
• 🤖 AI Financial Advisor - 5 daily AI queries for financial guidance
• 📱 Responsive Design - Works perfectly on all devices
• 🔐 Secure Authentication - Google OAuth & email/password login

• 🚀 Unlimited AI Queries - Get financial advice anytime
• 📊 Advanced Analytics - Detailed financial insights and trends
• 🚫 Ad-Free Experience - Clean, distraction-free interface
• 📈 Enhanced Dashboard - More comprehensive financial statistics
• 🎯 Priority Support - Get help when you need it

• React 18.2.0 - Modern UI framework
• React Router DOM - Client-side routing
• Vite - Fast build tool and dev server
• Recharts - Beautiful data visualization
• Firebase - Authentication and real-time features
• CSS3 - Custom styling with responsive design

• FastAPI 0.115.8 - High-performance Python web framework
• MongoDB - NoSQL database with Motor async driver
• JWT - Secure token-based authentication
• Pydantic - Data validation and serialization
• Hugging Face API - AI-powered financial advice
• Gmail API - Email notifications and password reset

• Docker - Containerization support
• Gunicorn - Production WSGI server
• Uvicorn - ASGI server for development
• Pytest - Comprehensive testing framework

Before you begin, ensure you have the following installed:

• Node.js (v16 or higher)
• Python (v3.8 or higher)
• MongoDB (v4.4 or higher)
• Git

git clone https://github.com/yourusername/EasyFinance.git
cd EasyFinance

# Navigate to backend directory
cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Copy environment file
cp env.example .env

# Configure your environment variables in .env
# See Configuration section below

# Navigate to frontend directory (from project root)
cd frontend

# Install dependencies
npm install

# Copy environment configuration
cp env-config.md .env.local

# Configure your environment variables
# See Configuration section below

# Start MongoDB service
# On Windows (if installed as service):
net start MongoDB

# On macOS (using Homebrew):
brew services start mongodb-community

# On Linux:
sudo systemctl start mongod

cd backend
uvicorn main:app --reload --host 0.0.0.0 --port 8000

cd frontend
npm run dev

The application will be available at:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs

# Database Configuration
MONGODB_URL=mongodb://localhost:27017/easyfinance

# JWT Configuration
SECRET_KEY=your-super-secret-jwt-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Email Configuration
GMAIL_APP_PASSWORD=your-gmail-app-password
FRONTEND_URL=http://localhost:5173

# AI Configuration
HUGGINGFACE_API_KEY=your-huggingface-api-key

# API Configuration
API_BASE_URL=http://localhost:8000

# API Configuration
VITE_API_BASE_URL=http://localhost:8000/api

# Firebase Configuration (if using Firebase features)
VITE_FIREBASE_API_KEY=your-firebase-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id

cd backend
pytest tests/ -v

cd frontend
npm test

# From project root
cd backend
python tests/run_all_tests.py

EasyFinance/
├── 📁 backend/                 # FastAPI backend
│   ├── 📁 config/             # Configuration files
│   ├── 📁 db/                 # Database models and repositories
│   │   ├── 📁 models/         # Pydantic models
│   │   └── 📁 repositories/   # Data access layer
│   ├── 📁 helpers/            # Utility functions
│   ├── 📁 routers/            # API route handlers
│   │   ├── 📁 dto/           # Data transfer objects
│   │   └── 📁 functions/     # Business logic functions
│   ├── 📁 services/           # Business logic services
│   ├── 📁 static/             # Static files
│   ├── 📁 templates/          # HTML templates
│   ├── 📁 tests/              # Test files
│   ├── 📄 main.py             # FastAPI application entry point
│   └── 📄 requirements.txt    # Python dependencies
├── 📁 frontend/               # React frontend
│   ├── 📁 public/             # Static assets
│   ├── 📁 src/                # Source code
│   │   ├── 📁 assets/         # CSS and images
│   │   ├── 📁 components/     # React components
│   │   │   ├── 📁 functions/  # Utility components
│   │   │   ├── 📁 pages/      # Page components
│   │   │   └── 📁 structure/  # Layout components
│   │   ├── 📁 config/         # Configuration files
│   │   ├── 📁 hooks/          # Custom React hooks
│   │   ├── 📁 models/         # Data models
│   │   ├── 📁 routes/         # Routing configuration
│   │   ├── 📁 services/       # API service layer
│   │   └── 📁 utils/          # Utility functions
│   ├── 📄 package.json        # Node.js dependencies
│   └── 📄 vite.config.js      # Vite configuration
└── 📄 README.md               # This file

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• POST /api/auth/forgot-password - Password reset request
• POST /api/auth/reset-password - Password reset confirmation

• GET /api/users/{user_id} - Get user profile
• PUT /api/users/{user_id} - Update user profile
• DELETE /api/users/{user_id} - Delete user account

• GET /api/finances/{user_id} - Get financial records
• POST /api/finances/{user_id} - Add financial record
• PUT /api/finances/{user_id}/{record_id} - Update financial record
• DELETE /api/finances/{user_id}/{record_id} - Delete financial record

• GET /api/budgets/{user_id} - Get budget allocations
• POST /api/budgets/{user_id} - Create budget allocation
• PUT /api/budgets/{user_id}/{budget_id} - Update budget allocation

• POST /api/ai/chat/{user_id} - Chat with AI advisor
• GET /api/ai/usage/{user_id} - Get AI usage statistics

• GET /api/dashboard/{user_id} - Get dashboard analytics
• GET /api/dashboard/{user_id}/stats - Get financial statistics

cd frontend
npm run build

cd backend
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

# Build and run with Docker Compose
docker-compose up --build

• Development: Use local MongoDB and development API keys
• Staging: Use staging database and limited API quotas
• Production: Use production database and full API access

We welcome contributions! Please follow these steps:

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

• Follow PEP 8 for Python code
• Use ESLint for JavaScript/React code
• Write tests for new features
• Update documentation as needed
• Follow conventional commit messages

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

• 📧 Email: REMOVED

• MongoDB Connection: Ensure MongoDB is running and accessible
• JWT Errors: Check SECRET_KEY configuration
• Email Issues: Verify Gmail App Password setup

• Build Errors: Clear node_modules and reinstall dependencies
• API Connection: Verify VITE_API_BASE_URL configuration
• Authentication: Check Firebase configuration

• Hugging Face - For providing AI models and API access
• MongoDB - For the robust database solution
• FastAPI - For the excellent Python web framework
• React Team - For the amazing frontend framework
• Open Source Community - For all the amazing libraries and tools