# adorsys/ledgers architecture

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

- Interactive diagram: https://gitdiagram.com/adorsys/ledgers
- Repository: https://github.com/adorsys/ledgers

## Overview

##### Project Type and Purpose
- This is a modular, Spring-based banking booking system (“Ledgers”) provided as a monorepo of interdependent modules and microservices.
- Core domains: Deposit Account, Double-Entry Accounting (Postings), Strong Customer Authentication (SCA), User Management, plus a REST-based Middleware layer, an example application (“ledgers-app”), Keycloak integrations, and DevOps deployment artifacts.

##### File-Structure Overview
- Top-level: application runner (“ledgers-app”), cleanup service, DB migration module (Liquibase), Keycloak client & extensions, utility libraries, plus multi-module packages under “ledgers-deposit-account”, “ledgers-postings”, “ledgers-sca”, “ledgers-user-management”, “ledgers-middleware”.
- Each domain is split into:
- repository (JPA entities & Spring Data)
- service-api (domain interfaces and DTOs)
- service-impl (business logic)
- rest-server (Spring-boot REST controllers)
- rest-client (Feign clients for intra-service calls)
- DevOps: Helm charts (backend + Postgres), Dockerfiles, CI workflows (GitHub Actions, GitLab CI).

##### Key README Insights
- Domain features: account creation, payment initiation, journal entries with hash chains, asynchronous closing, SCA workflows.
- Modules are pluggable via Spring annotations (`@EnableDepositAccountService`, etc.).
- Authentication via Keycloak (OAuth2/JWT), example theme, token exchange.
- Single database (Postgres in prod, H2 for dev), schema migrations via Liquibase.

a. Main Components
- External Clients (Browsers, Mobile Apps, Swagger UI)
- Keycloak Identity Provider
- Ledgers-App (Demo Spring Boot application)
- Middleware REST Server (aggregates domain services into HTTP APIs)
- Domain Service Modules (Deposit Account, Postings, SCA, User Management)
- JPA Repositories (each domain’s database layer)
- Database (Postgres/H2)
- External Services: Exchange-Rate API, SMTP (for SCA), Cleanup Scheduler
- DevOps Platform (Kubernetes/Helm, CI/CD)

b. Relationships & Data Flows
- Clients → (HTTPS + JWT) → Middleware REST Server
- REST Server → Service-API (calls into service-impl modules)
- Service-impl → JPA Repositories → Database
- Service modules → External services (e.g., Feign-based ExchangeRateClient)
- SCA Module ↔ SMTP or push providers
- Cleanup Service → Scheduled direct DB calls (SQL scripts)
- Keycloak → OAuth2 token issuance, introspection for JWT auth

c. Architectural Patterns & Principles
- Layered architecture: API layer / Service layer / Data layer
- Modular monorepo with Spring’s `@EnableXxx` approach for pluggable modules
- Microservices style separation (REST servers & clients)
- Shared relational database with per-module schema migrations
- Eventual consistency for postings partitioning
- Double-entry accounting with hash chains for integrity

