BountyHunter Backend - Business Flow Overview
1. Mục tiêu tài liệu
Tài liệu này tổng hợp luồng nghiệp vụ chính của BountyHunter-Backend theo góc nhìn technical leader mới onboarding, bám theo source code thực tế trong các module web, authentication, websocket, webmarketplace, livestreamweb, batch, firebaselistener, admin, receiver-service.
2. Bức tranh tổng thể
flowchart LR
Client[Mobile/Web Client] --> API["REST APIs\nweb/authentication/webmarketplace/livestreamweb"]
Client --> WS["WebSocket\n/websocket/{token}"]
AdminUI["Admin Portal"] --> AdminAPI["admin module\nport 8083"]
API --> Core[application-core\nBusiness Services]
WS --> Core
AdminAPI --> Core
Core --> DB[(MySQL)]
Core --> Redis[(Redis)]
Core --> MQ[(ActiveMQ Artemis)]
Core --> Firebase[(Firebase RTDB)]
MQ --> Batch[batch module\nJMS Listeners + Schedulers]
Batch --> Core
Batch --> Firebase
FirebaseListener[firebaselistener module] --> Firebase
FirebaseListener --> Core
ControlServer[BountyHunter-ControlServer\nIoT Bridge] -->|"queue-control-server-gameplay\nqueue-control-server-health-check\nqueue-machine_history_log"| MQ
MQ --> ReceiverSvc[receiver-service\nport 8088]
ReceiverSvc --> Core
ReceiverSvc --> Slack[(Slack Alerts)]
3. Luồng nghiệp vụ chính
| Luồng |
Entry point |
Thành phần xử lý chính |
Kết quả |
| Authentication |
POST /api/auth/generate-code, POST /api/auth/sign-in |
AuthController → LoginHandlerFactory → Web3AuthLoginHandler/ImmutableLoginHandler → AuthService |
Tạo user/session, cấp JWT |
| Game room (PVE) |
WS command (CREATE_PVE_*, JOIN_PVE_*) |
RoomCmdConsumer → CreateRoomService → Prize Allocation Queue → JMS listener → CreateRoomJMSService |
Tạo/join room, trừ tài nguyên |
| Matching & Matchmaking |
WS command JOIN_QUEUE_MATCH_MATCHING, JOIN_OPPONENT_POOL, SEND_INVITATION |
MatchMatchingCmdConsumer/OpponentPoolCmdHandler/InvitationCmdConsumer → queue chuyên biệt |
Ghép trận, pool đối thủ, mời chơi |
| Prize allocation |
Message vào queue-prize-allocation-* |
SendPrizeAllocationMessageService + nhóm listener JMS*AllocationListener |
Phân bổ/rollback prize theo loại |
| Payment & Marketplace |
webmarketplace APIs + webhook |
PaymentService (card/crypto/native/apple/google) + WebHookController |
Checkout, xác nhận thanh toán, cập nhật order |
| Livestream |
livestreamweb APIs + Firebase |
LivestreamController + LivestreamFirebaseService + gift aggregation (Redis→Batch JMS) |
Đồng bộ lượt xem/gift/điểm/yell point |
| NFT management |
web + webmarketplace APIs |
NftHunterService, NftGauntletService, NftBountyBallService, NftRentalOrderService |
Quản lý inventory NFT + rental lifecycle |
| Batch & async ops |
Scheduler + JMS + Firebase listeners |
batch + firebaselistener |
Cleanup, reconciliation, archive, event-driven updates |
| Admin backoffice |
Admin portal REST APIs |
admin module: Machine/User/Event/NFT/Livestream/IoT/Dashboard controllers |
CRUD master data, manage machines, trigger batch, monitor KPIs |
| IoT machine telemetry |
JMS messages from ControlServer |
receiver-service: 3 JMS listeners |
Lưu machine logs, xử lý gameplay events từ crane machine, health-check |
4. Luồng E2E tiêu biểu
4.1 Matchmaking (WS)
- Client gửi
JOIN_QUEUE_MATCH_MATCHING tới WebSocket.
CreateRoomService validate và route message sang queue prize allocation phù hợp (PRIZE / PRIZE_FOR_STREAMER / UNLIMITED).JMS*AllocationListener xử lý tuần tự theo queue, gọi UserMatchingService.- Khi đủ điều kiện ghép trận, room được tạo và broadcast ngược về client qua pub/sub.
4.2 Mua NFT bằng native token
- Client gọi
webmarketplace (/api/users/buy-nft/{productId} hoặc flow genesis).
PaymentService ủy quyền PaymentNativeTokenService để tạo order/verify on-chain.- Webhook/confirm endpoint cập nhật trạng thái order, ownership, inventory.
4.3 Livestream gift aggregation
- Gift events được cộng dồn trong Redis theo
streamerId.
GiftAggregationJob (batch) quét key, GETSET và đẩy message aggregate vào ActiveMQ (kèm JMSXGroupID=streamerId).JMSLivestreamViewerGiftFirebaseUpdateListener deposit B-Coin + update Firebase counters/WishOrb.
5. Mapping tài liệu chi tiết