How thurpe/bumpa-gamified-cashback works
Bumpa is an event-driven cashback backend: recording a customer purchase triggers achievement and badge evaluation, then queues a Paystack cashback payout. Customers can also query gamification state; payout recovery is handled by a reconciliation command and a signed webhook. The README documents these behaviors, but several implementations (including evaluators, the payout job, and reconciliation command) were not sampled, so their links reflect documented behavior rather than inspected call sites.
Main entry points: Payout.php Purchase, unlock, payout records · EvaluateAchievements.php Achievement evaluator · EvaluateBadges.php Badge evaluator · DispatchCashbackJob.php Cashback job
Components 19
Purchase and events
- Purchase API
app/Http/Controllers/PurchaseController.php - PurchaseCompleted
app/Events/PurchaseCompleted.php - Event wiring
app/Providers/EventServiceProvider.php
Gamification
- Achievement evaluator
app/Listeners/EvaluateAchievements.php - AchievementUnlocked
app/Events/AchievementUnlocked.php - Badge evaluator
app/Listeners/EvaluateBadges.php - BadgeUnlocked
app/Events/BadgeUnlocked.php - Achievements API
app/Http/Controllers/AchievementController.php - Gamification state
app/Support/GamificationState.php - Gamification rules
config/gamification.php
Cashback and recovery
- Cashback dispatcher
app/Listeners/DispatchCashback.php - Cashback job
app/Jobs/DispatchCashbackJob.php - Paystack client
app/Services/Paystack/PaystackClient.php - Payout sweeper
app/Console/Commands/ReconcilePayouts.php - Paystack webhook
app/Http/Controllers/PaystackWebhookController.php
State and ledger
- Purchase, unlock, payout records
app/Models/Payout.php
Other components
- Customer
- Paystack
- Transfer webhook
Connections 29
- Customer → Purchase API: submits purchase
- Purchase API → Purchase, unlock, payout records: records purchase
- Purchase API → PurchaseCompleted: dispatches
- Event wiring → Achievement evaluator: registers listener
- Event wiring → Badge evaluator: registers listener
- Event wiring → Cashback dispatcher: registers listener
- PurchaseCompleted → Achievement evaluator: triggers
- Achievement evaluator → Gamification rules: reads thresholds
- Achievement evaluator → Purchase, unlock, payout records: records unlock
- Achievement evaluator → AchievementUnlocked: dispatches
- AchievementUnlocked → Badge evaluator: triggers
- Badge evaluator → Gamification rules: reads thresholds
- Badge evaluator → Purchase, unlock, payout records: records badge
- Badge evaluator → BadgeUnlocked: dispatches
- BadgeUnlocked → Cashback dispatcher: triggers
- Cashback dispatcher → Cashback job: queues payout
- Cashback job → Purchase, unlock, payout records: updates payout
- Cashback job → Paystack client: requests transfer
- Paystack client → Paystack: transfers or verifies
- Payout sweeper → Purchase, unlock, payout records: finds pending payouts
- Payout sweeper → Paystack client: verifies transfer
- Payout sweeper → Cashback job: requeues failed payout
- Transfer webhook → Paystack webhook: posts callback
- Paystack webhook → Purchase, unlock, payout records: settles payout
- Paystack webhook → Cashback job: requeues failure
- Customer → Achievements API: requests state
- Achievements API → Gamification state: builds response
- Gamification state → Gamification rules: reads rules
- Gamification state → Purchase, unlock, payout records: reads unlocks