# kunalsingh-bais/offline-upi-system-fullstack architecture

> Architecture diagram of the GitHub repository kunalsingh-bais/offline-upi-system-fullstack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kunalsingh-bais/offline-upi-system-fullstack
- Repository: https://github.com/kunalsingh-bais/offline-upi-system-fullstack

## Overview

#### Purpose and topology
This is an offline-payment/UPI-style system: an Angular client packaged as an Android Capacitor app communicates with Spring Boot microservices for authentication, wallet/profile management, and encrypted transaction processing. Bluetooth Low Energy (BLE) supports device-to-device payment exchange and later synchronization.

#### Client application and entry points
The Angular application starts at `frontend/src/main.ts`, with routing and providers assembled in `frontend/src/app/app.config.ts` and `frontend/src/app/app.routes.ts`. It exposes login/register, dashboard, payment initiation/completion, pending sync, and history views. HTTP authentication is centralized through the route guard and interceptor:
- `frontend/src/app/guards/auth-guard.ts`
- `frontend/src/app/interceptors/auth-interceptor.ts`
- `frontend/src/app/services/api.ts`

#### Android/BLE native boundary
Capacitor hosts the web client in Android, entered through `frontend/android/app/src/main/java/com/offlineupi/MainActivity.java`. Native BLE code owns advertising, discovery/client connections, GATT-server behavior, and connection lifecycle; this is the boundary between browser-facing Angular services and Android Bluetooth APIs:
- `frontend/android/app/src/main/java/com/offlineupi/ble/BluetoothConnectionManager.java`
- `frontend/android/app/src/main/java/com/offlineupi/ble/BluetoothGattServerManager.java`
- `frontend/android/app/src/main/java/com/offlineupi/ble/BluetoothClient.java`

Angular-side Bluetooth, encryption, local IndexedDB, network-state, and BLE-sync services enable offline capture and deferred reconciliation:
- `frontend/src/app/services/capacitor-bluetooth.ts`
- `frontend/src/app/services/indexed-db.ts`
- `frontend/src/app/services/sync-ble.ts`

#### Gateway and service discovery
The backend is independently built Maven/Spring Boot services. `Backend/Api-gateway/src/main/java/com/api/gateway/ApiGatewayApplication.java` is the intended external backend entry point, configured by `Backend/Api-gateway/src/main/resources/application.yml`. Service location/registration is handled separately by:
- `Backend/Service-registry/src/main/java/com/service/registry/ServiceRegistryApplication.java`
- `Backend/Service-registry/src/main/resources/application.properties`

This establishes an edge-routing/discovery boundary rather than direct frontend coupling to individual services.

#### Identity and authorization
Auth Service provides registration, login, and token validation. Its controller delegates credential/user operations to `AuthService`, persists auth users via `UserRepository`, and issues/verifies JWTs through `JwtTokenProvider`:
- `Backend/Auth-service/src/main/java/com/auth/service/controller/AuthController.java`
- `Backend/Auth-service/src/main/java/com/auth/service/service/AuthService.java`
- `Backend/Auth-service/src/main/java/com/auth/service/security/JwtTokenProvider.java`

Security configuration is service-local in `Backend/Auth-service/src/main/java/com/auth/service/config/SecurityConfig.java`. User Service and Transaction Service each contain security configurations and clients, implying token validation or authenticated service-to-service calls rather than a shared in-process security layer.

#### User profile and wallet domain
User Service separates profile and wallet persistence/operations. It calls Auth Service through `AuthServiceClient`, then exposes profile and balance endpoints through distinct controllers:
- `Backend/User-service/src/main/java/com/user/service/client/AuthServiceClient.java`
- `Backend/User-service/src/main/java/com/user/service/controller/UserProfileController.java`
- `Backend/User-service/src/main/java/com/user/service/controller/WalletController.java`

Core state is represented by `UserProfile` and `Wallet`, persisted through their repositories. Wallet balance updates are a critical downstream boundary for transaction completion.

