# wikibook/clean-architecture architecture

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

- Interactive diagram: https://gitdiagram.com/wikibook/clean-architecture
- Repository: https://github.com/wikibook/clean-architecture

## Overview

##### Project type and purpose
- This is a Java Spring Boot web application demonstrating a domain-centric “Hexagonal” (Ports & Adapters) architecture.
- Its focus is on account management: querying balances and transferring money.

##### File structure
- Top-level: build files (Gradle), single module, Spring Boot entry point (BuckPalApplication).
- src/main/java/io/reflectoring/buckpal:
- BuckPalConfiguration / Properties – Spring Boot config
- account/application/port/in & /out – primary/secondary ports (UseCase interfaces)
- account/application/service – use-case implementations (business logic)
- account/domain – core entities (Account, Activity, ActivityWindow, Money)
- account/adapter/in/web – inbound adapter (SendMoneyController)
- account/adapter/out/persistence – outbound adapter (AccountPersistenceAdapter using JPA + Spring Data)
- Tests validate hexagonal rules, system behavior, unit tests for each layer.

##### Key insights from README
- The architecture style is explicitly Hexagonal (Ports & Adapters).
- Core separation: Domain → Application → Adapters (inbound & outbound).

##### Elements
- Clear labels for layers/components: Domain, Application Ports, Inbound Adapter, Outbound Adapter, Infrastructure
- From Controller → Input Port → Service → Output Port → Persistence Adapter → Repository → Database
- Return flows for query operations (GetAccountBalanceQuery)
- Interfaces (ports) vs. implementations (adapters).

## Diagram (Mermaid)

