# jhely-group/fintech-framework architecture

> Architecture diagram of the GitHub repository jhely-group/fintech-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jhely-group/fintech-framework
- Repository: https://github.com/jhely-group/fintech-framework

## Overview

#### 1. Purpose and Runtime
This is a Java 21/Spring Boot fintech framework for KYC onboarding, fiat/stablecoin payment operations, AI receipt extraction, and x402 agent-payment facilitation. The primary executable is `src/main/java/org/jhely/money/Application.java`; Maven and the container build are rooted at `pom.xml` and `Dockerfile`. It uses Spring Boot, Vaadin Flow server-rendered UI, MySQL/JPA persistence, and virtual-thread-oriented async work.

#### 2. Delivery Surfaces
The backend exposes both authenticated Vaadin screens and REST/webhook endpoints. Main user flows begin in `src/main/java/org/jhely/money/base/ui/view/MainLayout.java`, with wallet/payment screens under `src/main/java/org/jhely/money/base/ui/view/payments/` and x402 administration at `src/main/java/org/jhely/money/base/ui/view/x402/X402DashboardView.java`. REST boundaries include receipt/Stripe controllers and Bridge/x402 controllers, e.g. `src/main/java/org/jhely/money/base/api/ReceiptController.java`, `src/main/java/org/jhely/money/base/api/bridge/BridgeWebhookController.java`, and `src/main/java/org/jhely/money/base/api/x402/X402FacilitatorController.java`.

#### 3. Core Domain and Persistence
JPA domain entities model local users, balances and ledger transactions, payment-provider relationships, coupons, OTPs, uploaded receipt files/extractions, and x402 configuration/request logs. Key records are in `src/main/java/org/jhely/money/base/domain/UserAccount.java`, `src/main/java/org/jhely/money/base/domain/AccountTransaction.java`, and `src/main/java/org/jhely/money/base/domain/BridgeAgreement.java`. Spring Data repositories form the database boundary in `src/main/java/org/jhely/money/base/repository/`, backed by MySQL configured through `src/main/resources/application.properties`.

#### 4. Identity, Wallet, and Payments
Business services coordinate local accounts with Bridge’s KYC and payment rails. Onboarding creates/manages Bridge customers and hosted KYC, while callbacks and webhooks update local agreement/customer state and broadcast UI status. Relevant paths: `src/main/java/org/jhely/money/base/service/payments/BridgeOnboardingService.java`, `src/main/java/org/jhely/money/base/api/payments/BridgeKycCallbackController.java`, and `src/main/java/org/jhely/money/base/service/payments/TransferService.java`. Wallet, virtual-account, and external-account operations are separated into provider-facing services rather than embedded in UI/controllers.

#### 5. Bridge Integration Boundary
Bridge API access is encapsulated by configuration/client factories and a generated SDK. Application-facing code uses `src/main/java/org/jhely/money/base/api/payments/BridgeApiClient.java` and `src/main/java/org/jhely/money/base/service/BridgeApiClientFactory.java`; generated OpenAPI transport/models live under `src/main/java/org/jhely/money/sdk/bridge/`. Webhook provisioning and verification are explicit integration stages in `src/main/java/org/jhely/money/base/service/payments/BridgeWebhookProvisioner.java` and `src/main/java/org/jhely/money/base/service/payments/BridgeWebhookKeyProvider.java`.

#### 6. Receipt Processing Pipeline
Receipt ingestion persists files, then asynchronous extraction combines PDF text/OCR, parsing, and OpenAI fallback/model escalation into extraction results. The workflow centers on `src/main/java/org/jhely/money/base/service/ReceiptService.java`, `src/main/java/org/jhely/money/base/service/ExtractionWorker.java`, and `src/main/java/org/jhely/money/base/service/extract/AiFallbackService.java`. This is a clear external-service boundary: uploaded document data becomes persisted `ReceiptFile`/`ReceiptExtraction` state, with OpenAI configured in `src/main/java/org/jhely/money/base/config/OpenAIConfig.java`.

