How adorsys/ledgers works
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