How mika-rsbg/budget-planner works
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: connection.py Database connection · main.py Application entry · transaction_repository.py Transaction repositories · interpreter.py MT940 interpreter
Components 22
Desktop GUI
Window infrastructure, navigation, and feature screens.
- Window base classes
src/gui/app/basewindow.py - Menu navigation plugins
- Feature pages · Accounts, categories, home, transactions, and import review.
Feature Layer
Business services, repositories, and statement import.
- Account service
src/features/account/account_service.py - Account repositories · Current account operations and account history access.
- Transaction service
src/features/transaction/transaction_service.py - Transaction repositories · Transaction storage and type lookup.
src/features/transaction/transaction_repository.py - Category feature
src/features/category/service.py - Counterparty repository
src/features/counterparty/counterparty_repository.py - MT940 import coordinator
src/features/importer/mt940/importer.py - MT940 parser
src/features/importer/mt940/parser.py - MT940 interpreter
src/features/importer/mt940/interpreter.py - Import database service · Resolves and persists interpreted import data.
src/features/importer/mt940/database_service.py - Import table formatter
src/features/importer/formater/table_formater.py
Local Persistence
Database abstraction and schema initialization.
- Database connection
src/core/database/connection.py - Database schema
src/core/database/schema.py
Domain Models
Persistent and import-review representations.
- Business entities · Accounts, categories, counterparties, transactions, and transaction types.
- Import review models · Raw imported records and review views.
src/models/transaction/imported.py
Other components
- Application entry
src/main.py - App settings
src/config.py - Logging
src/core/logging/logger_config.py - Value and date utilities · Currency, date, and value normalization.
src/shared/currency_utils.py
Connections 28
- 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