d. Key Technologies & Frameworks
- Java 17, Spring Boot, Spring Data JPA, Feign clients
- Liquibase (DB migrations), H2 (dev), Postgres (prod)
- Keycloak for OAuth2 / JWT
- Docker, Helm charts, Kubernetes
- Maven multi-module build, GitHub Actions / GitLab CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Layer
    subgraph "External Clients" 
        direction TB
        Browser(["Browser/Mobile App"]):::external
        SwaggerUI(["Swagger UI"]):::external
    end

    subgraph "Authentication" 
        direction TB
        KeycloakIDP(["Keycloak Identity Provider"]):::auth
    end

    %% Application Layer
    subgraph "Demo Application"
        direction TB
        LedgersApp(["ledgers-app"]):::app
    end

    subgraph "Middleware Layer"
        direction TB
        MW_REST_Server(["Middleware REST Server"]):::api
        MW_REST_Client(["Middleware REST Client (Feign)"]):::service
        MW_Service_API(["Middleware Service API"]):::service
        MW_Service_Impl(["Middleware Service Impl"]):::service
    end

    %% Domain Services
    subgraph "Domain Services"
        direction TB

        subgraph "Deposit Account"
            direction TB
            Dep_Repo(["DepositAccountRepository"]):::db
            Dep_API(["DepositAccountServiceAPI"]):::service
            Dep_Impl(["DepositAccountServiceImpl"]):::service
        end

        subgraph "Postings"
            direction TB
            Post_Repo(["PostingsRepository"]):::db
            Post_API(["PostingsServiceAPI"]):::service
            Post_Impl(["PostingsServiceImpl"]):::service
            Post_REST(["Postings REST Server"]):::api
        end

        subgraph "SCA"
            direction TB
            SCA_Repo(["SCA Repository"]):::db
            SCA_API(["SCA Service API"]):::service
            SCA_Impl(["SCA Service Impl"]):::service
        end

        subgraph "User Management"
            direction TB
            UM_Repo(["UserMgmt Repository"]):::db
            UM_API(["UserMgmt Service API"]):::service
            UM_Impl(["UserMgmt Service Impl"]):::service
            UM_REST(["UserMgmt REST Server"]):::api
        end
    end

    %% Persistence
    Database(["Postgres / H2 Database"]):::database

    %% External Integrations
    subgraph "External Services"
        direction TB
        ExchangeAPI(["Exchange-Rate API"]):::external
        SMTP(["SMTP / Push Provider"]):::external
    end

    CleanupService(["Cleanup Scheduler Service"]):::infra

    %% DevOps
    subgraph "DevOps"
        direction TB
        HelmCharts(["Helm Charts"]):::infra
        DockerfileNode(["Dockerfile"]):::infra
        CICD(["CI/CD Workflows"]):::infra
        Liquibase(["Liquibase DB Migration"]):::infra
    end

    %% Connections
    Browser -->|"HTTPS + JWT"| MW_REST_Server
    SwaggerUI -->|"HTTPS + JWT"| MW_REST_Server

    MW_REST_Server -->|"calls API"| MW_Service_API
    MW_Service_API -->|"invokes"| MW_Service_Impl
    MW_Service_Impl -->|"Feign"| MW_REST_Client
    MW_REST_Client -->|"HTTP"| Dep_API
    MW_REST_Client -->|"HTTP"| Post_API
    MW_REST_Client -->|"HTTP"| SCA_API
    MW_REST_Client -->|"HTTP"| UM_API

    Dep_API -->|"executes"| Dep_Impl
    Dep_Impl -->|"JPA / JDBC"| Dep_Repo
    Dep_Repo -->|"reads/writes"| Database

    Post_API -->|"executes"| Post_Impl
    Post_Impl -->|"JPA / JDBC"| Post_Repo
    Post_Repo -->|"reads/writes"| Database
    Post_REST -->|"controllers call"| Post_API

    SCA_API -->|"executes"| SCA_Impl
    SCA_Impl -->|"JPA / JDBC"| SCA_Repo
    SCA_Repo -->|"reads/writes"| Database
    SCA_Impl -->|"SMTP / Push"| SMTP

    UM_API -->|"executes"| UM_Impl
    UM_Impl -->|"JPA / JDBC"| UM_Repo
    UM_Repo -->|"reads/writes"| Database
    UM_REST -->|"controllers call"| UM_API

    MW_REST_Server -->|"auth via OAuth2"| KeycloakIDP
    LedgersApp -->|"uses REST APIs"| MW_REST_Server

    KeycloakIDP -->|"issues tokens"| Browser
    KeycloakIDP -->|"introspects JWT"| MW_REST_Server

    ExchangeAPI -->|"Feign"| Post_Impl

    CleanupService -->|"direct SQL"| Database

    Liquibase -->|"migrates schema"| Database
    HelmCharts -->|"deploy"| MW_REST_Server
    HelmCharts -->|"deploy"| Database

    DockerfileNode -->|"build image"| MW_REST_Server
    CICD -->|"runs workflows"| DockerfileNode

    %% Click Events
    click KeycloakIDP "https://github.com/adorsys/ledgers/tree/develop/keycloak/keycloak-client/"
    click LedgersApp "https://github.com/adorsys/ledgers/tree/develop/ledgers-app/"
    click MW_REST_Server "https://github.com/adorsys/ledgers/tree/develop/ledgers-middleware/ledgers-middleware-rest-server/"
    click MW_REST_Client "https://github.com/adorsys/ledgers/tree/develop/ledgers-middleware/ledgers-middleware-rest-client/"
    click MW_Service_API "https://github.com/adorsys/ledgers/tree/develop/ledgers-middleware/ledgers-middleware-service-api/"
    click MW_Service_Impl "https://github.com/adorsys/ledgers/tree/develop/ledgers-middleware/ledgers-middleware-service-impl/"
    click Dep_Repo "https://github.com/adorsys/ledgers/tree/develop/ledgers-deposit-account/ledgers-deposit-account-repository/"
    click Dep_API "https://github.com/adorsys/ledgers/tree/develop/ledgers-deposit-account/ledgers-deposit-account-service-api/"
    click Dep_Impl "https://github.com/adorsys/ledgers/tree/develop/ledgers-deposit-account/ledgers-deposit-account-service-impl/"
    click Post_Repo "https://github.com/adorsys/ledgers/tree/develop/ledgers-postings/ledgers-postings-repository/"
    click Post_API "https://github.com/adorsys/ledgers/tree/develop/ledgers-postings/ledgers-postings-service-api/"
    click Post_Impl "https://github.com/adorsys/ledgers/tree/develop/ledgers-postings/ledgers-postings-service-impl/"
    click Post_REST "https://github.com/adorsys/ledgers/tree/develop/ledgers-postings/ledgers-postings-rest-server/"
    click SCA_Repo "https://github.com/adorsys/ledgers/tree/develop/ledgers-sca/ledgers-sca-repository/"
    click SCA_API "https://github.com/adorsys/ledgers/tree/develop/ledgers-sca/ledgers-sca-service-api/"
    click SCA_Impl "https://github.com/adorsys/ledgers/tree/develop/ledgers-sca/ledgers-sca-service-impl/"
    click UM_Repo "https://github.com/adorsys/ledgers/tree/develop/ledgers-user-management/ledgers-user-management-repository/"
    click UM_API "https://github.com/adorsys/ledgers/tree/develop/ledgers-user-management/ledgers-user-management-service-api/"
    click UM_Impl "https://github.com/adorsys/ledgers/tree/develop/ledgers-user-management/ledgers-user-management-service-impl/"
    click UM_REST "https://github.com/adorsys/ledgers/tree/develop/ledgers-user-management/ledgers-user-management-rest-server/"
    click CleanupService "https://github.com/adorsys/ledgers/tree/develop/ledgers-cleanup-service/"
    click Liquibase "https://github.com/adorsys/ledgers/tree/develop/ledgers-db/"
    click HelmCharts "https://github.com/adorsys/ledgers/tree/develop/devOps/charts/ledgers/"
    click DockerfileNode "https://github.com/adorsys/ledgers/tree/develop/Dockerfile"
    click CICD "https://github.com/adorsys/ledgers/tree/develop/.github/workflows/"
    
    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef auth fill:#ffb,stroke:#333,stroke-width:1px
    classDef app fill:#bbf,stroke:#333,stroke-width:1px
    classDef api fill:#bfb,stroke:#333,stroke-width:1px
    classDef service fill:#fbf,stroke:#333,stroke-width:1px
    classDef db fill:#ffd,stroke:#333,stroke-width:1px
    classDef database fill:#ffe,stroke:#333,stroke-width:1px
    classDef infra fill:#dfd,stroke:#333,stroke-width:1px
```