#### 7. x402 Facilitator and Demo Consumer
The x402 module verifies and settles USDC/Solana protocol payments, protects facilitator operations with API-key/security controls, and logs requests/configuration locally. Its API/service boundary is `src/main/java/org/jhely/money/base/api/x402/X402FacilitatorController.java`, `src/main/java/org/jhely/money/base/service/x402/X402FacilitatorService.java`, and `src/main/java/org/jhely/money/base/domain/X402ApiRequestLog.java`. `example-x402/` is a separate Next.js consumer/demo: its paid endpoint at `example-x402/src/app/api/paid/route.ts` exercises the Java facilitator, while `example-x402/src/app/wallet/page.tsx` supplies wallet-facing UI.

#### 8. Cross-Cutting Controls
Authentication, authorization, CORS, request logging, and protocol-specific exception handling are centralized rather than distributed across features: `src/main/java/org/jhely/money/base/config/SecurityConfig.java`, `src/main/java/org/jhely/money/base/config/X402SecurityConfig.java`, and `src/main/java/org/jhely/money/base/api/x402/X402ExceptionHandler.java`. These controls separate browser/UI security from external webhook and x402 API trust boundaries.

Main entry points: [`src/main/java/org/jhely/money/base/ui/view/MainLayout.java`](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/ui/view/MainLayout.java) (Vaadin UI), [`src/main/java/org/jhely/money/base/api/ReceiptController.java`](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/api/ReceiptController.java) (REST and webhooks), [`src/main/java/org/jhely/money/base/service/BridgeApiClientFactory.java`](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/BridgeApiClientFactory.java) (Bridge client boundary), [`src/main/java/org/jhely/money/base/service/payments/BridgeOnboardingService.java`](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/payments/BridgeOnboardingService.java) (KYC onboarding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Spring Boot application"]
  node_runtime{{"Application runtime<br/>Spring Boot<br/>[Application.java]"}}
  node_ui["Vaadin UI<br/>server-rendered UI<br/>[MainLayout.java]"]
  node_rest["REST and webhooks<br/>controllers"]
  node_security["Security controls<br/>Spring Security"]
  node_domain["Financial domain<br/>JPA entities<br/>[UserAccount.java]"]
  node_repositories["Repositories<br/>Spring Data JPA"]
  node_mysql[("MySQL<br/>database")]
end

subgraph group_bridge["Bridge payments"]
  node_onboarding["KYC onboarding<br/>payment service"]
  node_transfers["Wallet and transfers<br/>payment service"]
  node_bridgeclient["Bridge client boundary<br/>API client factory"]
  node_bridgesdk["Bridge SDK<br/>generated OpenAPI SDK"]
  node_bridgewebhooks["Bridge webhook lifecycle<br/>provisioning and verification"]
  node_bridgeapi{{"Bridge platform"}}
end

subgraph group_receipt["Receipt extraction"]
  node_receiptservice["Receipt ingestion<br/>receipt service"]
  node_worker["Extraction worker<br/>async pipeline"]
  node_ai["OpenAI fallback<br/>AI extraction service"]
  node_openai{{"OpenAI<br/>external AI service"}}
end

subgraph group_x402["x402 facilitator"]
  node_x402api["Facilitator API<br/>secured controller"]
  node_x402service["Facilitator service<br/>protocol service"]
end

subgraph group_demo["Demo consumer"]
  node_consumer["Paid endpoint<br/>Next.js demo API<br/>[route.ts]"]
  node_walletdemo["Wallet demo UI<br/>Next.js UI<br/>[page.tsx]"]
end

node_runtime -->|"hosts"| node_ui
node_runtime -->|"hosts"| node_rest
node_security -->|"protects"| node_ui
node_security -->|"secures"| node_rest
node_ui -->|"starts KYC"| node_onboarding
node_ui -->|"manages funds"| node_transfers
node_rest -->|"uploads receipts"| node_receiptservice
node_rest -->|"receives Bridge events"| node_bridgewebhooks
node_onboarding -->|"uses"| node_bridgeclient
node_transfers -->|"uses"| node_bridgeclient
node_bridgewebhooks -->|"provisions through"| node_bridgeclient
node_bridgeclient -->|"creates client"| node_bridgesdk
node_bridgesdk -->|"calls"| node_bridgeapi
node_onboarding -->|"updates state"| node_repositories
node_transfers -->|"records transactions"| node_repositories
node_receiptservice -->|"schedules"| node_worker
node_worker -->|"falls back to"| node_ai
node_ai -->|"invokes"| node_openai
node_worker -->|"persists results"| node_repositories
node_repositories -->|"manages"| node_domain
node_repositories -->|"stores in"| node_mysql
node_consumer -->|"requests payment facilitation"| node_x402api
node_walletdemo -->|"uses"| node_consumer
node_x402api -->|"delegates to"| node_x402service
node_x402service -->|"logs requests and config"| node_repositories

click node_runtime "https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/Application.java"
click node_ui "https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/ui/view/MainLayout.java"
click node_rest "https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/api/ReceiptController.java"
click node_security "https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/config/SecurityConfig.java"
click node_domain "https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/domain/UserAccount.java"
click node_mysql "https://github.com/jhely-group/fintech-framework/blob/main/src/main/resources/application.properties"
click node_onboarding "https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/payments/BridgeOnboardingService.java"
click node_transfers "https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/payments/TransferService.java"
click node_bridgeclient "https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/BridgeApiClientFactory.java"
click node_bridgewebhooks "https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/payments/BridgeWebhookProvisioner.java"
click node_receiptservice "https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/ReceiptService.java"
click node_worker "https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/ExtractionWorker.java"
click node_ai "https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/extract/AiFallbackService.java"
click node_x402api "https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/api/x402/X402FacilitatorController.java"
click node_x402service "https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/x402/X402FacilitatorService.java"
click node_consumer "https://github.com/jhely-group/fintech-framework/blob/main/example-x402/src/app/api/paid/route.ts"
click node_walletdemo "https://github.com/jhely-group/fintech-framework/blob/main/example-x402/src/app/wallet/page.tsx"

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_runtime,node_ui,node_rest,node_security,node_domain,node_repositories,node_mysql toneBlue
class node_onboarding,node_transfers,node_bridgeclient,node_bridgesdk,node_bridgewebhooks,node_bridgeapi toneAmber
class node_receiptservice,node_worker,node_ai,node_openai toneMint
class node_x402api,node_x402service toneRose
class node_consumer,node_walletdemo toneIndigo
```

## Components

### Spring Boot application

- [Application runtime](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/Application.java): Spring Boot · Java 21 application with virtual-thread-oriented async work. · `src/main/java/org/jhely/money/Application.java`
- [Vaadin UI](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/ui/view/MainLayout.java): server-rendered UI · `src/main/java/org/jhely/money/base/ui/view/MainLayout.java`
- [REST and webhooks](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/api/ReceiptController.java): controllers · `src/main/java/org/jhely/money/base/api/ReceiptController.java`
- [Security controls](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/config/SecurityConfig.java): Spring Security · Centralizes authentication, authorization, CORS, and API trust boundaries. · `src/main/java/org/jhely/money/base/config/SecurityConfig.java`
- [Financial domain](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/domain/UserAccount.java): JPA entities · Accounts, transactions, agreements, receipts, and x402 logs. · `src/main/java/org/jhely/money/base/domain/UserAccount.java`
- **Repositories**: Spring Data JPA
- [MySQL](https://github.com/jhely-group/fintech-framework/blob/main/src/main/resources/application.properties): database · `src/main/resources/application.properties`

### Bridge payments

- [KYC onboarding](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/payments/BridgeOnboardingService.java): payment service · Synchronizes local customers and hosted KYC state. · `src/main/java/org/jhely/money/base/service/payments/BridgeOnboardingService.java`
- [Wallet and transfers](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/payments/TransferService.java): payment service · Coordinates wallet, virtual-account, and transfer operations. · `src/main/java/org/jhely/money/base/service/payments/TransferService.java`
- [Bridge client boundary](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/BridgeApiClientFactory.java): API client factory · Application-facing access to the generated Bridge SDK. · `src/main/java/org/jhely/money/base/service/BridgeApiClientFactory.java`
- **Bridge SDK**: generated OpenAPI SDK
- [Bridge webhook lifecycle](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/payments/BridgeWebhookProvisioner.java): provisioning and verification · `src/main/java/org/jhely/money/base/service/payments/BridgeWebhookProvisioner.java`
- **Bridge platform**: external KYC and payment rails

### Receipt extraction

- [Receipt ingestion](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/ReceiptService.java): receipt service · Persists uploaded receipt files and schedules extraction. · `src/main/java/org/jhely/money/base/service/ReceiptService.java`
- [Extraction worker](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/ExtractionWorker.java): async pipeline · Combines PDF text/OCR and parsing into persisted extraction state. · `src/main/java/org/jhely/money/base/service/ExtractionWorker.java`
- [OpenAI fallback](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/extract/AiFallbackService.java): AI extraction service · Escalates extraction when local parsing is insufficient. · `src/main/java/org/jhely/money/base/service/extract/AiFallbackService.java`
- **OpenAI**: external AI service

### x402 facilitator

- [Facilitator API](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/api/x402/X402FacilitatorController.java): secured controller · Receives x402 payment verification and settlement requests. · `src/main/java/org/jhely/money/base/api/x402/X402FacilitatorController.java`
- [Facilitator service](https://github.com/jhely-group/fintech-framework/blob/main/src/main/java/org/jhely/money/base/service/x402/X402FacilitatorService.java): protocol service · Verifies and settles USDC/Solana protocol payments. · `src/main/java/org/jhely/money/base/service/x402/X402FacilitatorService.java`

### Demo consumer

- [Paid endpoint](https://github.com/jhely-group/fintech-framework/blob/main/example-x402/src/app/api/paid/route.ts): Next.js demo API · Exercises the Java facilitator from a separate consumer. · `example-x402/src/app/api/paid/route.ts`
- [Wallet demo UI](https://github.com/jhely-group/fintech-framework/blob/main/example-x402/src/app/wallet/page.tsx): Next.js UI · `example-x402/src/app/wallet/page.tsx`

## Connections

- Application runtime → Vaadin UI: hosts
- Application runtime → REST and webhooks: hosts
- Security controls → Vaadin UI: protects
- Security controls → REST and webhooks: secures
- Vaadin UI → KYC onboarding: starts KYC
- Vaadin UI → Wallet and transfers: manages funds
- REST and webhooks → Receipt ingestion: uploads receipts
- REST and webhooks → Bridge webhook lifecycle: receives Bridge events
- KYC onboarding → Bridge client boundary: uses
- Wallet and transfers → Bridge client boundary: uses
- Bridge webhook lifecycle → Bridge client boundary: provisions through
- Bridge client boundary → Bridge SDK: creates client
- Bridge SDK → Bridge platform: calls
- KYC onboarding → Repositories: updates state
- Wallet and transfers → Repositories: records transactions
- Receipt ingestion → Extraction worker: schedules
- Extraction worker → OpenAI fallback: falls back to
- OpenAI fallback → OpenAI: invokes
- Extraction worker → Repositories: persists results
- Repositories → Financial domain: manages
- Repositories → MySQL: stores in
- Paid endpoint → Facilitator API: requests payment facilitation
- Wallet demo UI → Paid endpoint: uses
- Facilitator API → Facilitator service: delegates to
- Facilitator service → Repositories: logs requests and config