Look at the cash bubblin

Overview

Getting that financial flow just right...

One in the hand, one in the bag, bubblin' (look at you go)

Look at the cash, look at the cash bubblin' (okay you bubblin')

-- Anderson .Paak - Bubblin'

Key Features

• Automated Categorization: Classifies transactions into predefined categories.
• Data Cleaning: Standardizes and cleans transaction descriptions.
• Google Sheets Export: Prepares and exports data in a format compatible with Google Sheets.
• Unassigned Transactions: Identifies and exports uncategorized transactions for manual review.
• Location Processing: Integrates with Google Maps for transaction location data.

Tech Stack

• Language: Python 3.14
• Libraries: pandas, numpy, loguru
• Testing: pytest, hypothesis, mypy
• Tools: ruff, pre-commit

Supported Banks

• PKO: Fully supported for importing and categorizing transactions.

System Architecture

The system follows a three-layer architecture:

• Data Input: Reads bank CSV transactions with Polish encoding support
• Processing Pipeline: Cleans data → Maps categories → Processes locations → Generates maps links
• Data Output: Exports to Google Sheets format, identifies unassigned transactions, and creates location links

Testing & Quality Assurance

This project maintains high code quality through comprehensive testing practices and automated CI/CD:

Testing Framework

• Unit Tests: Full test coverage using pytest for all core modules
• Integration Tests: End-to-end workflow validation
• Security Tests: Input validation and vulnerability testing
• Performance Tests: Benchmarking critical operations
• Property-Based Tests: Randomized testing with Hypothesis

Continuous Integration

• GitHub Actions CI/CD Pipeline: Automated testing on every push and pull request
• Multi-Stage Pipeline:
  • Stage 1: Code quality gates (Ruff formatting, linting, mypy type checking)
  • Stage 2: Parallel test execution (unit, integration, security, property-based, performance tests)
  • Stage 3: Coverage reporting (unit/integration/security/property tracks) and artifact archival

Performance tests run in a dedicated CI job with coverage disabled by design (--no-cov) to keep timing-focused checks stable and avoid skewing the enforced coverage threshold.

How to Use

1. Place your transaction CSV file in the data/ directory.
2. Fill the data_processing/category.py file with your personal category data.
3. Run the main script:

   python main.py

4. Processed data will be available in google_sheets_expenses.csv (and google_sheets_income.csv for the income track).

Why I Built This

We all want a clearer picture of our finances. I created this project to simplify that process. By automatically categorizing your bank transactions, it gives you effortless insights into your spending habits. This means you can stop guessing, start seeing patterns, and make better choices that improve your financial health.