# alirezamohamadian1998/neobank architecture

> Architecture diagram of the GitHub repository alirezamohamadian1998/neobank, 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/alirezamohamadian1998/neobank
- Repository: https://github.com/alirezamohamadian1998/neobank

## Overview

NeoBank is a Spring Boot banking backend. Its core user-to-result flow is authenticated customer money movement: deposit, withdrawal, or transfer services validate and coordinate a request, optionally use a cached FX-rate lock, post balanced ledger entries, and record idempotency results. Account/customer management, debit-card issuing, FX-rate lookup, and transaction history are distinct product capabilities. Source excerpts show the money-movement and ledger boundaries; several other branches are represented from the README and file tree, so their internal calls are not inferred.

Main entry points: [`src/main/java/com/neobank/neobank/transaction/deposit/DepositService.java`](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/transaction/deposit/DepositService.java) (Deposits), [`src/main/java/com/neobank/neobank/transaction/withdrawal/WithdrawalService.java`](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/transaction/withdrawal/WithdrawalService.java) (Withdrawals), [`src/main/java/com/neobank/neobank/transaction/transfer/TransferService.java`](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/transaction/transfer/TransferService.java) (Transfers), [`src/main/java/com/neobank/neobank/ledger/LedgerPostingService.java`](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/ledger/LedgerPostingService.java) (Ledger posting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and customers"]
  node_customer["Customer management"]
  node_auth["JWT authentication<br/>[AuthService.java]"]
end

subgraph group_banking["Accounts and cards"]
  node_account["Account management"]
  node_account_store[("Accounts and balances<br/>[Account.java]")]
  node_cards["Debit cards"]
  node_card_issuer["Card issuer"]
end

subgraph group_movement["Money movement"]
  node_deposit["Deposits"]
  node_withdrawal["Withdrawals"]
  node_transfer["Transfers"]
  node_history["Transaction history"]
  node_idempotency["Idempotency"]
  node_idempotency_store[("Idempotency records")]
end

subgraph group_ledger["Ledger and persistence"]
  node_ledger_post["Ledger posting"]
  node_ledger_account[("Ledger accounts<br/>[LedgerAccount.java]")]
  node_bank_tx[("Bank transactions")]
  node_internal_accounts[("Settlement accounts")]
end

subgraph group_rates["FX rates"]
  node_fx_service["FX rate locks<br/>[FxRateService.java]"]
  node_fx_cache[("Rate caches")]
  node_fx_provider["Rates integration"]
end

node_customer_actor(("Customer"))
node_fx_vendor["Open Exchange Rates"]

node_customer_actor -->|"registers"| node_customer
node_customer_actor -->|"logs in"| node_auth
node_customer_actor -->|"manages accounts"| node_account
node_customer_actor -->|"requests deposit"| node_deposit
node_customer_actor -->|"requests withdrawal"| node_withdrawal
node_customer_actor -->|"requests transfer"| node_transfer
node_customer_actor -.->|"views history"| node_history
node_customer_actor -.->|"manages cards"| node_cards
node_account -->|"creates and reads"| node_account_store
node_cards -->|"loads funding account"| node_account_store
node_cards -->|"issues card"| node_card_issuer
node_deposit -->|"loads account"| node_account_store
node_withdrawal -->|"loads account"| node_account_store
node_transfer -->|"loads accounts"| node_account_store
node_deposit -->|"gets locked rates"| node_fx_service
node_withdrawal -->|"gets locked rates"| node_fx_service
node_transfer -->|"gets locked rates"| node_fx_service
node_fx_service -->|"reads and stores rates"| node_fx_cache
node_fx_vendor -.->|"supplies rates"| node_fx_provider
node_fx_provider -.->|"provides cached rates"| node_fx_cache
node_deposit -->|"posts entries"| node_ledger_post
node_withdrawal -->|"posts entries"| node_ledger_post
node_transfer -->|"posts entries"| node_ledger_post
node_deposit -->|"loads settlement account"| node_internal_accounts
node_withdrawal -->|"loads settlement account"| node_internal_accounts
node_ledger_post -->|"updates balance"| node_ledger_account
node_ledger_post -->|"adds entry"| node_bank_tx
node_deposit -->|"completes transaction"| node_bank_tx
node_withdrawal -->|"completes transaction"| node_bank_tx
node_transfer -->|"completes transaction"| node_bank_tx
node_deposit -->|"checks and saves key"| node_idempotency
node_withdrawal -->|"checks and saves key"| node_idempotency
node_transfer -->|"checks and saves key"| node_idempotency
node_idempotency -->|"reads and writes"| node_idempotency_store
node_history -.->|"reads transactions"| node_bank_tx

click node_customer "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/customer/CustomerService.java"
click node_auth "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/auth/AuthService.java"
click node_account "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/account/AccountService.java"
click node_account_store "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/account/Account.java"
click node_cards "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/card/DebitCardService.java"
click node_card_issuer "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/card/issuing/DebitCardIssuer.java"
click node_deposit "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/transaction/deposit/DepositService.java"
click node_withdrawal "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/transaction/withdrawal/WithdrawalService.java"
click node_transfer "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/transaction/transfer/TransferService.java"
click node_history "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/transaction/history/TransactionHistoryService.java"
click node_idempotency "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/idempotency/IdempotencyService.java"
click node_idempotency_store "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/idempotency/IdempotencyRecord.java"
click node_fx_service "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/fx/FxRateService.java"
click node_fx_cache "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/fx/ProviderRateCache.java"
click node_fx_provider "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/fx/openexchangerates/OpenExchangeRatesClient.java"
click node_ledger_post "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/ledger/LedgerPostingService.java"
click node_ledger_account "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/ledger/LedgerAccount.java"
click node_bank_tx "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/transaction/BankTransaction.java"
click node_internal_accounts "https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/internalaccount/InternalAccount.java"

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_customer,node_auth toneBlue
class node_account,node_account_store,node_cards,node_card_issuer toneAmber
class node_deposit,node_withdrawal,node_transfer,node_history,node_idempotency,node_idempotency_store toneMint
class node_ledger_post,node_ledger_account,node_bank_tx,node_internal_accounts toneRose
class node_fx_service,node_fx_cache,node_fx_provider,node_customer_actor,node_fx_vendor toneIndigo
```

## Components

### Identity and customers

- [Customer management](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/customer/CustomerService.java): `src/main/java/com/neobank/neobank/customer/CustomerService.java`
- [JWT authentication](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/auth/AuthService.java): `src/main/java/com/neobank/neobank/auth/AuthService.java`

### Accounts and cards

- [Account management](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/account/AccountService.java): `src/main/java/com/neobank/neobank/account/AccountService.java`
- [Accounts and balances](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/account/Account.java): `src/main/java/com/neobank/neobank/account/Account.java`
- [Debit cards](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/card/DebitCardService.java): `src/main/java/com/neobank/neobank/card/DebitCardService.java`
- [Card issuer](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/card/issuing/DebitCardIssuer.java): `src/main/java/com/neobank/neobank/card/issuing/DebitCardIssuer.java`

### Money movement

- [Deposits](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/transaction/deposit/DepositService.java): `src/main/java/com/neobank/neobank/transaction/deposit/DepositService.java`
- [Withdrawals](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/transaction/withdrawal/WithdrawalService.java): `src/main/java/com/neobank/neobank/transaction/withdrawal/WithdrawalService.java`
- [Transfers](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/transaction/transfer/TransferService.java): `src/main/java/com/neobank/neobank/transaction/transfer/TransferService.java`
- [Transaction history](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/transaction/history/TransactionHistoryService.java): `src/main/java/com/neobank/neobank/transaction/history/TransactionHistoryService.java`
- [Idempotency](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/idempotency/IdempotencyService.java): `src/main/java/com/neobank/neobank/idempotency/IdempotencyService.java`
- [Idempotency records](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/idempotency/IdempotencyRecord.java): `src/main/java/com/neobank/neobank/idempotency/IdempotencyRecord.java`

### Ledger and persistence

- [Ledger posting](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/ledger/LedgerPostingService.java): `src/main/java/com/neobank/neobank/ledger/LedgerPostingService.java`
- [Ledger accounts](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/ledger/LedgerAccount.java): `src/main/java/com/neobank/neobank/ledger/LedgerAccount.java`
- [Bank transactions](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/transaction/BankTransaction.java): `src/main/java/com/neobank/neobank/transaction/BankTransaction.java`
- [Settlement accounts](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/internalaccount/InternalAccount.java): `src/main/java/com/neobank/neobank/internalaccount/InternalAccount.java`

### FX rates

- [FX rate locks](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/fx/FxRateService.java): `src/main/java/com/neobank/neobank/fx/FxRateService.java`
- [Rate caches](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/fx/ProviderRateCache.java): `src/main/java/com/neobank/neobank/fx/ProviderRateCache.java`
- [Rates integration](https://github.com/alirezamohamadian1998/neobank/blob/main/src/main/java/com/neobank/neobank/fx/openexchangerates/OpenExchangeRatesClient.java): `src/main/java/com/neobank/neobank/fx/openexchangerates/OpenExchangeRatesClient.java`

### Other components

- **Customer**
- **Open Exchange Rates**

## Connections

- Customer → Customer management: registers (evidence: `README.md`)
- Customer → JWT authentication: logs in (evidence: `README.md`)
- Customer → Account management: manages accounts (evidence: `README.md`)
- Customer → Deposits: requests deposit (evidence: `README.md`)
- Customer → Withdrawals: requests withdrawal (evidence: `README.md`)
- Customer → Transfers: requests transfer (evidence: `README.md`)
- Customer → Transaction history: views history
- Customer → Debit cards: manages cards
- Account management → Accounts and balances: creates and reads (evidence: `src/main/java/com/neobank/neobank/account/AccountService.java`)
- Debit cards → Accounts and balances: loads funding account (evidence: `src/main/java/com/neobank/neobank/card/DebitCardService.java`)
- Debit cards → Card issuer: issues card (evidence: `src/main/java/com/neobank/neobank/card/DebitCardService.java`)
- Deposits → Accounts and balances: loads account (evidence: `src/main/java/com/neobank/neobank/transaction/deposit/DepositService.java`)
- Withdrawals → Accounts and balances: loads account (evidence: `src/main/java/com/neobank/neobank/transaction/withdrawal/WithdrawalService.java`)
- Transfers → Accounts and balances: loads accounts (evidence: `src/main/java/com/neobank/neobank/transaction/transfer/TransferService.java`)
- Deposits → FX rate locks: gets locked rates (evidence: `src/main/java/com/neobank/neobank/transaction/deposit/DepositService.java`)
- Withdrawals → FX rate locks: gets locked rates (evidence: `src/main/java/com/neobank/neobank/transaction/withdrawal/WithdrawalService.java`)
- Transfers → FX rate locks: gets locked rates (evidence: `src/main/java/com/neobank/neobank/transaction/transfer/TransferService.java`)
- FX rate locks → Rate caches: reads and stores rates (evidence: `src/main/java/com/neobank/neobank/fx/FxRateService.java`)
- Open Exchange Rates → Rates integration: supplies rates (evidence: `README.md`)
- Rates integration → Rate caches: provides cached rates
- Deposits → Ledger posting: posts entries (evidence: `src/main/java/com/neobank/neobank/transaction/deposit/DepositService.java`)
- Withdrawals → Ledger posting: posts entries (evidence: `src/main/java/com/neobank/neobank/transaction/withdrawal/WithdrawalService.java`)
- Transfers → Ledger posting: posts entries (evidence: `src/main/java/com/neobank/neobank/transaction/transfer/TransferService.java`)
- Deposits → Settlement accounts: loads settlement account (evidence: `src/main/java/com/neobank/neobank/transaction/deposit/DepositService.java`)
- Withdrawals → Settlement accounts: loads settlement account (evidence: `src/main/java/com/neobank/neobank/transaction/withdrawal/WithdrawalService.java`)
- Ledger posting → Ledger accounts: updates balance (evidence: `src/main/java/com/neobank/neobank/ledger/LedgerPostingService.java`)
- Ledger posting → Bank transactions: adds entry (evidence: `src/main/java/com/neobank/neobank/ledger/LedgerPostingService.java`)
- Deposits → Bank transactions: completes transaction (evidence: `README.md`)
- Withdrawals → Bank transactions: completes transaction (evidence: `README.md`)
- Transfers → Bank transactions: completes transaction (evidence: `README.md`)
- Deposits → Idempotency: checks and saves key (evidence: `src/main/java/com/neobank/neobank/transaction/deposit/DepositService.java`)
- Withdrawals → Idempotency: checks and saves key (evidence: `src/main/java/com/neobank/neobank/transaction/withdrawal/WithdrawalService.java`)
- Transfers → Idempotency: checks and saves key (evidence: `src/main/java/com/neobank/neobank/transaction/transfer/TransferService.java`)
- Idempotency → Idempotency records: reads and writes (evidence: `src/main/java/com/neobank/neobank/idempotency/IdempotencyService.java`)
- Transaction history → Bank transactions: reads transactions
