BudgetTracker

A modern, full-stack financial tracking and campus meal credit management system built for high-performance and data consistency.

Project Overview

BudgetTracker is a cross-platform financial application that allows users to seamlessly track income, expenses, and manage meal credit donations. The system features a responsive frontend built with React/Vite and a robust backend powered by FastAPI and Google Cloud Firestore.

Core Engineering Highlights

This project was built with production-grade engineering practices in mind, specifically focusing on data integrity and resilient architecture:

• Idempotent Data Ingestion (MD5 Hashing): The CSV import pipeline generates a unique MD5 hash (date | description | amount_in_cents) for each transaction. This hash serves as the Firestore Document ID, ensuring 100% idempotency and preventing duplicate entries even if the same file is uploaded multiple times.
• Precision Currency Handling: To eliminate catastrophic floating-point precision loss (a critical requirement for financial systems), all currency values are parsed, converted, and stored as integers (cents) in the database, and only formatted back to decimals at the presentation layer.
• Decoupled Architecture: Clean separation of concerns with a RESTful API backend handling business logic and a lightweight frontend managing state and UI rendering.

Tech Stack

Frontend:

• React 19 & Vite
• JavaScript (ES6+)
• CSS3 (Custom responsive styling)

Backend:

• Python 3 & FastAPI
• Google Cloud Firestore (NoSQL Database)
• Uvicorn (ASGI server)

---

Getting Started (Local Development)

Follow these steps to get the project running on your local machine.

1. Backend Setup

Navigate to the backend directory and set up the Python environment:

cd backend

# (Optional but recommended) Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start the FastAPI server (runs on http://localhost:8000 by default)
uvicorn main:app --reload

*Note: Ensure your Google Cloud SDK is authenticated locally, as Firestore will automatically look for default credentials.*

### 2. Frontend Setup

Open a new terminal window, navigate to the frontend directory, and start the Vite dev server:

```bash
cd frontend

# Install Node modules
npm install

# Start the development server
npm run dev

The frontend will typically be available at http://localhost:5173.

Repository Structure

• /backend - FastAPI application, database configuration, and data processing logic.
• /frontend - React/Vite web application, API integration hooks, and UI components.