MoneyPal - Personal Cash Flow Tracker

🚀 QUICK START REMINDER: After running python app.py, open http://127.0.0.1:5000/ in your browser

A Flask-based personal finance PWA focused on cash flow forecasting rather than traditional budgeting. The key insight: most apps track past spending but don't solve the real problem of "will I have enough money left at the end of the month?"

💡 Project Vision

MoneyPal addresses a key gap in personal finance apps: most track past spending but don't solve the real problem of "will I have enough money left at the end of the month?"

Our Approach

• AI-Powered Cash Flow Forecasting: Prophet-based predictions using historical spending patterns
• Forward-Looking: Focus on future financial health vs. past analysis
• Database Switching: Seamless switching between LIVE and SAMPLE data modes
• Privacy-Focused: Manual data entry gives users full control over their financial data
• Minimal & Focused: Essential features without bloat

Target Users

• People frustrated with traditional budgeting apps
• Those seeking forward-looking financial insights
• Users who value privacy and data control
• Individuals wanting reliable cash flow predictions

Competitive Advantages

• AI cash flow forecasting with Prophet time series analysis
• Database mode switching for safe testing and live data
• Privacy-focused manual entry approach
• Minimal, focused feature set vs. bloated competitors

🚀 Features

Core Functionality ✅

• Cash Flow Tracking: Record income and expenses for Bank Account and Secured Visa
• Auto-Save Editing: Click any cell to edit inline with automatic saving
• AI-Powered Forecasting: 30-day cash flow predictions using Prophet or simple averaging
• Interactive Charts: Plotly-based visualizations with historical data and projections
• Database Mode Switching: Toggle between LIVE (real data) and SAMPLE (test data) modes
• Sticky Headers: Table headers remain visible while scrolling
• Data Export: Export financial data in CSV format
• Running Balance: Real-time balance calculations across all transactions

Advanced Features ✅

• Prophet AI Integration: Advanced time series forecasting with accuracy metrics
• Dual Account Support: Separate tracking for Bank Account and Secured Visa
• Visual Database Indicators: Clear [LIVE] / [SAMPLE] mode display
• Responsive Design: Cohesive color scheme across all interfaces
• Error Handling: Graceful fallback from AI to simple forecasting

🛠️ Technology Stack

• Backend: Flask 3.0.0, Python 3.8+
• Database: SQLite with SQLAlchemy 1.4.53
• AI/ML: Prophet for time series forecasting, Pandas for data processing
• Frontend: HTML5, CSS3, JavaScript, Plotly.js for charts
• Dependencies: Flask-SQLAlchemy 3.0.5, python-dotenv, pandas, prophet

📁 Project Structure

MoneyPal/
├── app.py                          # Main Flask application with AI forecasting
├── models.py                       # Database models (CashFlow)
├── requirements.txt                # Python dependencies including Prophet
├── db_preference.txt               # Database mode preference (LIVE/SAMPLE)
├── cashflowlive.db                 # Live database (real data)
├── cashflowtest.db                 # Sample database (test data)
├── populate_sample_data.py         # Sample data generator
├── populate_secured_visa_data.py   # Secured Visa sample data
├── templates/                      # HTML templates
│   ├── cashflow.html              # Bank account management
│   ├── secured_visa.html           # Secured Visa management
│   └── charts.html                 # Interactive charts with forecasting
└── README.md                       # Project documentation

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• pip package manager

Installation

1. Clone the repository

   git clone https://github.com/SamStamport/MoneyPal.git
   cd MoneyPal

2. Install dependencies and run

   # Create and activate a virtual environment (recommended)
   python -m venv .venv
   # PowerShell (Windows)
   & .\.venv\Scripts\Activate.ps1
   # macOS / Linux
   # source .venv/bin/activate
   
   pip install -r requirements.txt
   python app.py

3. First-time setup

   • Choose LIVE or SAMPLE database mode when prompted
   • Visit: http://localhost:5000

📊 Usage

Database Mode Selection

• First Run: Terminal prompts for LIVE or SAMPLE mode
• Subsequent Runs: Automatically uses saved preference
• Mode Switching: Use "Switch DB" button in any page header
• Visual Indicators: 🔴 LIVE DATABASE or 🟢 SAMPLE DATABASE always visible

Cash Flow Management

• Dual Accounts: Separate Bank Account and Secured Visa tracking
• Date Format: Enter dates in mm/dd/yyyy format
• Inline Editing: Click any cell (date, amount, description, notes) to edit
• Auto-Save: Changes save automatically when you click away
• Running Balance: Real-time balance calculations
• Sticky Headers: Headers remain visible while scrolling through data

Note: The application accepts both mm/dd/yyyy (user-friendly) and ISO YYYY-MM-DD date formats. When adding or editing via the UI prefer mm/dd/yyyy for consistency with CSV export.

AI-Powered Forecasting

• Charts Page: Interactive Plotly visualizations
• Prophet Integration: Advanced time series analysis for 10+ data points
• Simple Fallback: Average-based predictions for smaller datasets
• Accuracy Metrics: Confidence intervals and accuracy percentages
• 30-Day Projections: Future balance predictions for both accounts

🔧 Configuration

Database Modes

• LIVE Mode: Uses cashflowlive.db for real financial data
• SAMPLE Mode: Uses cashflowtest.db for testing and demonstrations
• Preference Storage: Mode saved in db_preference.txt
• Safe Switching: Clear visual indicators prevent accidental data mixing

Environment Variables (Optional)

Create a .env file in the project root:

FLASK_ENV=development
SECRET_KEY=your-secret-key-here

📈 Current Status

Phase 1: Core Features ✅

• Basic Flask application structure
• Database models and setup
• CSV export functionality
• Sample data generation

Phase 2: Financial Features ✅

• Complete cash flow CRUD operations
• Inline editing with auto-save functionality
• Visual feedback and error handling
• Data validation and currency formatting
• Dual account support (Bank + Secured Visa)
• Running balance calculations

Phase 3: AI-Powered Features ✅

• AI Cash Flow Prediction: Prophet-based forecasting with accuracy metrics
• Interactive Charts: Plotly visualizations with historical and projected data
• Database Mode Switching: Safe LIVE/SAMPLE data separation
• Advanced UI: Sticky headers, cohesive color scheme
• Error Handling: Graceful AI fallback to simple methods

Phase 4: Advanced Features 📋

• Voice input for expense logging
• Receipt photo capture with AI parsing
• Smart alerts for low balance predictions
• Goal tracking and budget management
• User authentication system
• Mobile PWA optimization

🤝 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

• Issues: Report bugs and feature requests on GitHub
• Documentation: Check the ROADMAP.md and CHANGELOG.md for detailed information
• Questions: Open a discussion on GitHub

🔄 Changelog

See CHANGELOG.md for a detailed history of changes and updates.

Charts UI (2026-01-15)

• Replaced vertical dotted markers with a custom horizontal double-thumb slider and mini controls (<<, <, >, >>) for selecting the visible date range on the Charts page.
• Added a Lock button to preserve the selected window across data updates and page reloads.
• Thumbs are keyboard-accessible: Arrow keys (1 day), PageUp/PageDown (10 days), Home/End, and Enter to apply.
• Live tooltips and labels show dates while dragging (format: mm/dd/yyyy).
• The selection persists to localStorage and is restored on page load; Plotly's built-in rangeslider is hidden and the custom slider synchronizes with date inputs and chart zoom/pan.

---

MoneyPal - Take control of your finances with AI-powered forecasting.