# thombergs/buckpal architecture

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

- Interactive diagram: https://gitdiagram.com/thombergs/buckpal
- Repository: https://github.com/thombergs/buckpal

## Overview

##### Project type and purpose
- This is a full-stack micro-service-style web application built with Spring Boot, illustrating a Hexagonal (Clean) Architecture.
- It demonstrates sending money between accounts and retrieving balances.

##### File structure and README insights
- Top-level Gradle build files and CI workflow indicate standard Java/Spring Boot build & test processes.
- `src/main/java/io/reflectoring/buckpal`:
- `application/domain/model` & `application/domain/service`: the core business logic.
- `application/port/in` & `application/port/out`: the use-case interfaces (ports).
- `adapter/in/web`: HTTP-based inbound adapter (Spring MVC controller).
- `adapter/out/persistence`: JPA-based outbound adapter (persistence).
- Resources include `application.yml` (Spring configuration).

##### Main system components
a. Domain Layer (Core)
- Entity classes: Account, Activity, ActivityWindow, Money
- Business services: SendMoneyService, GetAccountBalanceService
b. Application Ports
- Inbound ports (UseCase interfaces): SendMoneyUseCase, GetAccountBalanceUseCase
- Outbound ports: LoadAccountPort, UpdateAccountStatePort, AccountLock
c. Inbound Adapter
- SendMoneyController (Spring MVC) exposing REST endpoint(s)
d. Outbound Adapter
- AccountPersistenceAdapter implementing persistence ports
- SpringDataAccountRepository & AccountJpaEntity for JPA mapping
- NoOpAccountLock (lock stub)
e. Infrastructure
- Embedded or external relational database (e.g., H2 / PostgreSQL)
- Spring Boot application entrypoint (BuckPalApplication)
f. Configuration
- BuckPalConfigurationProperties, application.yml

##### Relationships & data flow
1. Client → HTTP Request → SendMoneyController
2. Controller → SendMoneyUseCase (port) → SendMoneyService
3. SendMoneyService uses LoadAccountPort to retrieve Account aggregate
4. Business rules enforce thresholds, create Activity objects
5. Service calls UpdateAccountStatePort to persist new state
6. AccountPersistenceAdapter uses Spring Data JPA to save entities → Database
7. GetAccountBalanceService follows a similar flow via LoadAccountPort
8. AccountLock port would coordinate concurrency (stubbed by NoOpAccountLock)

##### Architectural patterns & principles
- Hexagonal Architecture (ports & adapters) ensures domain independence from frameworks.
- Dependency Inversion: domain layer defines interfaces, adapters implement them.
- Separation of concerns: clear boundaries between web, domain logic, and persistence.
- Use case–driven: each service class implements one use case.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client (Browser)"]:::external

    subgraph "Inbound Adapter"
        SMController["SendMoneyController"]:::adapterIn
    end

    subgraph "Application Ports (Inbound)"
        SMUseCase["SendMoneyUseCase"]:::portIn
        GABUseCase["GetAccountBalanceUseCase"]:::portIn
    end

    subgraph "Domain & Use Cases"
        SMSvc["SendMoneyService"]:::domain
        GABSvc["GetAccountBalanceService"]:::domain
        Account["Account"]:::domain
        Activity["Activity"]:::domain
        ActivityWindow["ActivityWindow"]:::domain
        Money["Money"]:::domain
    end

    subgraph "Application Ports (Outbound)"
        LoadPort["LoadAccountPort"]:::portOut
        UpdatePort["UpdateAccountStatePort"]:::portOut
        LockPort["AccountLock"]:::portOut
    end

    subgraph "Outbound Adapters"
        PersistenceAdapter["AccountPersistenceAdapter"]:::adapterOut
        JpaEntity["AccountJpaEntity"]:::adapterOut
        Repo["SpringDataAccountRepository"]:::adapterOut
        NoOpLock["NoOpAccountLock"]:::adapterOut
    end

    subgraph "Infrastructure"
        DB["Database"]:::external
        AppEntry["BuckPalApplication"]:::infra
        ConfigProps["BuckPalConfigurationProperties"]:::infra
        ConfigClass["BuckPalConfiguration"]:::infra
        Yml["application.yml"]:::infra
    end

    Client -->|"HTTP Request"| SMController
    SMController -->|"sendMoney() via SendMoneyUseCase"| SMUseCase
    SMUseCase -->|"sendMoney()"| SMSvc
    SMSvc -->|"loadAccount() via LoadAccountPort"| LoadPort
    LoadPort -->|"implemented by"| PersistenceAdapter
    PersistenceAdapter -->|"uses repository"| Repo
    Repo -->|"maps to"| JpaEntity
    SMSvc -->|"updateState() via UpdateAccountStatePort"| UpdatePort
    UpdatePort --> PersistenceAdapter
    SMSvc -->|"lockAccount() via AccountLock"| LockPort
    LockPort --> NoOpLock
    SMSvc -->|"response"| SMController
    SMController --> Client

    Client -->|"getBalance() via GetAccountBalanceUseCase"| GABUseCase
    GABUseCase -->|"getAccountBalance()"| GABSvc
    GABSvc -->|"loadAccount() via LoadAccountPort"| LoadPort
    GABSvc -->|"response"| SMController
    SMController --> Client

    PersistenceAdapter --> DB

    click Account "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/application/domain/model/Account.java"
    click Activity "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/application/domain/model/Activity.java"
    click ActivityWindow "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/application/domain/model/ActivityWindow.java"
    click Money "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/application/domain/model/Money.java"
    click SMSvc "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/application/domain/service/SendMoneyService.java"
    click GABSvc "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/application/domain/service/GetAccountBalanceService.java"
    click SMUseCase "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/application/port/in/SendMoneyUseCase.java"
    click GABUseCase "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/application/port/in/GetAccountBalanceUseCase.java"
    click LoadPort "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/application/port/out/LoadAccountPort.java"
    click UpdatePort "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/application/port/out/UpdateAccountStatePort.java"
    click LockPort "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/application/port/out/AccountLock.java"
    click SMController "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/adapter/in/web/SendMoneyController.java"
    click PersistenceAdapter "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/adapter/out/persistence/AccountPersistenceAdapter.java"
    click JpaEntity "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/adapter/out/persistence/AccountJpaEntity.java"
    click Repo "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/adapter/out/persistence/SpringDataAccountRepository.java"
    click NoOpLock "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/adapter/out/persistence/NoOpAccountLock.java"
    click AppEntry "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/BuckPalApplication.java"
    click ConfigProps "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/BuckPalConfigurationProperties.java"
    click ConfigClass "https://github.com/thombergs/buckpal/blob/master/src/main/java/io/reflectoring/buckpal/BuckPalConfiguration.java"
    click Yml "https://github.com/thombergs/buckpal/blob/master/src/main/resources/application.yml"

    classDef domain fill:#ffeb99,stroke:#333,stroke-width:1px
    classDef portIn fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef portOut fill:#d4edda,stroke:#333,stroke-width:1px
    classDef adapterIn fill:#d1ecf1,stroke:#333,stroke-width:1px
    classDef adapterOut fill:#c3e6cb,stroke:#333,stroke-width:1px
    classDef infra fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef external fill:#f5c6cb,stroke:#333,stroke-width:1px
```
