# luca12341234/jbudget architecture

> Architecture diagram of the GitHub repository luca12341234/jbudget, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luca12341234/jbudget
- Repository: https://github.com/luca12341234/jbudget

## Overview

1. **Repository shape and runtime**
   This is a **Java desktop application** built with **JavaFX** and **Gradle Kotlin DSL**. The persistence layer uses **Hibernate** against a local file database (`app/data/jbudgetdb.mv.db`), which strongly suggests an embedded **H2-style** database setup rather than a remote server.

2. **Top-level architectural style**
   The code is organized as a classic layered desktop app:
   **JavaFX UI → control/helpers → service layer → repository layer → Hibernate/database**.
   The layers are separated by interfaces in most places, so the UI does not talk directly to persistence.

3. **UI composition**
   The visible screens are defined in `src/main/resources/view`:
   `Main.fxml`, `Categories.fxml`, `Deadlines.fxml`, `Transactions.fxml`, and `Statistics.fxml`.
   Styling is centralized in `css/style.css`.  
   `MainApp.java` is the application entry point and likely loads the main shell and navigates between these views.

4. **Presentation controllers**
   The controllers live under `control/view/api/fx`:
   `CategoriesController`, `DeadlinesController`, `TransactionsController`, and `StatisticsController`.
   They implement view-facing interfaces from `control/view/api`, which keeps the FXML controllers aligned with explicit contracts such as `ITransactionsView` and `IStatisticsView`.

5. **UI support/binding utilities**
   The `control` package contains reusable presentation helpers that keep controller code thin:
   - `alert` for user feedback dialogs
   - `form` for form state/validation helpers
   - `combo` for category dropdown binding
   - `table` for action buttons embedded in table columns
   - `transactions` for table refresh, row mapping, and table binding
   - `statistics` for summary calculation and series building  
   These classes are the glue between JavaFX widgets and the app’s domain data.

6. **Domain model**
   The core business entities are in `model/entity`:
   `Category`, `Deadline`, and `Transaction`, all based on `BaseEntity`.
   Supporting model types include:
   - `Identifiable` and `Named` interfaces
   - enums `TransactionType` and `FilterMode`
   - row/view models such as `CategoryRow`, `DeadlineRow`, and `MovementRow`  
   The separation between entities and row models indicates the UI does not bind directly to persistence objects in every case.

7. **Business services**
   The service layer is under `service/impl` with interfaces in `service/api`.
   It provides CRUD-style orchestration for the main entities:
   - `CategoryServiceImpl`
   - `DeadlineServiceImpl`
   - `TransactionServiceImpl`  
   `AbstractCrudService` provides shared behavior, so the concrete services likely add domain-specific rules, such as transaction filtering, budget/deadline checks, or category-related lookups.

8. **Persistence layer**
   The repositories in `infra/persistence` are the data-access boundary:
   - generic `CrudRepository` and `HibernateRepository`
   - entity-specific `CategoryRepository`, `DeadlineRepository`, `TransactionRepository`
   - `TxPredicateBuilder` for building transaction queries dynamically  
   This suggests that querying is partly criteria/predicate-based, especially for transaction filtering and reporting.

9. **Infrastructure and wiring**
   `infra/config` contains the bootstrapping and ORM setup:
   - `HibernateUtil` for session factory/configuration
   - `ServiceFactory` for dependency construction
   - `CategoryFields` and `TransactionFields` for field-name constants or query mapping  
   This is the app’s composition root: the point where services and repositories are assembled.

10. **Primary data flows**
   The main runtime flow is:
   **FXML event → controller → helper/binder → service → repository → Hibernate → local DB**.
   Data comes back as entities or row/view models, then is rendered into tables, forms, combo boxes, or statistics views.

11. **Transactions as the central workflow**
   The most elaborate subsystem is transaction management:
   `TransactionsController` works with `TransactionsTableBinder`, `TransactionsRefresher`, `MovementRowMapper`, and `TxFilter`.
   That implies support for listing, filtering, mapping, and refreshing transaction rows in response to user actions.

12. **Statistics and reporting**
   The statistics screen is isolated from transaction entry and uses `SummaryCalculator` and `SeriesBuilder`.
   This indicates a read-only analytical path: transaction data is aggregated into summaries/series for display, likely in charts or KPIs.

13. **Categories and deadlines as supporting bounded contexts**
   Categories and deadlines are separate user-facing modules, each with its own controller, service, repository, and row model.
   They are structurally parallel to transactions, which makes them good candidates for separate boxes in an architecture diagram.