```mermaid
graph TB
    %% Domain Core
    subgraph "Domain Core"
        direction TB
        Account["Account"]:::domain
        Activity["Activity"]:::domain
        ActivityWindow["ActivityWindow"]:::domain
        Money["Money"]:::domain
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        %% Input Ports
        SendMoneyUseCase["SendMoneyUseCase"]:::portin
        GetAccountBalanceQuery["GetAccountBalanceQuery"]:::portin
        SendMoneyCommand["SendMoneyCommand"]:::portin

        %% Use Case Implementations
        SendMoneyService["SendMoneyService"]:::service
        GetAccountBalanceService["GetAccountBalanceService"]:::service
        NoOpAccountLock["NoOpAccountLock"]:::service
        MoneyTransferProperties["MoneyTransferProperties"]:::service
        ThresholdExceededException["ThresholdExceededException"]:::service

        %% Output Ports
        LoadAccountPort["LoadAccountPort"]:::portout
        UpdateAccountStatePort["UpdateAccountStatePort"]:::portout
        AccountLock["AccountLock"]:::portout
    end

    %% Inbound Adapter
    subgraph "Inbound Adapter"
        SendMoneyController["SendMoneyController"]:::adapterin
    end

    %% Outbound Adapter
    subgraph "Outbound Adapter"
        direction TB
        AccountPersistenceAdapter["AccountPersistenceAdapter"]:::adapterout
        AccountJpaEntity["AccountJpaEntity"]:::adapterout
        ActivityJpaEntity["ActivityJpaEntity"]:::adapterout
        AccountMapper["AccountMapper"]:::adapterout
        SpringDataAccountRepository["SpringDataAccountRepository"]:::adapterout
        ActivityRepository["ActivityRepository"]:::adapterout
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        BuckPalApplication["BuckPalApplication"]:::infra
        BuckPalConfiguration["BuckPalConfiguration"]:::infra
        BuckPalConfigurationProperties["BuckPalConfigurationProperties"]:::infra
        ApplicationYml["application.yml"]:::infra
        Database[(Database)]:::db
    end

    %% Connections
    SendMoneyController -->|"calls"| SendMoneyUseCase
    SendMoneyUseCase -->|"executes"| SendMoneyService
    SendMoneyService -->|"uses"| LoadAccountPort
    SendMoneyService -->|"uses"| UpdateAccountStatePort
    SendMoneyService -->|"uses"| AccountLock

    GetAccountBalanceQuery -->|"executes"| GetAccountBalanceService
    GetAccountBalanceService -->|"uses"| LoadAccountPort

    LoadAccountPort -->|"implemented by"| AccountPersistenceAdapter
    UpdateAccountStatePort -->|"implemented by"| AccountPersistenceAdapter
    AccountLock -->|"implemented by"| NoOpAccountLock

    AccountPersistenceAdapter -->|"maps via"| AccountMapper
    AccountMapper -->|"maps"| AccountJpaEntity
    AccountMapper -->|"maps"| ActivityJpaEntity

    AccountPersistenceAdapter -->|"calls"| SpringDataAccountRepository
    AccountPersistenceAdapter -->|"calls"| ActivityRepository

    SpringDataAccountRepository -->|"reads/writes"| Database
    ActivityRepository -->|"reads/writes"| Database

    %% Infrastructure wiring
    BuckPalApplication --> BuckPalConfiguration
    BuckPalConfiguration --> BuckPalConfigurationProperties
    BuckPalApplication --> SendMoneyController
    BuckPalApplication --> AccountPersistenceAdapter

    %% Click Events
    click Account "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/domain/Account.java"
    click Activity "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/domain/Activity.java"
    click ActivityWindow "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/domain/ActivityWindow.java"
    click Money "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/domain/Money.java"

    click SendMoneyUseCase "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/application/port/in/SendMoneyUseCase.java"
    click GetAccountBalanceQuery "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/application/port/in/GetAccountBalanceQuery.java"
    click SendMoneyCommand "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/application/port/in/SendMoneyCommand.java"

    click LoadAccountPort "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/application/port/out/LoadAccountPort.java"
    click UpdateAccountStatePort "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/application/port/out/UpdateAccountStatePort.java"
    click AccountLock "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/application/port/out/AccountLock.java"

    click SendMoneyService "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/application/service/SendMoneyService.java"
    click GetAccountBalanceService "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/application/service/GetAccountBalanceService.java"
    click MoneyTransferProperties "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/application/service/MoneyTransferProperties.java"
    click NoOpAccountLock "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/application/service/NoOpAccountLock.java"
    click ThresholdExceededException "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/application/service/ThresholdExceededException.java"

    click SendMoneyController "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/adapter/in/web/SendMoneyController.java"

    click AccountPersistenceAdapter "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/adapter/out/persistence/AccountPersistenceAdapter.java"
    click AccountJpaEntity "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/adapter/out/persistence/AccountJpaEntity.java"
    click ActivityJpaEntity "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/adapter/out/persistence/ActivityJpaEntity.java"
    click AccountMapper "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/adapter/out/persistence/AccountMapper.java"
    click SpringDataAccountRepository "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/adapter/out/persistence/SpringDataAccountRepository.java"
    click ActivityRepository "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/account/adapter/out/persistence/ActivityRepository.java"

    click BuckPalApplication "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/BuckPalApplication.java"
    click BuckPalConfiguration "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/BuckPalConfiguration.java"
    click BuckPalConfigurationProperties "https://github.com/wikibook/clean-architecture/blob/main/src/main/java/io/reflectoring/buckpal/BuckPalConfigurationProperties.java"
    click ApplicationYml "https://github.com/wikibook/clean-architecture/blob/main/src/main/resources/application.yml"

    %% Style Definitions
    classDef domain fill:#f9f,stroke:#333,stroke-width:2px
    classDef portin fill:#ff9,stroke:#333,stroke-width:1px
    classDef portout fill:#9ff,stroke:#333,stroke-width:1px
    classDef service fill:#9f9,stroke:#333,stroke-width:1px
    classDef adapterin fill:#fc9,stroke:#333,stroke-width:1px
    classDef adapterout fill:#c9f,stroke:#333,stroke-width:1px
    classDef infra fill:#ccc,stroke:#333,stroke-width:1px
    classDef db fill:#ccf,stroke:#333,stroke-width:1px
```
