Skip to content

IP10/Expense-tracker

Repository files navigation

Expense Tracker App

A comprehensive expense tracking application with Android frontend and Python FastAPI backend, featuring AI-powered expense categorization.

Features

Core Functionality

  • βœ… User registration and authentication
  • βœ… Add expenses with automatic AI categorization
  • βœ… View and manage expense list
  • βœ… Generate reports (this month, last month, custom date range)
  • βœ… Category management with manual editing
  • βœ… INR currency support

Technical Features

  • πŸ€– Claude Sonnet AI-powered expense categorization with keyword fallback
  • πŸ“± Material Design 3 Android app
  • πŸ”’ JWT-based authentication
  • πŸ“Š Real-time expense analytics
  • ☁️ Supabase backend integration

Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    HTTP/REST     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    SQL    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   Android App   β”‚ ──────────────── β”‚  FastAPI Backend β”‚ ───────── β”‚    Supabase     β”‚
β”‚  (Jetpack       β”‚                  β”‚  (Python)       β”‚           β”‚   (PostgreSQL)  β”‚
β”‚   Compose)      β”‚                  β”‚                 β”‚           β”‚                 β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜           β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Tech Stack

Backend

  • Framework: FastAPI (Python)
  • Database: Supabase (PostgreSQL)
  • Authentication: JWT tokens
  • AI: Claude Sonnet API with keyword fallback
  • Testing: Pytest

Android App

  • UI: Jetpack Compose + Material Design 3
  • Architecture: MVVM with Hilt DI
  • Navigation: Navigation Compose
  • Networking: Retrofit + OkHttp
  • Testing: JUnit + Espresso

Setup Instructions

Prerequisites

  • Python 3.8+
  • Android Studio (latest version)
  • Supabase account

Backend Setup

  1. Create Supabase Project

    # Go to https://supabase.com and create a new project
    # Get your URL and API keys
  2. Database Schema

    -- Run this in Supabase SQL editor
    -- Users table
    CREATE TABLE users (
        id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
        email varchar UNIQUE NOT NULL,
        full_name varchar NOT NULL,
        password_hash varchar NOT NULL,
        created_at timestamptz DEFAULT now(),
        updated_at timestamptz DEFAULT now()
    );
    
    -- Categories table
    CREATE TABLE categories (
        id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
        name varchar NOT NULL,
        emoji varchar,
        is_system boolean DEFAULT false,
        user_id uuid REFERENCES users(id) ON DELETE CASCADE,
        created_at timestamptz DEFAULT now(),
        updated_at timestamptz DEFAULT now(),
        UNIQUE(name, user_id)
    );
    
    -- Expenses table
    CREATE TABLE expenses (
        id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
        user_id uuid REFERENCES users(id) ON DELETE CASCADE NOT NULL,
        amount decimal(10,2) NOT NULL CHECK (amount > 0),
        note varchar(500) NOT NULL,
        date date NOT NULL,
        category_id uuid REFERENCES categories(id) NOT NULL,
        created_at timestamptz DEFAULT now(),
        updated_at timestamptz DEFAULT now()
    );
    
    -- Indexes
    CREATE INDEX idx_expenses_user_id ON expenses(user_id);
    CREATE INDEX idx_expenses_date ON expenses(date);
    CREATE INDEX idx_expenses_category_id ON expenses(category_id);
    CREATE INDEX idx_categories_user_id ON categories(user_id);
  3. Backend Installation

    cd backend
    python -m venv venv
    source venv/bin/activate  # Windows: venv\Scripts\activate
    pip install -r requirements.txt
  4. Environment Setup

    cp .env.example .env
    # Edit .env with your Supabase and Claude API credentials:
    # SUPABASE_URL=your_supabase_url
    # SUPABASE_KEY=your_supabase_anon_key  
    # SUPABASE_SERVICE_KEY=your_supabase_service_key
    # JWT_SECRET=your_jwt_secret_key
    # ANTHROPIC_API_KEY=your_claude_api_key
  5. Run Backend

    python main.py
    # API will be available at http://localhost:8000

Android App Setup

  1. Open in Android Studio

    # Open android-app folder in Android Studio
  2. Build Project

    # Android Studio will automatically download dependencies
    # Make sure backend is running on localhost:8000
  3. Run App

    # Use Android Studio's run button or
    ./gradlew installDebug

Testing

Backend Tests

cd backend
pytest -v
pytest tests/test_auth.py -v
pytest tests/test_expenses.py -v
pytest tests/test_ai_categorizer.py -v

Android Tests

cd android-app
./gradlew test           # Unit tests
./gradlew connectedAndroidTest  # Integration tests

API Documentation