#### Transaction lifecycle and cryptography
Transaction Service manages initiate, BLE sync, and completion flows through `TransactionController` and `TransactionService`. Transaction state is persisted independently, while a `UserServiceClient` links completion to wallet/user operations:
- `Backend/Transaction-service/src/main/java/com/transaction/service/controller/TransactionController.java`
- `Backend/Transaction-service/src/main/java/com/transaction/service/service/TransactionService.java`
- `Backend/Transaction-service/src/main/java/com/transaction/service/client/UserServiceClient.java`

The transaction payload boundary explicitly supports encrypted/decrypted forms and BLE-specific payloads. Encryption is layered: RSA key management/public-key publication, AES encryption, hashing, and orchestration in `EncryptionProcessor`:
- `Backend/Transaction-service/src/main/java/com/transaction/service/encryption/RSAKeyService.java`
- `Backend/Transaction-service/src/main/java/com/transaction/service/encryption/AESEncryptionService.java`
- `Backend/Transaction-service/src/main/java/com/transaction/service/encryption/EncryptionProcessor.java>

Main entry points: [`Backend/Api-gateway/src/main/java/com/api/gateway/ApiGatewayApplication.java`](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Api-gateway/src/main/java/com/api/gateway/ApiGatewayApplication.java) (API gateway), [`frontend/src/app/services/indexed-db.ts`](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/frontend/src/app/services/indexed-db.ts) (Offline store & sync), [`Backend/Transaction-service/src/main/java/com/transaction/service/service/TransactionService.java`](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Transaction-service/src/main/java/com/transaction/service/service/TransactionService.java) (Transaction lifecycle), [`Backend/Auth-service/src/main/java/com/auth/service/controller/AuthController.java`](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Auth-service/src/main/java/com/auth/service/controller/AuthController.java) (Auth service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Angular Client"]
  node_angular_app["Angular app<br/>web client<br/>[main.ts]"]
  node_client_security["Auth guard &amp; interceptor<br/>client auth<br/>[auth-guard.ts]"]
  node_api_client["API service<br/>HTTP client<br/>[api.ts]"]
  node_offline_store[("Offline store &amp; sync<br/>IndexedDB/BLE sync<br/>[indexed-db.ts]")]
  node_capacitor_bluetooth["Capacitor Bluetooth<br/>native bridge"]
end

subgraph group_native["Android BLE Boundary"]
  node_android_host["Capacitor Android host<br/>Android entry point<br/>[MainActivity.java]"]
  node_ble_transport["BLE transport<br/>Android BLE"]
end

subgraph group_edge["Backend Edge"]
  node_api_gateway{{"API gateway<br/>Spring Boot gateway"}}
  node_service_registry["Service registry<br/>service discovery"]
end

subgraph group_identity["Identity &amp; Wallet"]
  node_auth_api["Auth service<br/>Spring Boot service"]
  node_auth_core["Auth core &amp; JWT<br/>identity security<br/>[AuthService.java]"]
  node_user_wallet["User &amp; wallet service<br/>Spring Boot service"]
  node_auth_service_client["Auth service client"]
end

subgraph group_payments["Transaction Processing"]
  node_transaction_api["Transaction service<br/>Spring Boot service"]
  node_transaction_core["Transaction lifecycle<br/>transaction domain"]
  node_encryption_processor["Encryption processor<br/>crypto orchestration"]
  node_user_service_client["User service client"]
end

node_angular_app -->|"protected requests"| node_client_security
node_client_security -->|"authenticated HTTP"| node_api_client
node_api_client -->|"backend API"| node_api_gateway
node_angular_app -->|"offline payments"| node_offline_store
node_offline_store -->|"BLE sync"| node_capacitor_bluetooth
node_capacitor_bluetooth -->|"Capacitor bridge"| node_android_host
node_android_host -->|"native BLE"| node_ble_transport
node_ble_transport -.->|"peer payloads"| node_offline_store
node_api_gateway -.->|"discovers services"| node_service_registry
node_api_gateway -->|"routes auth"| node_auth_api
node_api_gateway -->|"routes profile/wallet"| node_user_wallet
node_api_gateway -->|"routes payments"| node_transaction_api
node_auth_api -->|"delegates"| node_auth_core
node_user_wallet -->|"validates identity"| node_auth_service_client
node_auth_service_client -->|"auth calls"| node_auth_api
node_transaction_api -->|"delegates"| node_transaction_core
node_transaction_core -->|"encrypts/decrypts payloads"| node_encryption_processor
node_transaction_core -->|"completes payment"| node_user_service_client
node_user_service_client -->|"wallet update"| node_user_wallet
node_offline_store -.->|"deferred reconciliation"| node_transaction_api

click node_angular_app "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/frontend/src/main.ts"
click node_client_security "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/frontend/src/app/guards/auth-guard.ts"
click node_api_client "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/frontend/src/app/services/api.ts"
click node_offline_store "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/frontend/src/app/services/indexed-db.ts"
click node_capacitor_bluetooth "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/frontend/src/app/services/capacitor-bluetooth.ts"
click node_android_host "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/frontend/android/app/src/main/java/com/offlineupi/MainActivity.java"
click node_ble_transport "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/frontend/android/app/src/main/java/com/offlineupi/ble/BluetoothConnectionManager.java"
click node_api_gateway "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Api-gateway/src/main/java/com/api/gateway/ApiGatewayApplication.java"
click node_service_registry "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Service-registry/src/main/java/com/service/registry/ServiceRegistryApplication.java"
click node_auth_api "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Auth-service/src/main/java/com/auth/service/controller/AuthController.java"
click node_auth_core "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Auth-service/src/main/java/com/auth/service/service/AuthService.java"
click node_user_wallet "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/User-service/src/main/java/com/user/service/controller/WalletController.java"
click node_auth_service_client "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/User-service/src/main/java/com/user/service/client/AuthServiceClient.java"
click node_transaction_api "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Transaction-service/src/main/java/com/transaction/service/controller/TransactionController.java"
click node_transaction_core "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Transaction-service/src/main/java/com/transaction/service/service/TransactionService.java"
click node_user_service_client "https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Transaction-service/src/main/java/com/transaction/service/client/UserServiceClient.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_angular_app,node_client_security,node_api_client,node_offline_store,node_capacitor_bluetooth toneBlue
class node_android_host,node_ble_transport toneAmber
class node_api_gateway,node_service_registry toneMint
class node_auth_api,node_auth_core,node_user_wallet,node_auth_service_client toneRose
class node_transaction_api,node_transaction_core,node_encryption_processor,node_user_service_client toneIndigo
```

