# hanzunii/ubx-banking-system architecture

> Architecture diagram of the GitHub repository hanzunii/ubx-banking-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hanzunii/ubx-banking-system
- Repository: https://github.com/hanzunii/ubx-banking-system

## Overview

UBX Banking is a distributed banking system: users and administrators act through web, Android, or desktop clients; the gateway handles REST, sessions, and real-time updates; and the RMI core performs banking operations against its database. The README documents discovery, MFA, idempotent transfers, and live balance pushes. Legacy `atm-server` is a separate, superseded implementation. Some client and core subsystems are represented by their exact source directories because their implementation files were not sampled.

Main entry points: [`api-gateway/src/main/java/com/atm/gateway/controller/GatewayController.java`](https://github.com/hanzunii/ubx-banking-system/blob/main/api-gateway/src/main/java/com/atm/gateway/controller/GatewayController.java) (REST controller), [`rmi-server/src/main/java/com/atm/rmi/server/RmiBridgeController.java`](https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/server/RmiBridgeController.java) (RMI bridge endpoints), [`atm-android/app/src/main/java/com/atm/mobile/network/ApiClient.java`](https://github.com/hanzunii/ubx-banking-system/blob/main/atm-android/app/src/main/java/com/atm/mobile/network/ApiClient.java) (Android API client), [`rmi-server/src/main/java/com/atm/rmi/service/TransactionServiceImpl.java`](https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/service/TransactionServiceImpl.java) (Transactions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client applications"]
  node_web["Web banking"]
  node_webapp["Web routing and auth<br/>[App.jsx]"]
  node_android["Android banking"]
  node_androidapi["Android API client<br/>[ApiClient.java]"]
  node_discovery["Gateway discovery"]
  node_desktop["Admin console"]
  node_adminservice["Admin API client<br/>[AdminService.java]"]
end

subgraph group_gateway["API gateway"]
  node_gatewayapi["REST controller"]
  node_gatewayauth["JWT and security<br/>[JwtUtil.java]"]
  node_idempotency["Transfer idempotency"]
  node_rmiadapter["RMI banking adapter"]
  node_realtime["Live balance push"]
  node_ws["Account WebSocket"]
  node_discoveryserver["UDP discovery responder"]
end

subgraph group_core["RMI banking core"]
  node_rmihttp["RMI bridge endpoints"]
  node_auth["Authentication and MFA"]
  node_account["Account operations"]
  node_transactions["Transactions"]
  node_adminops["Account administration"]
end

subgraph group_storage["Core persistence"]
  node_customerrepo[("Customer records")]
  node_txnrepo[("Transaction records")]
end

subgraph group_legacy["Legacy server"]
  node_legacyauth["Legacy authentication<br/>[AuthService.java]"]
  node_legacybank["Legacy banking operations"]
  node_legacyaccountapi["Legacy account endpoints"]
  node_legacyauthapi["Legacy auth endpoints"]
  node_legacydb[("Legacy data store")]
end

node_user(("Bank user"))
node_admin(("System admin"))

node_user -->|"uses"| node_web
node_user -->|"uses"| node_android
node_admin -->|"uses"| node_desktop
node_webapp -->|"routes to"| node_web
node_web -->|"sends REST"| node_gatewayapi
node_android -->|"requests through"| node_androidapi
node_androidapi -->|"sends REST"| node_gatewayapi
node_androidapi -->|"resolves server"| node_discovery
node_discovery -->|"probes"| node_discoveryserver
node_desktop -->|"uses"| node_adminservice
node_adminservice -->|"calls REST"| node_gatewayapi
node_gatewayapi -->|"issues tokens"| node_gatewayauth
node_gatewayapi -->|"records results"| node_idempotency
node_gatewayapi -->|"invokes banking"| node_rmiadapter
node_gatewayapi -->|"pushes updates"| node_realtime
node_ws -.->|"delivers updates"| node_realtime
node_gatewayapi -->|"calls RMI services"| node_rmihttp
node_rmihttp -->|"delegates auth"| node_auth
node_rmihttp -->|"delegates account"| node_account
node_rmihttp -->|"delegates transfers"| node_transactions
node_rmihttp -->|"delegates admin"| node_adminops
node_auth -->|"reads and writes"| node_customerrepo
node_transactions -.->|"updates balances"| node_customerrepo
node_transactions -.->|"stores transactions"| node_txnrepo
node_adminops -.->|"manages accounts"| node_customerrepo
node_legacyauthapi -->|"delegates auth"| node_legacyauth
node_legacyaccountapi -->|"delegates banking"| node_legacybank
node_legacyauth -.->|"uses persistence"| node_legacydb
node_legacybank -.->|"uses persistence"| node_legacydb

click node_web "https://github.com/hanzunii/ubx-banking-system/tree/main/web-app/src/pages"
click node_webapp "https://github.com/hanzunii/ubx-banking-system/blob/main/web-app/src/App.jsx"
click node_android "https://github.com/hanzunii/ubx-banking-system/tree/main/atm-android/app/src/main/java/com/atm/mobile/ui"
click node_androidapi "https://github.com/hanzunii/ubx-banking-system/blob/main/atm-android/app/src/main/java/com/atm/mobile/network/ApiClient.java"
click node_discovery "https://github.com/hanzunii/ubx-banking-system/blob/main/atm-android/app/src/main/java/com/atm/mobile/network/ServerDiscovery.java"
click node_desktop "https://github.com/hanzunii/ubx-banking-system/blob/main/admin-desktop/src/main/java/com/atm/admin/DashboardFrame.java"
click node_adminservice "https://github.com/hanzunii/ubx-banking-system/blob/main/admin-desktop/src/main/java/com/atm/admin/AdminService.java"
click node_gatewayapi "https://github.com/hanzunii/ubx-banking-system/blob/main/api-gateway/src/main/java/com/atm/gateway/controller/GatewayController.java"
click node_gatewayauth "https://github.com/hanzunii/ubx-banking-system/blob/main/api-gateway/src/main/java/com/atm/gateway/security/JwtUtil.java"
click node_idempotency "https://github.com/hanzunii/ubx-banking-system/blob/main/api-gateway/src/main/java/com/atm/gateway/service/IdempotencyService.java"
click node_rmiadapter "https://github.com/hanzunii/ubx-banking-system/blob/main/api-gateway/src/main/java/com/atm/gateway/service/RmiBankingService.java"
click node_realtime "https://github.com/hanzunii/ubx-banking-system/blob/main/api-gateway/src/main/java/com/atm/gateway/service/RealtimePusher.java"
click node_ws "https://github.com/hanzunii/ubx-banking-system/blob/main/api-gateway/src/main/java/com/atm/gateway/websocket/AccountSocketHandler.java"
click node_discoveryserver "https://github.com/hanzunii/ubx-banking-system/blob/main/api-gateway/src/main/java/com/atm/gateway/service/DiscoveryResponder.java"
click node_rmihttp "https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/server/RmiBridgeController.java"
click node_auth "https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/service/AuthServiceImpl.java"
click node_account "https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/service/AccountServiceImpl.java"
click node_transactions "https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/service/TransactionServiceImpl.java"
click node_adminops "https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/service/AdminServiceImpl.java"
click node_customerrepo "https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/repository/CustomerRepository.java"
click node_txnrepo "https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/repository/TransactionRepository.java"
click node_legacyauth "https://github.com/hanzunii/ubx-banking-system/blob/main/atm-server/src/main/java/com/atm/server/service/AuthService.java"
click node_legacybank "https://github.com/hanzunii/ubx-banking-system/blob/main/atm-server/src/main/java/com/atm/server/service/BankingService.java"
click node_legacyaccountapi "https://github.com/hanzunii/ubx-banking-system/blob/main/atm-server/src/main/java/com/atm/server/controller/AccountController.java"
click node_legacyauthapi "https://github.com/hanzunii/ubx-banking-system/blob/main/atm-server/src/main/java/com/atm/server/controller/AuthController.java"
click node_legacydb "https://github.com/hanzunii/ubx-banking-system/blob/main/atm-server/src/main/java/com/atm/server/DatabaseManager.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_web,node_webapp,node_android,node_androidapi,node_discovery,node_desktop,node_adminservice,node_user toneBlue
class node_gatewayapi,node_gatewayauth,node_idempotency,node_rmiadapter,node_realtime,node_ws,node_discoveryserver toneAmber
class node_rmihttp,node_auth,node_account,node_transactions,node_adminops toneMint
class node_customerrepo,node_txnrepo toneRose
class node_legacyauth,node_legacybank,node_legacyaccountapi,node_legacyauthapi,node_legacydb,node_admin toneIndigo
```

## Components

### Client applications

- [Web banking](https://github.com/hanzunii/ubx-banking-system/tree/main/web-app/src/pages): `web-app/src/pages`
- [Web routing and auth](https://github.com/hanzunii/ubx-banking-system/blob/main/web-app/src/App.jsx): `web-app/src/App.jsx`
- [Android banking](https://github.com/hanzunii/ubx-banking-system/tree/main/atm-android/app/src/main/java/com/atm/mobile/ui): `atm-android/app/src/main/java/com/atm/mobile/ui`
- [Android API client](https://github.com/hanzunii/ubx-banking-system/blob/main/atm-android/app/src/main/java/com/atm/mobile/network/ApiClient.java): `atm-android/app/src/main/java/com/atm/mobile/network/ApiClient.java`
- [Gateway discovery](https://github.com/hanzunii/ubx-banking-system/blob/main/atm-android/app/src/main/java/com/atm/mobile/network/ServerDiscovery.java): `atm-android/app/src/main/java/com/atm/mobile/network/ServerDiscovery.java`
- [Admin console](https://github.com/hanzunii/ubx-banking-system/blob/main/admin-desktop/src/main/java/com/atm/admin/DashboardFrame.java): `admin-desktop/src/main/java/com/atm/admin/DashboardFrame.java`
- [Admin API client](https://github.com/hanzunii/ubx-banking-system/blob/main/admin-desktop/src/main/java/com/atm/admin/AdminService.java): `admin-desktop/src/main/java/com/atm/admin/AdminService.java`

### API gateway

- [REST controller](https://github.com/hanzunii/ubx-banking-system/blob/main/api-gateway/src/main/java/com/atm/gateway/controller/GatewayController.java): `api-gateway/src/main/java/com/atm/gateway/controller/GatewayController.java`
- [JWT and security](https://github.com/hanzunii/ubx-banking-system/blob/main/api-gateway/src/main/java/com/atm/gateway/security/JwtUtil.java): `api-gateway/src/main/java/com/atm/gateway/security/JwtUtil.java`
- [Transfer idempotency](https://github.com/hanzunii/ubx-banking-system/blob/main/api-gateway/src/main/java/com/atm/gateway/service/IdempotencyService.java): `api-gateway/src/main/java/com/atm/gateway/service/IdempotencyService.java`
- [RMI banking adapter](https://github.com/hanzunii/ubx-banking-system/blob/main/api-gateway/src/main/java/com/atm/gateway/service/RmiBankingService.java): `api-gateway/src/main/java/com/atm/gateway/service/RmiBankingService.java`
- [Live balance push](https://github.com/hanzunii/ubx-banking-system/blob/main/api-gateway/src/main/java/com/atm/gateway/service/RealtimePusher.java): `api-gateway/src/main/java/com/atm/gateway/service/RealtimePusher.java`
- [Account WebSocket](https://github.com/hanzunii/ubx-banking-system/blob/main/api-gateway/src/main/java/com/atm/gateway/websocket/AccountSocketHandler.java): `api-gateway/src/main/java/com/atm/gateway/websocket/AccountSocketHandler.java`
- [UDP discovery responder](https://github.com/hanzunii/ubx-banking-system/blob/main/api-gateway/src/main/java/com/atm/gateway/service/DiscoveryResponder.java): `api-gateway/src/main/java/com/atm/gateway/service/DiscoveryResponder.java`

### RMI banking core

- [RMI bridge endpoints](https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/server/RmiBridgeController.java): `rmi-server/src/main/java/com/atm/rmi/server/RmiBridgeController.java`
- [Authentication and MFA](https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/service/AuthServiceImpl.java): `rmi-server/src/main/java/com/atm/rmi/service/AuthServiceImpl.java`
- [Account operations](https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/service/AccountServiceImpl.java): `rmi-server/src/main/java/com/atm/rmi/service/AccountServiceImpl.java`
- [Transactions](https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/service/TransactionServiceImpl.java): `rmi-server/src/main/java/com/atm/rmi/service/TransactionServiceImpl.java`
- [Account administration](https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/service/AdminServiceImpl.java): `rmi-server/src/main/java/com/atm/rmi/service/AdminServiceImpl.java`

### Core persistence

- [Customer records](https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/repository/CustomerRepository.java): `rmi-server/src/main/java/com/atm/rmi/repository/CustomerRepository.java`
- [Transaction records](https://github.com/hanzunii/ubx-banking-system/blob/main/rmi-server/src/main/java/com/atm/rmi/repository/TransactionRepository.java): `rmi-server/src/main/java/com/atm/rmi/repository/TransactionRepository.java`

### Legacy server

- [Legacy authentication](https://github.com/hanzunii/ubx-banking-system/blob/main/atm-server/src/main/java/com/atm/server/service/AuthService.java): `atm-server/src/main/java/com/atm/server/service/AuthService.java`
- [Legacy banking operations](https://github.com/hanzunii/ubx-banking-system/blob/main/atm-server/src/main/java/com/atm/server/service/BankingService.java): `atm-server/src/main/java/com/atm/server/service/BankingService.java`
- [Legacy account endpoints](https://github.com/hanzunii/ubx-banking-system/blob/main/atm-server/src/main/java/com/atm/server/controller/AccountController.java): `atm-server/src/main/java/com/atm/server/controller/AccountController.java`
- [Legacy auth endpoints](https://github.com/hanzunii/ubx-banking-system/blob/main/atm-server/src/main/java/com/atm/server/controller/AuthController.java): `atm-server/src/main/java/com/atm/server/controller/AuthController.java`
- [Legacy data store](https://github.com/hanzunii/ubx-banking-system/blob/main/atm-server/src/main/java/com/atm/server/DatabaseManager.java): `atm-server/src/main/java/com/atm/server/DatabaseManager.java`

### Other components

- **Bank user**
- **System admin**

## Connections

- Bank user → Web banking: uses (evidence: `README.md`)
- Bank user → Android banking: uses (evidence: `README.md`)
- System admin → Admin console: uses (evidence: `README.md`)
- Web routing and auth → Web banking: routes to (evidence: `web-app/src/App.jsx`)
- Web banking → REST controller: sends REST (evidence: `README.md`)
- Android banking → Android API client: requests through (evidence: `atm-android/app/src/main/java/com/atm/mobile/MainActivity.java`)
- Android API client → REST controller: sends REST (evidence: `README.md`)
- Android API client → Gateway discovery: resolves server (evidence: `atm-android/app/src/main/java/com/atm/mobile/network/ApiClient.java`)
- Gateway discovery → UDP discovery responder: probes (evidence: `README.md`)
- Admin console → Admin API client: uses (evidence: `admin-desktop/src/main/java/com/atm/admin/AdminService.java`)
- Admin API client → REST controller: calls REST (evidence: `admin-desktop/src/main/java/com/atm/admin/AdminService.java`)
- REST controller → JWT and security: issues tokens (evidence: `api-gateway/src/main/java/com/atm/gateway/controller/GatewayController.java`)
- REST controller → Transfer idempotency: records results (evidence: `api-gateway/src/main/java/com/atm/gateway/controller/GatewayController.java`)
- REST controller → RMI banking adapter: invokes banking (evidence: `api-gateway/src/main/java/com/atm/gateway/controller/GatewayController.java`)
- REST controller → Live balance push: pushes updates (evidence: `api-gateway/src/main/java/com/atm/gateway/controller/GatewayController.java`)
- Account WebSocket → Live balance push: delivers updates
- REST controller → RMI bridge endpoints: calls RMI services (evidence: `README.md`)
- RMI bridge endpoints → Authentication and MFA: delegates auth (evidence: `rmi-server/src/main/java/com/atm/rmi/server/RmiBridgeController.java`)
- RMI bridge endpoints → Account operations: delegates account (evidence: `rmi-server/src/main/java/com/atm/rmi/server/RmiBridgeController.java`)
- RMI bridge endpoints → Transactions: delegates transfers (evidence: `rmi-server/src/main/java/com/atm/rmi/server/RmiBridgeController.java`)
- RMI bridge endpoints → Account administration: delegates admin (evidence: `rmi-server/src/main/java/com/atm/rmi/server/RmiBridgeController.java`)
- Authentication and MFA → Customer records: reads and writes (evidence: `rmi-server/src/main/java/com/atm/rmi/service/AuthServiceImpl.java`)
- Transactions → Customer records: updates balances (evidence: `rmi-server/src/main/java/com/atm/rmi/service/TransactionServiceImpl.java`)
- Transactions → Transaction records: stores transactions (evidence: `rmi-server/src/main/java/com/atm/rmi/service/TransactionServiceImpl.java`)
- Account administration → Customer records: manages accounts (evidence: `rmi-server/src/main/java/com/atm/rmi/service/AdminServiceImpl.java`)
- Legacy auth endpoints → Legacy authentication: delegates auth (evidence: `atm-server/src/main/java/com/atm/server/controller/AuthController.java`)
- Legacy account endpoints → Legacy banking operations: delegates banking (evidence: `atm-server/src/main/java/com/atm/server/controller/AccountController.java`)
- Legacy authentication → Legacy data store: uses persistence
- Legacy banking operations → Legacy data store: uses persistence