# firefly-oss/core-banking-ledger architecture

> Architecture diagram of the GitHub repository firefly-oss/core-banking-ledger, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/firefly-oss/core-banking-ledger
- Repository: https://github.com/firefly-oss/core-banking-ledger

## Overview

Core Banking Ledger is a reactive banking microservice for transaction and related-record CRUD, not financial calculation or payment processing. A client submits transaction requests through the REST API; services manage transaction records and payment-specific details, with status changes tracked as history, while the data layer persists the records. The README also identifies double-entry legs, attachments, and statement generation as product capabilities. Source excerpts confirm the transaction and attachment controller-to-service paths; connections to unsampled service and persistence internals are documented at the module level only.

Main entry points: [`core-banking-ledger-models/src/main/java/com/firefly/core/banking/ledger/models/repositories`](https://github.com/firefly-oss/core-banking-ledger/tree/main/core-banking-ledger-models/src/main/java/com/firefly/core/banking/ledger/models/repositories) (Related Records), [`core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/core/v1/TransactionController.java`](https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/core/v1/TransactionController.java) (Transactions API), [`core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/attachment/v1/TransactionAttachmentController.java`](https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/attachment/v1/TransactionAttachmentController.java) (Attachments API), [`core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/core/v1/TransactionServiceImpl.java`](https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/core/v1/TransactionServiceImpl.java) (Transaction CRUD)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_transactions_api["Transactions API"]
  node_attachments_api["Attachments API"]
  node_payment_apis["Payment Line APIs"]
  node_statements_api["Statements API"]
end

subgraph group_services["Ledger Services"]
  node_transactions["Transaction CRUD"]
  node_attachments["Attachment CRUD"]
  node_payment_lines["Payment Lines"]
  node_status_history["Status History"]
  node_legs["Accounting Legs"]
  node_statements["Statement Generation"]
end

subgraph group_contracts["API Contracts"]
  node_dto["DTO Contracts"]
end

subgraph group_data["Persistence"]
  node_transaction_store[("Ledger Records")]
  node_related_store[("Related Records")]
end

node_client(("API Client"))

node_client -->|"sends requests"| node_transactions_api
node_transactions_api -->|"calls"| node_transactions
node_client -->|"sends requests"| node_attachments_api
node_attachments_api -->|"calls"| node_attachments
node_client -->|"sends requests"| node_payment_apis
node_client -->|"sends requests"| node_statements_api
node_transactions_api -->|"accepts and returns"| node_dto
node_attachments_api -->|"accepts and returns"| node_dto
node_transactions -->|"records status changes"| node_status_history
node_transactions -->|"persists transactions"| node_transaction_store
node_attachments -->|"persists attachments"| node_related_store
node_payment_apis -.->|"delegates CRUD"| node_payment_lines
node_statements_api -.->|"delegates generation"| node_statements
node_payment_lines -->|"persists line records"| node_related_store
node_status_history -->|"persists history"| node_related_store
node_legs -->|"persists legs"| node_related_store
node_statements -.->|"reads ledger data"| node_related_store

click node_transactions_api "https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/core/v1/TransactionController.java"
click node_attachments_api "https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/attachment/v1/TransactionAttachmentController.java"
click node_payment_apis "https://github.com/firefly-oss/core-banking-ledger/tree/main/core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers"
click node_statements_api "https://github.com/firefly-oss/core-banking-ledger/tree/main/core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/statement/v1"
click node_transactions "https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/core/v1/TransactionServiceImpl.java"
click node_attachments "https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/attachment/v1/TransactionAttachmentServiceImpl.java"
click node_payment_lines "https://github.com/firefly-oss/core-banking-ledger/tree/main/core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services"
click node_status_history "https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/core/v1/TransactionStatusHistoryServiceImpl.java"
click node_legs "https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/leg/v1/TransactionLegServiceImpl.java"
click node_statements "https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/statement/v1/StatementServiceImpl.java"
click node_dto "https://github.com/firefly-oss/core-banking-ledger/tree/main/core-banking-ledger-interfaces/src/main/java/com/firefly/core/banking/ledger/interfaces/dtos"
click node_transaction_store "https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-models/src/main/java/com/firefly/core/banking/ledger/models/repositories/core/v1/TransactionRepository.java"
click node_related_store "https://github.com/firefly-oss/core-banking-ledger/tree/main/core-banking-ledger-models/src/main/java/com/firefly/core/banking/ledger/models/repositories"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_transactions_api,node_attachments_api,node_payment_apis,node_statements_api,node_client toneBlue
class node_transactions,node_attachments,node_payment_lines,node_status_history,node_legs,node_statements toneAmber
class node_dto toneMint
class node_transaction_store,node_related_store toneRose
```

## Components

### REST API

- [Transactions API](https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/core/v1/TransactionController.java): `core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/core/v1/TransactionController.java`
- [Attachments API](https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/attachment/v1/TransactionAttachmentController.java): `core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/attachment/v1/TransactionAttachmentController.java`
- [Payment Line APIs](https://github.com/firefly-oss/core-banking-ledger/tree/main/core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers): `core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers`
- [Statements API](https://github.com/firefly-oss/core-banking-ledger/tree/main/core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/statement/v1): `core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/statement/v1`

### Ledger Services

- [Transaction CRUD](https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/core/v1/TransactionServiceImpl.java): `core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/core/v1/TransactionServiceImpl.java`
- [Attachment CRUD](https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/attachment/v1/TransactionAttachmentServiceImpl.java): `core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/attachment/v1/TransactionAttachmentServiceImpl.java`
- [Payment Lines](https://github.com/firefly-oss/core-banking-ledger/tree/main/core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services): `core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services`
- [Status History](https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/core/v1/TransactionStatusHistoryServiceImpl.java): `core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/core/v1/TransactionStatusHistoryServiceImpl.java`
- [Accounting Legs](https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/leg/v1/TransactionLegServiceImpl.java): `core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/leg/v1/TransactionLegServiceImpl.java`
- [Statement Generation](https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/statement/v1/StatementServiceImpl.java): `core-banking-ledger-core/src/main/java/com/firefly/core/banking/ledger/core/services/statement/v1/StatementServiceImpl.java`

### API Contracts

- [DTO Contracts](https://github.com/firefly-oss/core-banking-ledger/tree/main/core-banking-ledger-interfaces/src/main/java/com/firefly/core/banking/ledger/interfaces/dtos): `core-banking-ledger-interfaces/src/main/java/com/firefly/core/banking/ledger/interfaces/dtos`

### Persistence

- [Ledger Records](https://github.com/firefly-oss/core-banking-ledger/blob/main/core-banking-ledger-models/src/main/java/com/firefly/core/banking/ledger/models/repositories/core/v1/TransactionRepository.java): `core-banking-ledger-models/src/main/java/com/firefly/core/banking/ledger/models/repositories/core/v1/TransactionRepository.java`
- [Related Records](https://github.com/firefly-oss/core-banking-ledger/tree/main/core-banking-ledger-models/src/main/java/com/firefly/core/banking/ledger/models/repositories): `core-banking-ledger-models/src/main/java/com/firefly/core/banking/ledger/models/repositories`

### Other components

- **API Client**

## Connections

- API Client → Transactions API: sends requests (evidence: `README.md`)
- Transactions API → Transaction CRUD: calls (evidence: `core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/core/v1/TransactionController.java`)
- API Client → Attachments API: sends requests (evidence: `README.md`)
- Attachments API → Attachment CRUD: calls (evidence: `core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/attachment/v1/TransactionAttachmentController.java`)
- API Client → Payment Line APIs: sends requests (evidence: `README.md`)
- API Client → Statements API: sends requests (evidence: `README.md`)
- Transactions API → DTO Contracts: accepts and returns (evidence: `core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/core/v1/TransactionController.java`)
- Attachments API → DTO Contracts: accepts and returns (evidence: `core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/attachment/v1/TransactionAttachmentController.java`)
- Transaction CRUD → Status History: records status changes
- Transaction CRUD → Ledger Records: persists transactions (evidence: `README.md`)
- Attachment CRUD → Related Records: persists attachments (evidence: `README.md`)
- Payment Line APIs → Payment Lines: delegates CRUD (evidence: `core-banking-ledger-web/src/main/java/com/firefly/core/banking/ledger/web/controllers/core/v1/TransactionController.java`)
- Statements API → Statement Generation: delegates generation
- Payment Lines → Related Records: persists line records (evidence: `README.md`)
- Status History → Related Records: persists history (evidence: `README.md`)
- Accounting Legs → Related Records: persists legs (evidence: `README.md`)
- Statement Generation → Related Records: reads ledger data
