games_app/docs/SPRING_BOOT_MIGRATION_FEASIBILITY.md
2026-06-29 15:01:23 +02:00

9.4 KiB
Raw Blame History

Migration Backend → Spring Boot – Feasibility (Refonte)

This document lists all current backend functionalities and confirms that each can be implemented in Spring Boot without losing any capability. No code has been modified; this is an assurance before any refonte (migration).


1. Current Stack Summary

  • Runtime: Node.js (Express + TypeScript)
  • Database: PostgreSQL (same schema can be kept)
  • Auth: JWT (access + refresh), Argon2/bcrypt, TOTP (2FA)
  • Blockchain: TRON (TronWeb), Polygon (ethers.js), BIP39/HD (bip39 + ethers + TronWeb)

2. Functionality Checklist → Spring Boot Equivalents

2.1 Authentication & Users

Current (Node) Spring Boot / Java Equivalent Possible?
Register (email + password, email hashed for lookup, encrypted at rest) Spring Security + custom UserDetailsService; JPA entities; AES-GCM via javax.crypto or Spring Security Crypto ✅ Yes
Login (rate-limited) Spring Security form/login or custom filter; Bucket4j or Spring rate-limiter ✅ Yes
JWT access + refresh tokens jjwt (io.jsonwebtoken) or Spring Security OAuth2 Resource Server; refresh stored in DB ✅ Yes
Password hashing (Argon2 / bcrypt) Spring Security PasswordEncoder (Argon2PasswordEncoder, BCryptPasswordEncoder) ✅ Yes
2FA TOTP (setup: generate secret, QR code) e.g. com.eatthepath:java-otp + ZXing or similar for QR ✅ Yes
2FA enable (verify 6-digit code) Same TOTP lib to verify code ✅ Yes
Email/phone encrypted storage, email_hash for index Same schema; encryption with AES-256-GCM in Java ✅ Yes

2.2 Wallet & Ledger (API)

Current (Node) Spring Boot / Java Equivalent Possible?
GET /wallet-types Spring Data JPA WalletType repository; same table ✅ Yes
GET /balances Service that reads ledger_accounts (or view) per user; same schema ✅ Yes
GET /deposit-address/:walletType HD derivation (see 2.4) → return address; store in user_wallets ✅ Yes
GET /transactions JPA Transaction repository, filter by user, pagination ✅ Yes

2.3 Internal Transfer

Current (Node) Spring Boot / Java Equivalent Possible?
POST /transfer (toEmail, walletType, amount, totpCode) Service: verify TOTP, lookup user by email_hash, debit/credit in one @Transactional method, create 2 transaction rows ✅ Yes
Ledger: transferBetweenAccounts (debit sender, credit receiver, ledger_entries with reference_id UUID) Same logic in a single transaction; JPA or raw JDBC ✅ Yes

2.4 Withdrawals

Current (Node) Spring Boot / Java Equivalent Possible?
Lock balance, create withdrawal transaction & lock record Service with @Transactional; same tables ✅ Yes
Sign and broadcast TRON (TRX or TRC20) HTTP to TronGrid API or Java TRON client (e.g. tron4j / TronGrid HTTP) ✅ Yes
Sign and broadcast Polygon (ERC-20 USDC) web3j for Ethereum-compatible chains (Polygon) ✅ Yes
Hot wallet private key decryption AES-GCM in Java (same as encrypting email/TOTP) ✅ Yes
Unlock balance on success/failure, update tx status Same business logic in service layer ✅ Yes

2.5 Deposit Monitoring (Background Job)

Current (Node) Spring Boot / Java Equivalent Possible?
Periodic poll (e.g. every 60s) @Scheduled(fixedDelay = 60000) or Quartz ✅ Yes
TRON: get TRX transfers to user addresses TronGrid HTTP API (same as TronWeb uses) or Java TRON client ✅ Yes
TRON: get TRC20 (USDT) transfers to user addresses Same; TRC20 contract calls / events via TronGrid ✅ Yes
Polygon: get ERC-20 (USDC) transfers to user addresses web3j + contract events (Transfer) or logs ✅ Yes
Confirmations logic (time-based or block-based) Same logic in Java ✅ Yes
Credit ledger, create transaction, update scanner state JPA repositories; same schema ✅ Yes
Idempotency (blockchain_tx_id) Same unique constraint and checks ✅ Yes

2.6 HD Wallet & Keys

Current (Node) Spring Boot / Java Equivalent Possible?
BIP39 mnemonic (generate, mnemonicToSeed) bitcoinj or BIP39 library for Java (e.g. org.bitcoinj:bitcoinj-core or dedicated BIP39 lib) ✅ Yes
Derive TRON path m/44'/195'/0'/0/n TRON uses same derivation as some Java libs; or call TronGrid “create account” / derive via their API; or use a small TRON key-derivation lib in Java ✅ Yes
Derive Ethereum/Polygon path m/44'/60'/0'/0/n web3j or bitcoinj BIP44 for ETH ✅ Yes
Encrypt/decrypt private keys (AES-256-GCM) javax.crypto.Cipher with AES/GCM/NoPadding ✅ Yes
Seed hot wallets (script) Same logic as service; runnable as CommandLineRunner or separate script with Spring context ✅ Yes

2.7 Database & Schema

Current (Node) Spring Boot / Java Equivalent Possible?
PostgreSQL Spring Data JPA + same PostgreSQL; no schema change required ✅ Yes
Migrations (schema.sql / migrate) Flyway or Liquibase; reuse same SQL or generate from JPA (careful with existing data) ✅ Yes
All tables (users, roles, refresh_tokens, wallet_types, user_wallets, hot_wallets, ledger_accounts, ledger_entries, transactions, withdrawal_locks, deposit_scanner_state, audit_logs, exchange_funding) Same schema; map to JPA entities or keep raw SQL where needed (e.g. complex ledger updates) ✅ Yes

2.8 Security & Middleware

Current (Node) Spring Boot / Java Equivalent Possible?
CORS (origin, credentials) WebMvcConfigurer or @CrossOrigin ✅ Yes
Helmet-like (security headers) Spring Security headers ✅ Yes
Rate limiting (API + stricter login) Bucket4j, or Spring Cloud Gateway, or custom filter with in-memory/Redis ✅ Yes
JWT auth middleware Spring Security JWT filter or OAuth2 Resource Server ✅ Yes
Audit log (sensitive actions) @Aspect or filter/interceptor writing to audit_logs table ✅ Yes

2.9 Configuration & Environment

Current (Node) Spring Boot / Java Equivalent Possible?
.env / ENV_FILE (DATABASE_URL, JWT_SECRET, TRON_, POLYGON_, etc.) application.yml / application-{profile}.yml and spring.config.additional-location or env vars ✅ Yes
Config (port, apiPrefix, blockchain, rateLimit, withdrawal limits) @ConfigurationProperties classes ✅ Yes

2.10 Scripts & Operations

Current (Node) Spring Boot / Java Equivalent Possible?
seed-hot-wallets (mnemonic → derive & store hot wallets) CommandLineRunner or standalone Spring app / script using same services ✅ Yes
migrate (run schema) Flyway/Liquibase on startup or Maven/Gradle task ✅ Yes
Health check GET /health Spring Boot Actuator management.endpoints.web.exposure.include=health ✅ Yes

3. External / Blockchain Dependencies

  • TRON: TronWeb is JavaScript. In Java you use:
    • TronGrid HTTP API (same backend TronWeb calls), or
    • A Java TRON SDK (e.g. tron4j, or official grpc-client if available).
  • Polygon (EVM): web3j is the standard Java library for Ethereum and EVM chains (Polygon).
  • BIP39 / HD: Java libs (bitcoinj, or dedicated BIP39) cover mnemonic and derivation; TRON path 195' may need a small adapter or a lib that supports custom curves/paths.

None of these block the migration; they only require choosing the right Java libraries and possibly a thin adapter layer for TRON (HTTP or SDK).


4. Conclusion

  • All functionalities listed above (auth, wallet, balances, deposit addresses, transactions, internal transfer, withdrawals, deposit monitoring, HD wallet, encryption, rate limiting, audit, config, scripts) can be implemented in Spring Boot without losing any of the behaviour you defined at the beginning.
  • The same PostgreSQL schema can be kept; the same API contract (paths, request/response bodies) can be preserved so the Flutter app does not need to change (only the base URL if needed).
  • The only “translation” is from Node/TS libraries to Java equivalents (TronWeb → TronGrid HTTP or Java TRON SDK; ethers → web3j; bip39/ethers → Java BIP39/bitcoinj/web3j).

5. Suggested Migration Phases (When You Decide to Proceed)

  1. Phase 1: New Spring Boot project; DB connection; Flyway with current schema; implement auth (register, login, refresh, 2FA) and wallet API (wallet-types, balances, deposit-address, transactions). Keep Node backend running in parallel until parity.
  2. Phase 2: Internal transfer + withdrawal (with HD/hot wallet and TRON/Polygon in Java).
  3. Phase 3: Deposit monitor as scheduled job; seed-hot-wallets script; rate limiting and audit.
  4. Phase 4: Switch Flutter to new base URL; retire Node backend after tests.

If you want to proceed with the refonte, the next step is Phase 1 (scaffold Spring Boot and replicate auth + wallet APIs) while keeping your current backend unchanged until the new one is validated.