14. **What to show in an architecture diagram**
   The clearest boundaries to draw are:
   - **JavaFX view layer** with FXML screens and controllers
   - **presentation helpers/binders** for tables/forms/alerts
   - **service layer** for business rules
   - **repository/ORM layer** for persistence
   - **domain model** at the center
   - **local database file** as the storage backend  
   A good diagram should emphasize that this is a **single-user desktop application with local persistence**, not a distributed client-server system.

Main entry points: [`app/src/main/java/it/unicam/cs/mpgc/jbudget125576/control/view/api/fx`](https://github.com/luca12341234/jbudget/tree/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/control/view/api/fx) (FXML controllers), [`app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/TransactionServiceImpl.java`](https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/TransactionServiceImpl.java) (Transaction service), [`app/src/main/java/it/unicam/cs/mpgc/jbudget125576/control`](https://github.com/luca12341234/jbudget/tree/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/control) (UI helpers), [`app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/CategoryServiceImpl.java`](https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/CategoryServiceImpl.java) (Category service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["JavaFX UI"]
  node_mainapp["MainApp<br/>entrypoint<br/>[MainApp.java]"]
  node_mainfxml["Main shell<br/>fxml view<br/>[Main.fxml]"]
  node_transactionsfx["Transactions<br/>fxml view<br/>[Transactions.fxml]"]
  node_categoriesfx["Categories<br/>fxml view<br/>[Categories.fxml]"]
  node_deadlinesfx["Deadlines<br/>fxml view<br/>[Deadlines.fxml]"]
  node_statisticsfx["Statistics<br/>fxml view<br/>[Statistics.fxml]"]
  node_controllers["FXML controllers<br/>view controllers"]
end

subgraph group_presentation["Presentation helpers"]
  node_presentationhelpers["UI helpers<br/>binding helpers"]
end

subgraph group_domain["Domain model"]
  node_domainmodel["Domain entities"]
end

subgraph group_application["Services"]
  node_categoryservice["Category service"]
  node_deadlineservice["Deadline service"]
  node_transactionservice["Transaction service"]
  node_crudbase["CRUD base<br/>service base"]
end

subgraph group_persistence["Persistence"]
  node_categoryrepo["Category repo"]
  node_deadlinerepo["Deadline repo"]
  node_transactionrepo["Transaction repo"]
  node_hibernate["Hibernate ORM<br/>orm config<br/>[HibernateUtil.java]"]
  node_servicefactory["Service factory<br/>composition root"]
end

subgraph group_storage["Local storage"]
  node_dbfile[("Budget DB<br/>embedded database<br/>[jbudgetdb.mv.db]")]
end

node_mainapp -->|"loads"| node_mainfxml
node_mainapp -->|"initializes"| node_servicefactory
node_mainfxml -->|"hosts"| node_controllers
node_controllers -->|"uses"| node_presentationhelpers
node_controllers -->|"calls"| node_categoryservice
node_controllers -->|"calls"| node_deadlineservice
node_controllers -->|"calls"| node_transactionservice
node_controllers -->|"binds"| node_domainmodel
node_presentationhelpers -->|"maps"| node_domainmodel
node_presentationhelpers -->|"reads"| node_transactionservice
node_presentationhelpers -->|"reads"| node_categoryservice
node_presentationhelpers -->|"reads"| node_deadlineservice
node_categoryservice -->|"extends"| node_crudbase
node_deadlineservice -->|"extends"| node_crudbase
node_transactionservice -->|"extends"| node_crudbase
node_categoryservice -->|"uses"| node_categoryrepo
node_deadlineservice -->|"uses"| node_deadlinerepo
node_transactionservice -->|"uses"| node_transactionrepo
node_transactionservice -->|"filters"| node_domainmodel
node_categoryrepo -->|"runs on"| node_hibernate
node_deadlinerepo -->|"runs on"| node_hibernate
node_transactionrepo -->|"runs on"| node_hibernate
node_hibernate -->|"stores in"| node_dbfile
node_servicefactory -->|"creates"| node_categoryservice
node_servicefactory -->|"creates"| node_deadlineservice
node_servicefactory -->|"creates"| node_transactionservice
node_transactionsfx -->|"backed by"| node_controllers
node_categoriesfx -->|"backed by"| node_controllers
node_deadlinesfx -->|"backed by"| node_controllers
node_statisticsfx -->|"backed by"| node_controllers

click node_mainapp "https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/MainApp.java"
click node_mainfxml "https://github.com/luca12341234/jbudget/blob/main/app/src/main/resources/view/Main.fxml"
click node_transactionsfx "https://github.com/luca12341234/jbudget/blob/main/app/src/main/resources/view/Transactions.fxml"
click node_categoriesfx "https://github.com/luca12341234/jbudget/blob/main/app/src/main/resources/view/Categories.fxml"
click node_deadlinesfx "https://github.com/luca12341234/jbudget/blob/main/app/src/main/resources/view/Deadlines.fxml"
click node_statisticsfx "https://github.com/luca12341234/jbudget/blob/main/app/src/main/resources/view/Statistics.fxml"
click node_controllers "https://github.com/luca12341234/jbudget/tree/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/control/view/api/fx"
click node_presentationhelpers "https://github.com/luca12341234/jbudget/tree/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/control"
click node_categoryservice "https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/CategoryServiceImpl.java"
click node_deadlineservice "https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/DeadlineServiceImpl.java"
click node_transactionservice "https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/TransactionServiceImpl.java"
click node_crudbase "https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/base/AbstractCrudService.java"
click node_categoryrepo "https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/infra/persistence/CategoryRepository.java"
click node_deadlinerepo "https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/infra/persistence/DeadlineRepository.java"
click node_transactionrepo "https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/infra/persistence/TransactionRepository.java"
click node_hibernate "https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/infra/config/HibernateUtil.java"
click node_servicefactory "https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/infra/config/ServiceFactory.java"
click node_domainmodel "https://github.com/luca12341234/jbudget/tree/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/model"
click node_dbfile "https://github.com/luca12341234/jbudget/blob/main/app/data/jbudgetdb.mv.db"

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_mainapp,node_mainfxml,node_transactionsfx,node_categoriesfx,node_deadlinesfx,node_statisticsfx,node_controllers toneBlue
class node_presentationhelpers toneAmber
class node_domainmodel toneMint
class node_categoryservice,node_deadlineservice,node_transactionservice,node_crudbase toneRose
class node_categoryrepo,node_deadlinerepo,node_transactionrepo,node_hibernate,node_servicefactory toneIndigo
class node_dbfile toneTeal
```

## Components

### JavaFX UI

FXML screens and controllers

- [MainApp](https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/MainApp.java): entrypoint · JavaFX application bootstrap and navigation root · `app/src/main/java/it/unicam/cs/mpgc/jbudget125576/MainApp.java`
- [Main shell](https://github.com/luca12341234/jbudget/blob/main/app/src/main/resources/view/Main.fxml): fxml view · Primary application shell · `app/src/main/resources/view/Main.fxml`
- [Transactions](https://github.com/luca12341234/jbudget/blob/main/app/src/main/resources/view/Transactions.fxml): fxml view · Transaction management screen · `app/src/main/resources/view/Transactions.fxml`
- [Categories](https://github.com/luca12341234/jbudget/blob/main/app/src/main/resources/view/Categories.fxml): fxml view · Category management screen · `app/src/main/resources/view/Categories.fxml`
- [Deadlines](https://github.com/luca12341234/jbudget/blob/main/app/src/main/resources/view/Deadlines.fxml): fxml view · Deadline management screen · `app/src/main/resources/view/Deadlines.fxml`
- [Statistics](https://github.com/luca12341234/jbudget/blob/main/app/src/main/resources/view/Statistics.fxml): fxml view · Reporting and summary screen · `app/src/main/resources/view/Statistics.fxml`
- [FXML controllers](https://github.com/luca12341234/jbudget/tree/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/control/view/api/fx): view controllers · Screen controllers implementing view contracts · `app/src/main/java/it/unicam/cs/mpgc/jbudget125576/control/view/api/fx`

### Presentation helpers

Bindings, forms, alerts, and table utilities

- [UI helpers](https://github.com/luca12341234/jbudget/tree/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/control): binding helpers · Alerts, forms, combo binding, table actions, and transaction/statistics glue · `app/src/main/java/it/unicam/cs/mpgc/jbudget125576/control`

### Domain model

Core entities, row models, and enums

- [Domain entities](https://github.com/luca12341234/jbudget/tree/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/model): entities · Category, Deadline, Transaction, base entity, interfaces, and row models · `app/src/main/java/it/unicam/cs/mpgc/jbudget125576/model`

### Services

Business orchestration and CRUD rules

- [Category service](https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/CategoryServiceImpl.java): service · Category CRUD orchestration and rules · `app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/CategoryServiceImpl.java`
- [Deadline service](https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/DeadlineServiceImpl.java): service · Deadline CRUD orchestration and rules · `app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/DeadlineServiceImpl.java`
- [Transaction service](https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/TransactionServiceImpl.java): service · Transaction CRUD, filtering, and reporting orchestration · `app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/TransactionServiceImpl.java`
- [CRUD base](https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/base/AbstractCrudService.java): service base · Shared CRUD service behavior · `app/src/main/java/it/unicam/cs/mpgc/jbudget125576/service/impl/base/AbstractCrudService.java`

### Persistence

Repositories, query builders, and ORM setup

- [Category repo](https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/infra/persistence/CategoryRepository.java): repository · Category persistence boundary · `app/src/main/java/it/unicam/cs/mpgc/jbudget125576/infra/persistence/CategoryRepository.java`
- [Deadline repo](https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/infra/persistence/DeadlineRepository.java): repository · Deadline persistence boundary · `app/src/main/java/it/unicam/cs/mpgc/jbudget125576/infra/persistence/DeadlineRepository.java`
- [Transaction repo](https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/infra/persistence/TransactionRepository.java): repository · Transaction persistence and query access · `app/src/main/java/it/unicam/cs/mpgc/jbudget125576/infra/persistence/TransactionRepository.java`
- [Hibernate ORM](https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/infra/config/HibernateUtil.java): orm config · Session factory and ORM bootstrap · `app/src/main/java/it/unicam/cs/mpgc/jbudget125576/infra/config/HibernateUtil.java`
- [Service factory](https://github.com/luca12341234/jbudget/blob/main/app/src/main/java/it/unicam/cs/mpgc/jbudget125576/infra/config/ServiceFactory.java): composition root · Wires services and repositories · `app/src/main/java/it/unicam/cs/mpgc/jbudget125576/infra/config/ServiceFactory.java`

### Local storage

Embedded database file

- [Budget DB](https://github.com/luca12341234/jbudget/blob/main/app/data/jbudgetdb.mv.db): embedded database · Local persisted database file · `app/data/jbudgetdb.mv.db`

## Connections

- MainApp → Main shell: loads · Bootstraps the main shell
- MainApp → Service factory: initializes · Creates application services
- Main shell → FXML controllers: hosts · Main shell embeds screen controllers
- FXML controllers → UI helpers: uses · Controllers delegate UI state and widget binding
- FXML controllers → Category service: calls · Category screen operations
- FXML controllers → Deadline service: calls · Deadline screen operations
- FXML controllers → Transaction service: calls · Transaction screen operations
- FXML controllers → Domain entities: binds · Controllers render entities and row models
- UI helpers → Domain entities: maps · Transforms domain data into table rows, summaries, and chart series
- UI helpers → Transaction service: reads · Transaction table refresh and filtering helpers
- UI helpers → Category service: reads · Category combo binding and lookup
- UI helpers → Deadline service: reads · Deadline-related form support
- Category service → CRUD base: extends · Shares CRUD service behavior
- Deadline service → CRUD base: extends · Shares CRUD service behavior
- Transaction service → CRUD base: extends · Shares CRUD service behavior
- Category service → Category repo: uses · Persists categories
- Deadline service → Deadline repo: uses · Persists deadlines
- Transaction service → Transaction repo: uses · Persists and queries transactions
- Transaction service → Domain entities: filters · Applies transaction/domain rules and row projections
- Category repo → Hibernate ORM: runs on · Repository access is backed by Hibernate sessions
- Deadline repo → Hibernate ORM: runs on · Repository access is backed by Hibernate sessions
- Transaction repo → Hibernate ORM: runs on · Repository access is backed by Hibernate sessions
- Hibernate ORM → Budget DB: stores in · Persists to the local database file
- Service factory → Category service: creates · Composes category service
- Service factory → Deadline service: creates · Composes deadline service
- Service factory → Transaction service: creates · Composes transaction service
- Transactions → FXML controllers: backed by · Transaction view is controlled by the FX controller
- Categories → FXML controllers: backed by · Category view is controlled by the FX controller
- Deadlines → FXML controllers: backed by · Deadline view is controlled by the FX controller
- Statistics → FXML controllers: backed by · Statistics view is controlled by the FX controller
