# mika-rsbg/budget-planner architecture

> Architecture diagram of the GitHub repository mika-rsbg/budget-planner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mika-rsbg/budget-planner
- Repository: https://github.com/mika-rsbg/budget-planner

## Overview

#### Purpose and Entry Point
Budget-Planner is a local Python desktop application for recording accounts, transactions, categories, counterparties, and imported bank statements to support personal budget tracking. Runtime starts at `src/main.py`; application-wide settings are centralized in `src/config.py`. The primary user boundary is a GUI, not a web/API service.

#### Presentation and Navigation
The GUI is organized as reusable window bases, feature pages, and menu-extension plugins. `src/gui/app/basewindow.py` and `src/gui/app/basetoplevelwindow.py` provide window infrastructure. Feature screens include account management (`src/gui/pages/account/accountpage.py`), categories (`src/gui/pages/category/categoriepage.py`), transaction management/import review (`src/gui/pages/transaction/transactionpage.py`, `src/gui/pages/transaction/import_overview.py`), and the home view (`src/gui/pages/home/homepage.py`). Menu plugins under `src/gui/plugins/menu_extension/` connect navigation actions to these pages.

#### Domain Model Layer
Persistent business concepts are represented by entity/view models rather than GUI-specific data structures: accounts in `src/models/account/entity.py`, categories in `src/models/category/entity.py`, counterparties in `src/models/counterparty/entity.py`, and transactions in `src/models/transaction/entity.py`. Import-specific representations—raw imported records and review views—are separated in `src/models/transaction/imported.py` and `src/models/transaction/import_view.py`. Transaction types have their own model at `src/models/transaction_typ/entity.py`.

#### Service and Repository Boundary
Feature modules use repositories for database access and services for business orchestration. Accounts split current account access/history and operations across `src/features/account/account_repository.py`, `src/features/account/account_history_repository.py`, and `src/features/account/account_service.py`. Transactions follow the same shape in `src/features/transaction/transaction_repository.py` and `src/features/transaction/transaction_service.py`; type lookup is isolated in `src/features/transaction/transaction_typ_repository.py`. Categories use `src/features/category/category_repository.py` plus `src/features/category/service.py`; counterparties currently expose repository access via `src/features/counterparty/counterparty_repository.py`.

#### Database Core
Persistence is local and abstracted behind `src/core/database/connection.py`; schema definition/initialization belongs in `src/core/database/schema.py`. Repositories are the intended boundary between feature logic and storage, allowing GUI pages and services to work with domain entities rather than direct SQL/schema concerns. The repository tree does not indicate a remote database, backend server, or external SaaS dependency.

#### MT940 Import Pipeline
Bank-statement import is a distinct staged subsystem under `src/features/importer/mt940/`. `src/features/importer/mt940/importer.py` coordinates import, `parser.py` reads MT940 input, and `interpreter.py` transforms parsed records into application meaning. `database_service.py` persists or resolves import data, while `errors.py` defines import failure handling. Formatting for tabular presentation is separate in `src/features/importer/formater/table_formater.py` and `table_config.py`, feeding GUI import-review flows rather than contaminating parser logic.

#### Cross-Cutting Operations
Logging is centrally configured through `src/core/logging/logger_config.py`, with cleanup and utility operations in `src/core/logging/clean_log.py` and `src/core/logging/logging_tools.py`. Shared normalization/calculation primitives—currency, date, and value handling—live in `src/shared/currency_utils.py`, `src/shared/date_utils.py`, and `src/shared/value_utils.py`. Typical control flow is GUI action → feature service/repository → database → entity/view model → GUI refresh; MT940 follows file input → parser/interpreter → import persistence/review → transaction-facing UI.