Authentication Endpoints

  • POST /api/auth/register - Register new user
  • POST /api/auth/login - Login user
  • POST /api/auth/refresh - Refresh access token
  • GET /api/auth/me - Get current user info

Expense Endpoints

  • POST /api/expenses/ - Create expense
  • GET /api/expenses/ - List expenses (with filters)
  • GET /api/expenses/{id} - Get expense details
  • PUT /api/expenses/{id} - Update expense
  • DELETE /api/expenses/{id} - Delete expense
  • POST /api/expenses/categorize-preview - Preview categorization

Category Endpoints

  • GET /api/categories/ - List categories
  • POST /api/categories/ - Create category
  • PUT /api/categories/{id} - Update category
  • DELETE /api/categories/{id} - Delete category

Report Endpoints

  • POST /api/reports/ - Generate custom report
  • GET /api/reports/this-month - This month report
  • GET /api/reports/last-month - Last month report
  • GET /api/reports/last-n-months/{n} - Last N months report
  • GET /api/reports/monthly-trend - Monthly trend data
  • GET /api/reports/summary - Overall summary

AI Categorization

The app uses Claude Sonnet AI for intelligent expense categorization with keyword-based fallback. This provides:

Default Categories

  • 🍽️ Food: restaurant, lunch, coffee, grocery, etc.
  • πŸš— Transport: uber, taxi, fuel, bus, flight, etc.
  • 🎬 Entertainment: movie, netflix, gym, concert, etc.
  • πŸ›’ Shopping: clothes, amazon, electronics, etc.
  • πŸ₯ Healthcare: doctor, medicine, hospital, etc.
  • πŸ’‘ Utilities: electricity, internet, rent, etc.
  • πŸ“š Education: course, books, fees, etc.
  • πŸ“ Other: fallback category

Categorization Logic

  1. Claude AI Analysis: Uses Claude Sonnet to understand context and nuances
  2. Indian Context Aware: Recognizes Swiggy=Food, Ola=Transport, etc.
  3. Keyword Fallback: Falls back to keyword matching if API unavailable
  4. Robust Error Handling: Always provides a category, never fails

Benefits of Claude Sonnet

  • Superior Context Understanding: Better than keyword matching alone
  • Indian Market Awareness: Understands local brands and services
  • Cost Efficient: Generally more cost-effective than GPT-4
  • Reliable Fallback: Keyword system ensures 100% uptime

Corner Cases Handled

Data Validation

  • βœ… Amount validation (positive, reasonable limits)
  • βœ… Note length limits and required fields
  • βœ… Date validation (no future dates beyond reasonable)
  • βœ… Category ownership verification

Error Handling

  • βœ… Network timeouts and retries
  • βœ… Authentication token expiry
  • βœ… Database constraint violations
  • βœ… Invalid input sanitization

Edge Scenarios

  • βœ… Empty expense lists
  • βœ… Category deletion (moves to "Other")
  • βœ… Concurrent data modifications
  • βœ… Large dataset performance

Development

Code Structure

Backend

backend/
β”œβ”€β”€ app/
β”‚   β”œβ”€β”€ routers/         # API endpoints
β”‚   β”œβ”€β”€ models.py        # Pydantic models
β”‚   β”œβ”€β”€ auth.py          # Authentication logic
β”‚   β”œβ”€β”€ database.py      # Database connection
β”‚   β”œβ”€β”€ ai_categorizer.py # AI categorization
β”‚   └── config.py        # Configuration
β”œβ”€β”€ tests/               # Test files
└── main.py             # FastAPI app

Android

android-app/src/main/java/com/expensetracker/app/
β”œβ”€β”€ data/                # Data layer (repositories, API)
β”œβ”€β”€ domain/              # Business logic (models, use cases)
β”œβ”€β”€ presentation/        # UI layer (Compose screens)
β”œβ”€β”€ di/                  # Dependency injection
└── utils/               # Utility functions

Contributing

  1. Fork the repository
  2. Create feature branch (git checkout -b feature/amazing-feature)
  3. Commit changes (git commit -m 'Add amazing feature')
  4. Push to branch (git push origin feature/amazing-feature)
  5. Open Pull Request

Testing Guidelines

  • Write tests for all new features
  • Maintain >80% code coverage
  • Test both happy path and error scenarios
  • Include integration tests for API endpoints

Deployment

Backend Deployment

  • Deploy to platforms like Railway, Render, or AWS
  • Set environment variables for production
  • Use production Supabase instance

Android Deployment

  • Build release APK: ./gradlew assembleRelease
  • Upload to Google Play Store
  • Update API endpoint to production URL

License

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

Support

For support or questions:

  • Create an issue in the repository
  • Check existing documentation
  • Review test files for usage examples

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages