jhely-group/fintech-framework

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.