How thombergs/buckpal works
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.