Financial Transaction Manager

A comprehensive suite of tools for managing and analyzing financial transactions with a beautiful dark-themed GUI.

📋 Table of Contents

• Overview
• Features
• Quick Start
• Applications
• Installation
• Usage Guide
• File Structure
• Troubleshooting
• Advanced Features

Overview

This project provides a comprehensive financial transaction management application:

Transaction Manager: Full-featured database system with categorization, filtering, analytics, and built-in export capabilities

The application features a modern dark theme with easy toggle support.

Features

✨ Transaction Manager

• 🗄️ SQLite Database: Persistent storage with automatic duplicate detection
• 🏷️ Smart Categorization: Pattern-based auto-categorization with regex support
• 📊 Visual Analytics: Summary views with drill-down capabilities
• 📅 Date Filtering: Quick filters (30/60/90 days, This Year, All Time)
• 📥 Multi-Format Import: Import CSV, OFX, QFX, and QBO files
• 📂 Bulk Import: Import single or multiple files at once
• 🔍 Transaction Deletion: Selective deletion by category and date range
• 📊 ODS Export: Export filtered data to formatted spreadsheets with color coding
• 🌙 Dark Theme: Eye-friendly interface with toggle support

Quick Start

Windows (Double-Click Launch)

Transaction Manager:

launch_transaction_manager.bat

Command Line

Transaction Manager:

python transaction_manager_gui.py

Export Summary Generator:

python export_summary_gui.py

Build Executable (Windows):

build_exe.bat

Application

Transaction Manager

The main application for comprehensive transaction management with built-in export capabilities.

Key Tabs

📥 Import Data Tab

• Select transaction files to import (CSV, OFX, QFX, QBO)
• Configure import settings for CSV files (skip lines, duplicate detection)
• Auto-detection of file format
• View import log and statistics
• Bulk import from folder (supports mixed file types)

📊 Summary Tab

• View transactions grouped by category
• Filter by date range and category
• Sort by any column
• Double-click to drill down into transactions
• Delete transactions by category/date
• Export filtered data to ODS format with color coding

🏷️ Manage Categories Tab

• Create/edit/delete categories
• Configure pattern matching rules
• Pattern types: contains, startswith, endswith, exact, regex
• Recategorize all transactions with one click

Pattern Matching Examples

Name: Amazon Purchases
Pattern: AMAZON MKTPL
Type: contains
→ Matches: "AMAZON MKTPL*XYZ123", "POS AMAZON MKTPL"

Name: Gas Stations  
Pattern: ^(ARCO|SHELL|76)
Type: regex
→ Matches: "ARCO #1234", "SHELL GAS", "76 STATION"

2. Export Summary Generator

Simplified interface for generating transaction summaries.

Workflow

1. Select a CSV file (Export.csv, download.CSV, or browse)
2. Generate summary using SQL aggregation
3. View results with automatic color formatting
4. Open directly in LibreOffice Calc

Output Files

• ExportSummary-YYYYMMDD.csv - Raw data
• ExportSummary-YYYYMMDD.ods - Formatted with colors (requires odfpy)

Installation

Prerequisites

• Python 3.6+ - Download
• q command (CSV processor) - Auto-installed
• ofxparse (OFX/QFX/QBO support) - Auto-installed
• LibreOffice/OpenOffice (optional, for best viewing) - Download

Automated Setup (Windows)

setup.bat

This will:

• Check Python installation
• Install required packages
• Verify setup
• Launch the application

Manual Installation

# Install dependencies
pip install -r requirements.txt

# Build executable (optional)
pip install pyinstaller
pyinstaller transaction_manager.spec

Dependencies

q-text-as-data    # CSV processing with SQL
odfpy             # ODS file formatting (optional)
pyinstaller       # Executable building (optional)

Built-in modules: tkinter, sqlite3, csv, hashlib, re, datetime

Usage Guide

First-Time Setup

The Transaction Manager automatically:

• Creates the database (transactions.db)
• Initializes default categories
• Shows a welcome message

Importing Transactions

Supported File Formats:

• CSV - Comma-separated values from bank exports
• OFX - Open Financial Exchange (standard format)
• QFX - Quicken Financial Exchange
• QBO - QuickBooks Online format

