XpenseTracker 💰

A self-hosted, Python-based expense and income tracking application with AI receipt scanning.

Features

• Modern UI
  Built with the web-based NiceGui framework.
• Financial Dashboard
  Overview of your income, expenses, balance, and savings rate with interactive charts.
• AI Receipt Scanning
  Upload a receipt and let AI extract the details automatically.
• Income & Expense Tracking
  Log both earnings and spendings with strict input validation.
• Transaction History
  View all your transactions with inline editing and dynamic category filtering.
• Customizable Settings
  Manage categories, currencies, and AI providers.
• Data Safety
  Includes scripts for automated data backups.

Tech Stack

• Frontend: NiceGui
• Backend: Python, FastAPI, SQLAlchemy
• Database: PostgreSQL or SQLite
• AI: Google Gemini API / OpenAI API (& more to come)

Configuration

You can configure the database type in .env:

DB_TYPE=postgres # or sqlite

If using SQLite, the database file will be stored in app/data/xpensetracker.db.

Installation Setup

1. Clone the repository.

2. Configure Environment:

   • Rename .env.example to the active configuration file .env and fill in the required content, including any necessary API keys.

3. Run with Docker:

   docker compose up --build

4. Access the App:

   • Open your browser and navigate to http://localhost:8501.

Development Setup

1. Create Virtual Environment:

   python -m venv .venv

2. Activate Virtual Environment:

   • Windows (PowerShell):

     .venv\Scripts\Activate.ps1

   • Linux/macOS:

     source .venv/bin/activate

3. Install Dependencies:

   pip install -r requirements.txt

4. Run Tests:
   See tests/TESTING.md for detailed testing instructions.

   & ".venv/Scripts/python.exe" -m pytest tests/

Deployment & Backups

For detailed instructions on how to deploy to a Raspberry Pi or manage backups, see the deployment/ folder:

• Raspberry Pi Guide
• Production & Backup Guide
  • Includes manual update steps if Watchtower is disabled.