How harryjsmith40/financial-data-tracker works
1. Overall shape
- This is a small, local, Python-based CLI application for personal finance tracking.
- The architecture is centered around three concerns: ingest CSV exports, store/merge them into a master dataset, and plot financial views.
2. Entry point and orchestration
- main.py is the user-facing entry point.
- It likely coordinates the interactive menu flow described in the README: upload CSV, choose a visualization, or exit.
- This module is the top-level controller that connects input prompts to the data and plotting layers.
3. Transaction data management
- data_repository.py appears to be the persistence and data-access layer.
- Its responsibility is likely to read bank CSV exports, normalize them into a consistent structure, deduplicate transactions, and append them to a master record.
- The README suggests this layer also supports selecting an account and handling multiple account sources.
4. Domain/business logic
- financial_tracker.py is likely the core application logic between raw CSV data and visual output.
- Based on the README, it probably handles cleaning, filtering, categorization placeholders, and preparing transaction sets for net worth, spending, and income views.
- This is the main “finance rules” boundary, separate from file I/O and plotting.
5. Visualization subsystem
- financial_visualiser.py is the plotting layer.
- It likely builds the net worth, expense, and income charts described in the README using a plotting library such as Matplotlib.
- The architecture implies this module consumes prepared, aggregated data rather than raw CSV rows.
6. Configuration package
- The Config/ package holds cross-cutting settings and styling.
- Config/config.py likely centralizes file paths, constants, and display settings.
- Config/amount_over_date.mplstyle indicates a custom Matplotlib style file for consistent chart formatting.
7. Data flow through the system
- The main flow is: bank CSV export → load/clean → deduplicate/merge into master data → aggregate by time/account → visualize.
- Net worth appears to use a date-indexed rollup with forward filling to fill gaps between transactions.
- Spending and income views appear to filter transactions by sign/category and then sum them across accounts.
8. State and storage boundary
- The app is file-based, not service-based.
- The master transaction history is stored locally rather than in a database or remote API.
- That means the key architectural boundary is between downloaded bank CSV files and the local canonical dataset.
9. Multi-account support
- A central requirement of the system is combining multiple accounts into one historical picture.
- Architecture-wise, this means account identity matters during ingestion and aggregation, even if the raw CSV format is shared.
- The tracker is therefore not just a single-ledger viewer; it is an account-aggregation tool.
10. External dependencies and runtime
- The project is a Python application targeting Python 3.13.13.
- Its behavior strongly suggests dependencies on pandas for CSV/data manipulation and matplotlib for plotting.
- There is no evidence of web frameworks, servers, or cloud infrastructure; the app runs locally from main.py.
11. Repository intent vs. current scope
- The README describes a future ML categorization stage, but the current codebase is still Stage 1: manual CSV ingestion plus visualization.
- For an architecture diagram, treat ML as planned future work, not a current subsystem.
- The present system boundary ends at local data preparation and chart display.
12. Important diagram-friendly boundaries
- Separate the diagram into:
- CLI / user interaction
- Data ingestion and repository
- Finance processing / aggregation
- Visualization / chart rendering
- Configuration and styling
- The clearest dependency direction is from user actions into tracking logic, then into stored data and plots, with config supporting all layers.
Main entry points: financial_visualiser.py financial_visualiser.py · config.py config.py · main.py main.py · data_repository.py data_repository.py
Components 9
Ingestion
CSV loading, normalization, and local persistence
- CSV exports · Bank account statement files
- data_repository.py · Ingests, normalizes, and merges transactions
data_repository.py - Master data · Canonical merged transaction history
Tracking
Finance rules and aggregation
- financial_tracker.py · Cleans, filters, and aggregates finance data
financial_tracker.py
Visuals
Chart generation and presentation
- financial_visualiser.py · Builds net worth, spending, and income charts
financial_visualiser.py - Charts · Rendered financial views
Config
Shared settings and plotting style
- config.py · Shared paths, constants, and display options
Config/config.py - style file · Custom chart styling
Config/amount_over_date.mplstyle
Connections 13
- main.py → data_repository.py: ingest · Coordinates CSV upload flow
- main.py → financial_tracker.py: analyze · Requests account and view preparation
- main.py → financial_visualiser.py: plot · Launches visualization selection and rendering
- CSV exports → data_repository.py: read · Source files are parsed and normalized
- data_repository.py → Master data: merge · Appends deduplicated transactions into canonical storage
- Master data → financial_tracker.py: load · Provides transaction history for aggregation
- financial_tracker.py → financial_visualiser.py: prepare · Supplies summarized series and filtered views
- financial_visualiser.py → Charts: render · Produces the financial charts
- config.py → main.py: settings · Shared runtime options and paths
- config.py → data_repository.py: paths · Supports file locations and storage setup
- config.py → financial_tracker.py: constants · Supports finance rules and shared parameters
- config.py → financial_visualiser.py: style · Provides plotting configuration
- style file → financial_visualiser.py: theme · Applies consistent Matplotlib styling