Single File Import:

1. Go to "Import Data" tab
2. Click "Select File (CSV/OFX/QFX/QBO)"
3. For CSV:
   • Configure skip lines (if needed)
   • Review auto-detected column mapping
   • Adjust mappings if needed (drag-drop selection)
   • Preview data
   • Import
4. For OFX/QFX/QBO: Automatic import (no configuration needed)
5. Transactions imported with duplicate detection

Bulk Import:

1. Click "Import All Files in Folder"
2. Select directory containing transaction files
3. Supports mixed file types (CSV + OFX)
4. Configure settings (applies to CSV files)
5. Confirm import

Flexible Column Mapping:

• ✨ NEW: Works with ANY CSV format from any bank!
• Auto-detects common column names (Date, Amount, Description, etc.)
• Manual mapping for custom column names
• Supports both separate Debit/Credit columns OR single Amount column
• Mappings are automatically saved for future imports

CSV Column Requirements:

• Required: Date field, Description field
• Amount: Either one "Amount" column OR both "Debit" and "Credit" columns
• Optional: Balance, Memo, Transaction Number, Check Number, Fees

Supported CSV Formats:

• Chase, Bank of America, Wells Fargo, Capital One, Discover
• PayPal, Venmo, Cash App
• Credit card statements
• Investment account exports
• ...and any other CSV format!

OFX/QFX/QBO Files:

• Automatically parsed with no configuration needed
• Extracts date, description, amount, payee, memo, and check number
• Supports multiple accounts in a single file

Duplicate Detection

Transactions are hashed using the entire CSV line for accurate duplicate detection:

• Same transaction from different files → Skipped
• Any field differs → Imported as new
• Import log shows: "Imported: X, Skipped: Y duplicates"

Working with Categories

Creating Categories:

1. Go to "Manage Categories" tab
2. Click "New Category"
3. Enter name, pattern, and pattern type
4. Click "Save Category"
5. Choose "Recategorize All" to apply

Finding Uncategorized Transactions:

1. Go to "Summary" tab
2. Look for individual transaction descriptions (not categories)
3. Right-click → "Create New Category from This"
4. Adjust pattern as needed

Date Range Filtering

Quick Filters:

• Last 30 Days
• Last 60 Days
• Last 90 Days
• This Year
• All Time

Custom Range:

• Enter dates in YYYY-MM-DD format
• Click "Refresh" to apply

Deleting Transactions

From Summary View:

1. Select one or more categories (Ctrl+Click)
2. Right-click → "Delete Selected Transactions"
3. Confirm deletion (shows affected count)

From Transaction Details:

1. Double-click category to open details
2. Select transactions to delete
3. Click "Delete Selected" or right-click
4. Confirm deletion

Generating Export Summaries

1. Launch Export Summary Generator
2. Select or browse to CSV file
3. Click "Generate Export Summary"
4. Wait for processing
5. Click "Open in Calc" or "Open Folder"

The summary includes:

• Description grouping
• Total Debit/Credit
• Count, Average, Min, Max
• Date range per category

File Structure

Application Files

transaction_manager_gui.py    # Main GUI application
transaction_db.py             # Database operations
transaction_importer.py       # CSV import logic
export_summary_gui.py         # Export summary generator
theme.py                      # Dark/light theme support
import_settings.py            # Import configuration manager

Launchers (Windows)

launch_transaction_manager.bat  # Transaction Manager launcher
launch_gui.bat                  # Export Summary launcher  
build_exe.bat                   # Build executable
reset_database.bat              # Reset database

Configuration

import_settings.json          # Saved import configurations
transactions.db               # SQLite database (auto-created)
ExportSummary.sql             # SQL template for summaries

Documentation

README.md                     # This file (main documentation)
BUILD_EXE_INSTRUCTIONS.md     # Executable building guide
IMPORT_SETTINGS_GUIDE.md      # Import configuration details
requirements.txt              # Python dependencies

Build Output (Generated)

build/                        # PyInstaller build artifacts
dist/TransactionManager/      # Standalone executable
dist/TransactionManager.zip   # Portable distribution

Troubleshooting

Common Issues

"q command not found"

pip install q-text-as-data
# Restart terminal/Command Prompt after install

