Finance Manager

A self-hosted, LLM-powered personal finance management web application that automatically categorizes your expenses and provides detailed analytics.

Features

• Automated Expense Categorization: Uses LLM (OpenAI GPT or local Ollama) to intelligently categorize transactions
• Multiple File Format Support: Upload CSV, Excel, or PDF bank statements
• Rich Analytics Dashboard: View spending patterns by week, month, quarter, or year
• Interactive Visualizations: Charts and graphs for easy analysis
• Self-Hosted: Complete control over your financial data
• Single Docker Container: Easy deployment with external database support
• Flexible LLM Options: Use OpenAI API or run locally with Ollama

Screenshots

The application provides:

• File upload interface for bank statements
• Summary cards showing income, expenses, and net balance
• Category breakdown with interactive pie charts
• Time-based trends with line charts
• Transaction history table
• Upload history tracking

Architecture

• Backend: FastAPI (Python)
• Frontend: HTML/CSS/JavaScript with Chart.js
• Database: PostgreSQL (external or containerized)
• LLM: OpenAI GPT-3.5/4 or Ollama (local)

Quick Start

Prerequisites

• Docker and Docker Compose installed
• PostgreSQL database (external or use the included one)
• OpenAI API key OR Ollama installed (for local LLM)

Installation

1. Clone the repository

git clone <your-repo-url>
cd finance-manager

2. Configure environment variables

Copy the example environment file:

cp .env.example .env

Edit .env with your settings:

For OpenAI (recommended for best results):

DATABASE_URL=postgresql://user:password@db:5432/financedb
USE_OLLAMA=false
OPENAI_API_KEY=sk-your-actual-openai-api-key
OPENAI_MODEL=gpt-3.5-turbo

For Ollama (local, no API costs):

DATABASE_URL=postgresql://user:password@db:5432/financedb
USE_OLLAMA=true
OLLAMA_URL=http://ollama:11434/v1
OLLAMA_MODEL=llama2

3. Start the application

docker-compose up -d

4. Access the application

Open your browser and navigate to:

http://localhost:8000

Using an External Database

To use your own PostgreSQL database instead of the containerized one:

1. Update the DATABASE_URL in your .env file:

DATABASE_URL=postgresql://username:password@your-db-host:5432/your-database

2. Comment out the db service in docker-compose.yml:

# db:
#   image: postgres:15-alpine
#   ...

3. Remove the depends_on in the finance-manager service:

finance-manager:
  build: .
  # Remove or comment out:
  # depends_on:
  #   - db

File Format Support

CSV Files

The parser automatically detects common column names:

• Date: date, transaction date, posting date, trans date
• Description: description, memo, payee, merchant, details
• Amount: amount, transaction amount, debit, credit

Example CSV format:

Date,Description,Amount
2024-01-15,Grocery Store,-45.67
2024-01-16,Salary Deposit,2500.00
2024-01-17,Gas Station,-35.20

Excel Files (.xlsx, .xls)

Same column detection as CSV files. Supports standard Excel formats.

PDF Files

Automatically extracts transaction data from PDF bank statements using LLM. Works best with structured PDF statements from major banks.

Usage

1. Upload a Statement

   • Click "Choose File" and select your bank statement (CSV, Excel, or PDF)
   • Click "Upload & Process"
   • Wait for the LLM to categorize all transactions

2. View Analytics

   • Select time period (Week/Month/Quarter/Year)
   • Review summary cards for income, expenses, and net
   • Analyze spending by category using the pie chart
   • Track trends over time with the line chart

3. Review Transactions

   • Scroll down to see all transactions
   • Each transaction shows date, description, category, and amount

4. Check Upload History

   • View all previously uploaded files
   • See processing status and transaction counts

Default Categories

The LLM automatically assigns transactions to these categories:

• Food & Dining
• Groceries
• Transportation
• Shopping
• Entertainment
• Bills & Utilities
• Healthcare
• Travel
• Income
• Transfer
• Other

API Endpoints

The application provides a REST API:

• POST /api/upload - Upload and process a bank statement
• GET /api/transactions - Get transactions with filters
• GET /api/categories - Get all categories
• POST /api/categories - Create a new category
• GET /api/analytics - Get analytics for a time period
• GET /api/uploads - Get upload history
• PUT /api/transactions/{id}/category - Update transaction category
• GET /health - Health check endpoint

API documentation available at: http://localhost:8000/docs

Configuration Options

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	postgresql://user:password@db:5432/financedb
USE_OLLAMA	Use local Ollama instead of OpenAI	false
OPENAI_API_KEY	Your OpenAI API key	Required if USE_OLLAMA=false
OPENAI_MODEL	OpenAI model to use	gpt-3.5-turbo
OLLAMA_URL	Ollama API endpoint	http://localhost:11434/v1
OLLAMA_MODEL	Ollama model to use	llama2

Using Ollama (Local LLM)

To use Ollama instead of OpenAI:

1. Uncomment the Ollama service in docker-compose.yml

2. Pull a model (first time only):

docker-compose exec ollama ollama pull llama2

3. Update environment variables:

USE_OLLAMA=true
OLLAMA_URL=http://ollama:11434/v1
OLLAMA_MODEL=llama2

Deployment

Production Deployment

For production use:

1. Use an external database for better persistence and backups
2. Set strong passwords in your environment variables
3. Enable HTTPS using a reverse proxy (nginx, Traefik, etc.)
4. Regular backups of your PostgreSQL database
5. Monitor logs for any issues

Reverse Proxy Example (nginx)

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Troubleshooting

Database Connection Issues

# Check if database is running
docker-compose ps

# View logs
docker-compose logs db
docker-compose logs finance-manager

LLM Categorization Not Working

• Verify your OPENAI_API_KEY is correct
• Check API quota and billing
• For Ollama, ensure the model is pulled: docker-compose exec ollama ollama list

File Upload Fails

• Check file format is supported (CSV, XLSX, PDF)
• Ensure file contains proper column headers
• Review logs: docker-compose logs finance-manager

Development

Running Locally (without Docker)

1. Install dependencies:

cd backend
pip install -r requirements.txt

2. Set environment variables:

export DATABASE_URL=postgresql://user:password@localhost:5432/financedb
export OPENAI_API_KEY=your-key-here

3. Run the application:

uvicorn app.main:app --reload

Database Migrations

The application automatically creates database tables on startup. For manual migration management, you can use Alembic (included in requirements).

Security Considerations

• Data Privacy: All financial data stays on your server
• API Keys: Never commit API keys to version control
• Database: Use strong passwords and restrict access
• HTTPS: Always use HTTPS in production
• Updates: Keep Docker images and dependencies updated

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - feel free to use this for personal or commercial purposes.

Support

For issues, questions, or contributions, please open an issue on GitHub.

Roadmap

Future enhancements:

• Budget tracking and alerts
• Recurring transaction detection
• Multi-user support with authentication
• Mobile app
• Export reports to PDF
• Integration with bank APIs
• Custom categorization rules
• Spending predictions using ML

---

Made with ❤️ for better personal finance management