## Components

### Angular Client

Offline-capable payment UI and client services.

- [Angular app](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/frontend/src/main.ts): web client · `frontend/src/main.ts`
- [Auth guard & interceptor](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/frontend/src/app/guards/auth-guard.ts): client auth · Protects routes and attaches authentication to API requests. · `frontend/src/app/guards/auth-guard.ts`
- [API service](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/frontend/src/app/services/api.ts): HTTP client · `frontend/src/app/services/api.ts`
- [Offline store & sync](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/frontend/src/app/services/indexed-db.ts): IndexedDB/BLE sync · Captures offline payment state for deferred reconciliation. · `frontend/src/app/services/indexed-db.ts`
- [Capacitor Bluetooth](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/frontend/src/app/services/capacitor-bluetooth.ts): native bridge · `frontend/src/app/services/capacitor-bluetooth.ts`

### Android BLE Boundary

Capacitor-hosted native Bluetooth implementation.

- [Capacitor Android host](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/frontend/android/app/src/main/java/com/offlineupi/MainActivity.java): Android entry point · `frontend/android/app/src/main/java/com/offlineupi/MainActivity.java`
- [BLE transport](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/frontend/android/app/src/main/java/com/offlineupi/ble/BluetoothConnectionManager.java): Android BLE · Owns advertising, discovery, GATT server, and connection lifecycle. · `frontend/android/app/src/main/java/com/offlineupi/ble/BluetoothConnectionManager.java`