Import shows "0 imported, all skipped"

• Transactions already exist in database (duplicate detection working)
• Delete transactions.db to start fresh (CAUTION: removes all data)

No color formatting in ODS files

pip install odfpy

Can't open results automatically

• Install LibreOffice/OpenOffice
• Or click "Open Folder" and open manually

Database errors

# Reset database (CAUTION: deletes all data)
del transactions.db  # Windows
rm transactions.db   # Linux/Mac

# Or use the reset script
reset_database.bat  # Windows

CSV import errors

• Check CSV has Date and Description columns
• Verify date format (MM/DD/YYYY)
• Check for extra header rows (use skip lines)
• Look at import log for specific errors

Theme not applying correctly

• Click "Toggle Theme" twice to refresh
• Some widgets require restarting the application

Debug Mode

Enable verbose logging in CSV import dialog:

• Check "Show hash details for first 3 rows"
• View import log for hash calculations
• Helps diagnose duplicate detection issues

Advanced Features

Custom SQL Queries

Edit ExportSummary.sql to customize:

• Grouping logic
• Column calculations
• Date filters
• Description mappings

Pattern Matching Reference

Type	Description	Example
contains	Pattern anywhere in description	AMAZON → matches "AMAZON MKTPL*123"
startswith	Description starts with pattern	POS → matches "POS AMAZON"
endswith	Description ends with pattern	INC → matches "ACME INC"
exact	Exact match (case-insensitive)	PAYCHECK → matches only "PAYCHECK"
regex	Regular expression	^(SHELL|ARCO) → matches gas stations

Database Schema

transactions table:

• id: Primary key
• transaction_hash: SHA-256 for duplicate detection
• date, description, memo: Transaction details
• amount_debit, amount_credit, balance: Financial data
• category_id: Foreign key to categories
• imported_at: Import timestamp

categories table:

• id: Primary key
• name: Display name
• pattern: Match pattern
• pattern_type: Pattern matching mode
• description, color: Metadata
• created_at, updated_at: Timestamps

Building Executables

Quick Build:

build_exe.bat

Manual Build:

pyinstaller transaction_manager.spec

Output:

• dist/TransactionManager/TransactionManager.exe - Standalone executable
• dist/TransactionManager.zip - Portable package

Distribution:

• Copy entire dist/TransactionManager/ folder
• No Python installation required on target machine
• Database and settings travel with executable

Keyboard Shortcuts

Summary View:

• Ctrl+Click - Multi-select categories
• Shift+Click - Range select
• Double-Click - Drill down
• Right-Click - Context menu

Transaction Details:

• Ctrl+A - Select all
• Right-Click - Delete options

Performance Tips

1. Indexed Queries: Database uses indexes on date, category, and hash
2. Bulk Operations: Use bulk import for multiple files
3. Date Ranges: Narrow date ranges load faster
4. Categorization: Run "Recategorize All" after editing multiple categories

Dark Theme Support

All GUIs support dark theme:

• Toggle: Click "🌙 Toggle Theme" button
• Default: Dark mode enabled by default
• Consistent: All widgets properly themed
• Persistent: Theme choice maintained during session

Theme colors:

• Background: #1e1e1e
• Text: #d4d4d4
• Accent: #0e639c
• Success: #4ec9b0
• Error: #f48771

Contributing & Development

Code Structure

• transaction_db.py: All database operations
• transaction_importer.py: CSV parsing and import
• theme.py: Theme management
• import_settings.py: Configuration persistence
• GUI files: Tkinter-based interfaces

Adding Features

1. Database changes: Modify transaction_db.py schema
2. Import logic: Update transaction_importer.py
3. GUI elements: Edit GUI files, apply theme
4. New tools: Follow existing patterns

License

This project uses standard open-source tools and libraries.

Credits

Built with:

• Python 3 + tkinter (GUI framework)
• SQLite (database)
• q-text-as-data (CSV/SQL processing)
• odfpy (ODS file formatting)
• PyInstaller (executable building)

---

Ready to get started? Double-click launch_transaction_manager.bat or launch_gui.bat!

For questions or issues, review this README or examine the code comments.

Version: 2.0 | Updated: October 2024