MoneyMind - AI-Powered Personal Finance Management

💼 100% Local, Privacy-Focused Financial Management for Freelancers & Consultants

MoneyMind is a fully local AI-powered personal finance management system designed for freelancers, consultants, and personal brands. It runs entirely on-premises using Docker Compose with native AI models (Mistral 7B via Ollama), ensuring complete privacy and zero monthly costs.

✨ Key Features

• 💼 Customer Management - Track clients with full contact and billing information
• 📊 Project Management - Manage projects with phases, milestones, and budget tracking
• ⏱️ Time Tracking - Log hours against projects and tasks (billable/non-billable)
• 💰 Income Tracking - Record all income sources with dynamic categories
• 💸 Expense Tracking - Track expenses with business percentage allocation (0-100%)
• 💵 Cash Balance Tracking - Track actual bank balance with historical snapshots
• 📈 Cashflow Projections - Forecast future cash position (3-6 months)
• 📊 Financial Dashboard - Runway, cash flow, burn rate, comprehensive metrics
• 💬 AI Chat Interface - Natural language queries about your finances
• 🎨 Dynamic Categories - Add, edit, and remove income/expense categories on the fly

🚀 Quick Start

Prerequisites

• Docker Desktop with Docker Compose v2
• 16GB+ RAM (for Mistral 7B)
• Development (macOS): Native Ollama with M4 Metal GPU
• Production (Linux): NVIDIA GPU (optional but recommended)

Hybrid Architecture Overview

This project uses a hybrid Ollama approach for optimal performance:

Environment	Ollama Deployment	GPU Acceleration	AI Response Time
Development (macOS M4)	Native on host	Apple Metal	3-5 seconds
Production (Linux CPU)	Docker container	None	12-20 seconds
Production (Linux GPU)	Docker container	NVIDIA CUDA	2-8 seconds

Development uses docker-compose.override.yml to redirect the API container to native Ollama on the macOS host, providing 3-5x faster AI responses via Metal GPU acceleration.

---

💻 Development Setup (macOS M4)

Automated Setup (Recommended)

Run the automated setup script:

./setup-dev.sh

This script will:

• Install Ollama via Homebrew (if needed)
• Pull the Mistral 7B model
• Start native Ollama server with M4 Metal GPU
• Start Docker containers with API redirected to native Ollama

Manual Setup

1. Install Ollama (if not installed):

brew install ollama

2. Pull Mistral 7B model:

ollama pull mistral:7b

3. Start native Ollama server:

ollama serve &

4. Start Docker containers:

docker compose up -d

The API will automatically use native Ollama via docker-compose.override.yml.

Development Service URLs

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs
• Ollama: http://localhost:11434

Expected AI Response Time: 3-5 seconds (M4 Metal GPU)

Stopping Development Environment

docker compose down
pkill ollama

---

🐧 Production Setup (Linux)

Automated Setup (Recommended)

Run the automated setup script:

./setup-prod.sh

This script will:

• Detect NVIDIA GPU (if available)
• Start Docker containers with containerized Ollama
• Pull Mistral 7B model inside container

Manual Setup

1. Start the application:

docker compose up -d

2. Pull Mistral 7B model (first time only):

docker compose exec ollama ollama pull mistral:7b

Production Service URLs

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs
• Ollama: http://localhost:11434

Expected AI Response Time:

• CPU: 12-20 seconds
• GPU: 2-8 seconds (with NVIDIA acceleration)

NVIDIA GPU Configuration (Optional)

For GPU acceleration on Linux, create docker-compose.prod.yml:

services:
  ollama:
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Then start with:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Stopping Production Environment

docker compose down

To remove all data (reset):

docker compose down -v

🏗️ Tech Stack

Frontend:

• React 18 with TypeScript
• Vite for blazing-fast builds
• Tailwind CSS for styling
• Recharts for data visualization
• React Router v6 for navigation
• Axios for API calls

Backend:

• FastAPI (Python 3.11+) with async/await
• Pydantic for data validation
• PostgreSQL 15 for data persistence
• OpenAI-compatible client for LLM

AI/ML:

• Mistral 7B via Ollama (local inference)
• Multi-agent architecture (Orchestrator, Finance, Projects agents)
• Natural language understanding for queries

Infrastructure:

• Docker Compose for orchestration
• PostgreSQL with optimized indexes
• Nginx for frontend serving

💬 AI Chat Examples

Ask MoneyMind in natural language:

Financial Health:

• "What's my runway?"
• "What's my burn rate?"
• "Am I profitable?"

Cashflow:

• "What's my current balance?"
• "What will my balance be next month?"
• "Show me cashflow projection for 6 months"

Income & Expenses:

• "How much did I earn last month?"
• "What are my biggest expenses?"
• "What are my recurring expenses?"

Projects:

• "Which project is most profitable?"
• "How many hours did I log this week?"
• "Show me active projects"

🎯 Key Concepts

Business Percentage Allocation

MoneyMind allows you to allocate expenses between business and personal use:

• 100% Business: GitHub Copilot ($20/month)
• Mixed: Internet bill ($80/month, 40% business = $32 business cost)
• Personal: Groceries ($150/month, 0% business = $0 business cost)

All financial calculations (runway, burn rate) use the business portion only for accuracy.

Cashflow Projections

The system projects your cash position forward based on:

• Current balance
• Pending income (distributed over next 3 months)
• Average monthly income (from last 90 days)
• Monthly expenses: recurring expenses if set, otherwise average from last 90 days

📊 Dashboard Metrics

• Runway - Months of operation at current burn rate
• Burn Rate - Average monthly business expenses
• Net Cash Flow - Monthly income minus expenses
• Current Balance - Latest bank account snapshot
• Projected Balance - Forecasted balance (3-6 months)

🧪 Testing

Backend tests:

cd api
pytest --cov=api --cov-report=html

Frontend tests:

cd web
npm test -- --coverage

Run all tests:

cd api && python3 -m pytest

🔒 Privacy & Security

• 100% Local - All data stays on your machine
• No Cloud Services - No external API calls
• No Tracking - No telemetry or analytics
• Open Source - Full transparency
• $0/month - No subscription fees

📦 Project Structure

moneymind/
├── api/                # FastAPI backend
│   ├── agents/         # AI agents (orchestrator, finance, projects)
│   ├── routers/        # API endpoints (11 routers)
│   └── services/       # Database, LLM services
├── web/                # React frontend
│   ├── src/
│   │   ├── pages/      # 9 pages
│   │   ├── components/ # 8 components
│   │   └── hooks/      # 5 custom hooks
├── database/           # PostgreSQL schema
├── docs/               # Documentation
└── tests/              # Test suite

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Built with FastAPI
• Powered by Mistral 7B
• UI with Tailwind CSS
• Charts by Recharts

---

MoneyMind - AI-Powered Personal Finance, 100% Local, $0/month

Built for privacy, designed for freelancers, powered by Mistral 7B