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

141 lines
9.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.