Main entry points: [`src/core/database/connection.py`](https://github.com/mika-rsbg/budget-planner/blob/main/src/core/database/connection.py) (Database connection), [`src/main.py`](https://github.com/mika-rsbg/budget-planner/blob/main/src/main.py) (Application entry), [`src/features/transaction/transaction_repository.py`](https://github.com/mika-rsbg/budget-planner/blob/main/src/features/transaction/transaction_repository.py) (Transaction repositories), [`src/features/importer/mt940/interpreter.py`](https://github.com/mika-rsbg/budget-planner/blob/main/src/features/importer/mt940/interpreter.py) (MT940 interpreter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gui["Desktop GUI"]
  node_window_base["Window base classes<br/>GUI infrastructure<br/>[basewindow.py]"]
  node_menu_plugins["Menu navigation plugins<br/>GUI plugins"]
  node_feature_pages["Feature pages<br/>GUI screens"]
end

subgraph group_features["Feature Layer"]
  node_account_service["Account service<br/>feature service<br/>[account_service.py]"]
  node_account_repos["Account repositories"]
  node_transaction_service["Transaction service<br/>feature service"]
  node_transaction_repos["Transaction repositories"]
  node_category_feature["Category feature<br/>service and repository<br/>[service.py]"]
  node_counterparty_repo["Counterparty repository"]
  node_mt940_importer["MT940 import coordinator<br/>import service<br/>[importer.py]"]
  node_mt940_parser["MT940 parser<br/>import stage<br/>[parser.py]"]
  node_mt940_interpreter["MT940 interpreter<br/>import stage<br/>[interpreter.py]"]
  node_import_database["Import database service<br/>import persistence"]
  node_table_formatter["Import table formatter<br/>presentation formatter<br/>[table_formater.py]"]
end

subgraph group_persistence["Local Persistence"]
  node_database[("Database connection<br/>local database access<br/>[connection.py]")]
  node_schema["Database schema<br/>schema initialization<br/>[schema.py]"]
end

subgraph group_domain["Domain Models"]
  node_domain_models["Business entities<br/>domain entities"]
  node_import_models["Import review models<br/>import models<br/>[imported.py]"]
end

node_entry{{"Application entry<br/>Python runtime<br/>[main.py]"}}
node_config["App settings<br/>configuration<br/>[config.py]"]
node_logging["Logging<br/>[logger_config.py]"]
node_shared_utils["Value and date utilities<br/>shared primitives<br/>[currency_utils.py]"]

node_entry -->|"loads"| node_config
node_entry -->|"starts GUI"| node_window_base
node_entry -->|"configures"| node_logging
node_window_base -->|"hosts"| node_feature_pages
node_menu_plugins -->|"navigates to"| node_feature_pages
node_feature_pages -->|"account actions"| node_account_service
node_feature_pages -->|"transaction actions"| node_transaction_service
node_feature_pages -->|"category actions"| node_category_feature
node_feature_pages -->|"counterparty access"| node_counterparty_repo
node_feature_pages -->|"imports statements"| node_mt940_importer
node_account_service -->|"orchestrates"| node_account_repos
node_transaction_service -->|"orchestrates"| node_transaction_repos
node_account_repos -->|"persists via"| node_database
node_transaction_repos -->|"persists via"| node_database
node_category_feature -->|"persists via"| node_database
node_counterparty_repo -->|"accesses"| node_database
node_database -.->|"initialized by"| node_schema
node_account_repos -->|"maps"| node_domain_models
node_transaction_repos -->|"maps"| node_domain_models
node_mt940_importer -->|"parses file"| node_mt940_parser
node_mt940_parser -->|"parsed records"| node_mt940_interpreter
node_mt940_interpreter -->|"interpreted data"| node_import_database
node_import_database -->|"persists or resolves"| node_database
node_mt940_interpreter -->|"creates review data"| node_import_models
node_import_models -->|"formats"| node_table_formatter
node_table_formatter -->|"import review table"| node_feature_pages
node_shared_utils -.->|"normalizes values"| node_account_service
node_shared_utils -.->|"normalizes values"| node_transaction_service

click node_entry "https://github.com/mika-rsbg/budget-planner/blob/main/src/main.py"
click node_config "https://github.com/mika-rsbg/budget-planner/blob/main/src/config.py"
click node_window_base "https://github.com/mika-rsbg/budget-planner/blob/main/src/gui/app/basewindow.py"
click node_account_service "https://github.com/mika-rsbg/budget-planner/blob/main/src/features/account/account_service.py"
click node_transaction_service "https://github.com/mika-rsbg/budget-planner/blob/main/src/features/transaction/transaction_service.py"
click node_transaction_repos "https://github.com/mika-rsbg/budget-planner/blob/main/src/features/transaction/transaction_repository.py"
click node_category_feature "https://github.com/mika-rsbg/budget-planner/blob/main/src/features/category/service.py"
click node_counterparty_repo "https://github.com/mika-rsbg/budget-planner/blob/main/src/features/counterparty/counterparty_repository.py"
click node_mt940_importer "https://github.com/mika-rsbg/budget-planner/blob/main/src/features/importer/mt940/importer.py"
click node_mt940_parser "https://github.com/mika-rsbg/budget-planner/blob/main/src/features/importer/mt940/parser.py"
click node_mt940_interpreter "https://github.com/mika-rsbg/budget-planner/blob/main/src/features/importer/mt940/interpreter.py"
click node_import_database "https://github.com/mika-rsbg/budget-planner/blob/main/src/features/importer/mt940/database_service.py"
click node_table_formatter "https://github.com/mika-rsbg/budget-planner/blob/main/src/features/importer/formater/table_formater.py"
click node_import_models "https://github.com/mika-rsbg/budget-planner/blob/main/src/models/transaction/imported.py"
click node_database "https://github.com/mika-rsbg/budget-planner/blob/main/src/core/database/connection.py"
click node_schema "https://github.com/mika-rsbg/budget-planner/blob/main/src/core/database/schema.py"
click node_logging "https://github.com/mika-rsbg/budget-planner/blob/main/src/core/logging/logger_config.py"
click node_shared_utils "https://github.com/mika-rsbg/budget-planner/blob/main/src/shared/currency_utils.py"

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_window_base,node_menu_plugins,node_feature_pages toneBlue
class node_account_service,node_account_repos,node_transaction_service,node_transaction_repos,node_category_feature,node_counterparty_repo,node_mt940_importer,node_mt940_parser,node_mt940_interpreter,node_import_database,node_table_formatter toneAmber
class node_database,node_schema toneMint
class node_domain_models,node_import_models toneRose
class node_entry,node_config,node_logging,node_shared_utils toneNeutral
```

## Components

### Desktop GUI

Window infrastructure, navigation, and feature screens.

- [Window base classes](https://github.com/mika-rsbg/budget-planner/blob/main/src/gui/app/basewindow.py): GUI infrastructure · `src/gui/app/basewindow.py`
- **Menu navigation plugins**: GUI plugins
- **Feature pages**: GUI screens · Accounts, categories, home, transactions, and import review.

### Feature Layer

Business services, repositories, and statement import.

- [Account service](https://github.com/mika-rsbg/budget-planner/blob/main/src/features/account/account_service.py): feature service · `src/features/account/account_service.py`
- **Account repositories**: repositories · Current account operations and account history access.
- [Transaction service](https://github.com/mika-rsbg/budget-planner/blob/main/src/features/transaction/transaction_service.py): feature service · `src/features/transaction/transaction_service.py`
- [Transaction repositories](https://github.com/mika-rsbg/budget-planner/blob/main/src/features/transaction/transaction_repository.py): repositories · Transaction storage and type lookup. · `src/features/transaction/transaction_repository.py`
- [Category feature](https://github.com/mika-rsbg/budget-planner/blob/main/src/features/category/service.py): service and repository · `src/features/category/service.py`
- [Counterparty repository](https://github.com/mika-rsbg/budget-planner/blob/main/src/features/counterparty/counterparty_repository.py): repository · `src/features/counterparty/counterparty_repository.py`
- [MT940 import coordinator](https://github.com/mika-rsbg/budget-planner/blob/main/src/features/importer/mt940/importer.py): import service · `src/features/importer/mt940/importer.py`
- [MT940 parser](https://github.com/mika-rsbg/budget-planner/blob/main/src/features/importer/mt940/parser.py): import stage · `src/features/importer/mt940/parser.py`
- [MT940 interpreter](https://github.com/mika-rsbg/budget-planner/blob/main/src/features/importer/mt940/interpreter.py): import stage · `src/features/importer/mt940/interpreter.py`
- [Import database service](https://github.com/mika-rsbg/budget-planner/blob/main/src/features/importer/mt940/database_service.py): import persistence · Resolves and persists interpreted import data. · `src/features/importer/mt940/database_service.py`
- [Import table formatter](https://github.com/mika-rsbg/budget-planner/blob/main/src/features/importer/formater/table_formater.py): presentation formatter · `src/features/importer/formater/table_formater.py`

### Local Persistence

Database abstraction and schema initialization.

- [Database connection](https://github.com/mika-rsbg/budget-planner/blob/main/src/core/database/connection.py): local database access · `src/core/database/connection.py`
- [Database schema](https://github.com/mika-rsbg/budget-planner/blob/main/src/core/database/schema.py): schema initialization · `src/core/database/schema.py`

### Domain Models

Persistent and import-review representations.

- **Business entities**: domain entities · Accounts, categories, counterparties, transactions, and transaction types.
- [Import review models](https://github.com/mika-rsbg/budget-planner/blob/main/src/models/transaction/imported.py): import models · Raw imported records and review views. · `src/models/transaction/imported.py`

### Other components

- [Application entry](https://github.com/mika-rsbg/budget-planner/blob/main/src/main.py): Python runtime · `src/main.py`
- [App settings](https://github.com/mika-rsbg/budget-planner/blob/main/src/config.py): configuration · `src/config.py`
- [Logging](https://github.com/mika-rsbg/budget-planner/blob/main/src/core/logging/logger_config.py): cross-cutting logging · `src/core/logging/logger_config.py`
- [Value and date utilities](https://github.com/mika-rsbg/budget-planner/blob/main/src/shared/currency_utils.py): shared primitives · Currency, date, and value normalization. · `src/shared/currency_utils.py`

## Connections

- Application entry → App settings: loads
- Application entry → Window base classes: starts GUI
- Application entry → Logging: configures
- Window base classes → Feature pages: hosts
- Menu navigation plugins → Feature pages: navigates to
- Feature pages → Account service: account actions
- Feature pages → Transaction service: transaction actions
- Feature pages → Category feature: category actions
- Feature pages → Counterparty repository: counterparty access
- Feature pages → MT940 import coordinator: imports statements
- Account service → Account repositories: orchestrates
- Transaction service → Transaction repositories: orchestrates
- Account repositories → Database connection: persists via
- Transaction repositories → Database connection: persists via
- Category feature → Database connection: persists via
- Counterparty repository → Database connection: accesses
- Database connection → Database schema: initialized by
- Account repositories → Business entities: maps
- Transaction repositories → Business entities: maps
- MT940 import coordinator → MT940 parser: parses file
- MT940 parser → MT940 interpreter: parsed records
- MT940 interpreter → Import database service: interpreted data
- Import database service → Database connection: persists or resolves
- MT940 interpreter → Import review models: creates review data
- Import review models → Import table formatter: formats
- Import table formatter → Feature pages: import review table
- Value and date utilities → Account service: normalizes values
- Value and date utilities → Transaction service: normalizes values
