Fix database location for package installation

[7174Andy]

Summary

This PR fixes a critical bug where the expense tracker application fails when installed via uv tool install spendwise-tracker or pip install. The issue was caused by hardcoded relative paths (expense_tracker/data/transactions.db) that only work when running from the source directory.

The solution migrates database storage to platform-specific user data directories following OS conventions, while maintaining full backward compatibility for existing users.

Changes

New Utilities

• expense_tracker/utils/path.py - Platform-specific data directory resolution

  • get_data_directory(): Returns appropriate data directory based on OS (macOS: ~/Library/Application Support/spendwise-tracker/, Linux: ~/.local/share/spendwise-tracker/, Windows: %LOCALAPPDATA%\spendwise-tracker\)
  • get_database_path(filename): Constructs full database file paths
  • Automatically creates directories if they don't exist

• expense_tracker/utils/migration.py - Legacy database migration

  • migrate_legacy_databases(): Automatically copies databases from old location on first launch
  • Safe copy operation (doesn't delete legacy files)
  • Logs migration events for debugging
  • Gracefully handles migration failures

Modified Files

• expense_tracker/app.py:15-25 - Updated entry point

  • Calls migration on startup
  • Prints database locations for user transparency
  • Uses get_database_path() for both repositories

• CLAUDE.md - Updated documentation with new database location information

Tests

• tests/utils/test_path.py - 78 lines of platform path resolution tests
• tests/utils/test_migration.py - 124 lines of migration scenario tests

Database Locations

New Locations (Platform-Specific)

• macOS: ~/Library/Application Support/spendwise-tracker/
• Linux/Unix: ~/.local/share/spendwise-tracker/
• Windows: %LOCALAPPDATA%\spendwise-tracker\

Legacy Location

• expense_tracker/data/ (relative to source code directory)

Migration Behavior

1. Fresh Installation: Creates databases directly in new platform-specific location
2. Existing Users: Automatically copies databases from expense_tracker/data/ to new location on first launch
3. Already Migrated: Skips migration if databases already exist in new location
4. Legacy Files: Original files remain untouched for manual cleanup/rollback

Example Usage

After installing via uv tool install:

$ expense-tracker
Using data directory for databases.
 - Transactions DB: /Users/username/Library/Application Support/spendwise-tracker/transactions.db
 - Merchant Categories DB: /Users/username/Library/Application Support/spendwise-tracker/merchant_categories.db

The application now works correctly regardless of where it's installed or from which directory it's launched.

Design Decisions

1. Platform-Specific Directories (No External Dependencies)

Used stdlib pathlib and platform.system() instead of platformdirs library to keep dependencies minimal. The logic is straightforward (~20 lines) and covers all major platforms.

2. Copy (Not Move) During Migration

Migration copies legacy databases rather than moving them, reducing risk of data loss. Users can roll back to previous version if needed, and can manually delete legacy files when confident.

3. Automatic Directory Creation

Data directory is created automatically with mkdir(parents=True, exist_ok=True), providing zero-configuration setup for users.

4. No Configuration Override

Intentionally excluded environment variable or config file overrides for database location to maintain simplicity. This can be added later if there's user demand.

Testing

All tests pass, including:

• ✅ Platform detection for macOS, Windows, Linux
• ✅ Data directory creation
• ✅ Database path resolution
• ✅ Migration scenarios (fresh install, existing databases, partial migration)
• ✅ Migration failure handling
• ✅ Multiple platform edge cases

Future Considerations

• CLI command to show database location: Could add expense-tracker --db-path for debugging
• Custom location support: Could add environment variable override if users request it
• Automatic cleanup: Could prompt users to delete legacy files after successful migration
• Multi-user support: Not planned for this single-user desktop app, but architecture now supports it