# harryjsmith40/financial-data-tracker architecture

> Architecture diagram of the GitHub repository harryjsmith40/financial-data-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harryjsmith40/financial-data-tracker
- Repository: https://github.com/harryjsmith40/financial-data-tracker

## Overview

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`](https://github.com/harryjsmith40/financial-data-tracker/blob/main/financial_visualiser.py) (financial_visualiser.py), [`Config/config.py`](https://github.com/harryjsmith40/financial-data-tracker/blob/main/Config/config.py) (config.py), [`main.py`](https://github.com/harryjsmith40/financial-data-tracker/blob/main/main.py) (main.py), [`data_repository.py`](https://github.com/harryjsmith40/financial-data-tracker/blob/main/data_repository.py) (data_repository.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_main_py(("main.py<br/>entrypoint<br/>[main.py]"))
end

subgraph group_ingest["Ingestion"]
  node_csv_exports["CSV exports<br/>input source"]
  node_data_repository_py[("data_repository.py<br/>[data_repository.py]")]
  node_master_dataset[("Master data<br/>local store")]
end

subgraph group_core["Tracking"]
  node_financial_tracker_py["financial_tracker.py<br/>domain logic"]
end

subgraph group_viz["Visuals"]
  node_financial_visualiser_py["financial_visualiser.py<br/>plotting"]
  node_charts["Charts<br/>output"]
end

subgraph group_config["Config"]
  node_config_py["config.py<br/>settings<br/>[config.py]"]
  node_style_mpl["style file<br/>matplotlib style"]
end

node_main_py -->|"ingest"| node_data_repository_py
node_main_py -->|"analyze"| node_financial_tracker_py
node_main_py -->|"plot"| node_financial_visualiser_py
node_csv_exports -->|"read"| node_data_repository_py
node_data_repository_py -->|"merge"| node_master_dataset
node_master_dataset -->|"load"| node_financial_tracker_py
node_financial_tracker_py -->|"prepare"| node_financial_visualiser_py
node_financial_visualiser_py -->|"render"| node_charts
node_config_py -->|"settings"| node_main_py
node_config_py -->|"paths"| node_data_repository_py
node_config_py -->|"constants"| node_financial_tracker_py
node_config_py -->|"style"| node_financial_visualiser_py
node_style_mpl -->|"theme"| node_financial_visualiser_py

click node_main_py "https://github.com/harryjsmith40/financial-data-tracker/blob/main/main.py"
click node_data_repository_py "https://github.com/harryjsmith40/financial-data-tracker/blob/main/data_repository.py"
click node_financial_tracker_py "https://github.com/harryjsmith40/financial-data-tracker/blob/main/financial_tracker.py"
click node_financial_visualiser_py "https://github.com/harryjsmith40/financial-data-tracker/blob/main/financial_visualiser.py"
click node_config_py "https://github.com/harryjsmith40/financial-data-tracker/blob/main/Config/config.py"
click node_style_mpl "https://github.com/harryjsmith40/financial-data-tracker/blob/main/Config/amount_over_date.mplstyle"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_py toneBlue
class node_csv_exports,node_data_repository_py,node_master_dataset toneAmber
class node_financial_tracker_py toneMint
class node_financial_visualiser_py,node_charts toneRose
class node_config_py,node_style_mpl toneIndigo
```

## Components

### CLI

User entry and interactive orchestration

- [main.py](https://github.com/harryjsmith40/financial-data-tracker/blob/main/main.py): entrypoint · Interactive CLI controller · `main.py`

### Ingestion

CSV loading, normalization, and local persistence

- **CSV exports**: input source · Bank account statement files
- [data_repository.py](https://github.com/harryjsmith40/financial-data-tracker/blob/main/data_repository.py): repository · Ingests, normalizes, and merges transactions · `data_repository.py`
- **Master data**: local store · Canonical merged transaction history

### Tracking

Finance rules and aggregation

- [financial_tracker.py](https://github.com/harryjsmith40/financial-data-tracker/blob/main/financial_tracker.py): domain logic · Cleans, filters, and aggregates finance data · `financial_tracker.py`

### Visuals

Chart generation and presentation

- [financial_visualiser.py](https://github.com/harryjsmith40/financial-data-tracker/blob/main/financial_visualiser.py): plotting · Builds net worth, spending, and income charts · `financial_visualiser.py`
- **Charts**: output · Rendered financial views

### Config

Shared settings and plotting style

- [config.py](https://github.com/harryjsmith40/financial-data-tracker/blob/main/Config/config.py): settings · Shared paths, constants, and display options · `Config/config.py`
- [style file](https://github.com/harryjsmith40/financial-data-tracker/blob/main/Config/amount_over_date.mplstyle): matplotlib style · Custom chart styling · `Config/amount_over_date.mplstyle`

## Connections

- 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