### Backend Edge

Gateway routing and service discovery.

- [API gateway](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Api-gateway/src/main/java/com/api/gateway/ApiGatewayApplication.java): Spring Boot gateway · External backend entry point and router. · `Backend/Api-gateway/src/main/java/com/api/gateway/ApiGatewayApplication.java`
- [Service registry](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Service-registry/src/main/java/com/service/registry/ServiceRegistryApplication.java): service discovery · `Backend/Service-registry/src/main/java/com/service/registry/ServiceRegistryApplication.java`

### Identity & Wallet

Authentication, profiles, and wallet balances.

- [Auth service](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Auth-service/src/main/java/com/auth/service/controller/AuthController.java): Spring Boot service · Registration, login, and token validation. · `Backend/Auth-service/src/main/java/com/auth/service/controller/AuthController.java`
- [Auth core & JWT](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Auth-service/src/main/java/com/auth/service/service/AuthService.java): identity security · Authenticates users and issues or verifies JWTs. · `Backend/Auth-service/src/main/java/com/auth/service/service/AuthService.java`
- [User & wallet service](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/User-service/src/main/java/com/user/service/controller/WalletController.java): Spring Boot service · Serves profiles and balances; applies wallet updates. · `Backend/User-service/src/main/java/com/user/service/controller/WalletController.java`
- [Auth service client](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/User-service/src/main/java/com/user/service/client/AuthServiceClient.java): service client · `Backend/User-service/src/main/java/com/user/service/client/AuthServiceClient.java`

### Transaction Processing

Encrypted transaction lifecycle and reconciliation.

- [Transaction service](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Transaction-service/src/main/java/com/transaction/service/controller/TransactionController.java): Spring Boot service · Initiates, synchronizes, and completes payments. · `Backend/Transaction-service/src/main/java/com/transaction/service/controller/TransactionController.java`
- [Transaction lifecycle](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Transaction-service/src/main/java/com/transaction/service/service/TransactionService.java): transaction domain · Persists independent transaction state and drives completion. · `Backend/Transaction-service/src/main/java/com/transaction/service/service/TransactionService.java`
- **Encryption processor**: crypto orchestration · Coordinates RSA keys, AES encryption, and hashing for transaction payloads.
- [User service client](https://github.com/kunalsingh-bais/offline-upi-system-fullstack/blob/main/Backend/Transaction-service/src/main/java/com/transaction/service/client/UserServiceClient.java): service client · Links transaction completion to wallet and user operations. · `Backend/Transaction-service/src/main/java/com/transaction/service/client/UserServiceClient.java`

## Connections

- Angular app → Auth guard & interceptor: protected requests
- Auth guard & interceptor → API service: authenticated HTTP
- API service → API gateway: backend API
- Angular app → Offline store & sync: offline payments
- Offline store & sync → Capacitor Bluetooth: BLE sync
- Capacitor Bluetooth → Capacitor Android host: Capacitor bridge
- Capacitor Android host → BLE transport: native BLE
- BLE transport → Offline store & sync: peer payloads
- API gateway → Service registry: discovers services
- API gateway → Auth service: routes auth
- API gateway → User & wallet service: routes profile/wallet
- API gateway → Transaction service: routes payments
- Auth service → Auth core & JWT: delegates
- User & wallet service → Auth service client: validates identity
- Auth service client → Auth service: auth calls
- Transaction service → Transaction lifecycle: delegates
- Transaction lifecycle → Encryption processor: encrypts/decrypts payloads
- Transaction lifecycle → User service client: completes payment
- User service client → User & wallet service: wallet update
- Offline store & sync → Transaction service: deferred reconciliation