Future: ultimatepoints as gamification layer on bbAccounts

[avandenberghe]

Context

dmzx/ultimatepoints currently handles both point storage and gamification (lottery, robbery, bonus) in a single extension with its own user_points column and points tables.

Long-term goal: gut ultimatepoints to only keep its gamification features (lottery, robbery, bonus) and have it depend on bbAccounts for all point storage and balance management.

Current UP Architecture

• user_points column on phpbb_users — updated in-place
• points_bank table — separate bank balances
• points_log table — transaction log (but not source of truth)
• points_values table — configuration
• points_lottery_* tables — lottery state
• Core functions: add_points(), substract_points() — direct UPDATE on user_points

Target Architecture

ultimatepoints (gamification only)
  └── depends on → bbAccounts (ledger)

What stays in UP:

• Lottery module (ticket purchase, draw, jackpot)
• Robbery module (attempt, success/fail, notifications)
• Bonus module (random chance on activity)
• Gamification-specific ACP settings
• Gamification-specific permissions

What moves to bbAccounts:

• All point storage → journal entries
• All balance queries → ledger service get_subledger_balance()
• Bank/savings → reclassification between liability control accounts
• Transfers → reclassification + fee revenue
• Transaction logs → subledger statement
• Forum point earning → separate source module

How UP calls bbAccounts:

Lottery win (user avatharbe/bbAccounts-dev#42 wins 500 jackpot):

DR  5060 Lottery Expense           500.00
CR  2100 User Wallets — Cash       500.00  (subledger: user avatharbe/bbAccounts-dev#42)

Robbery success (user avatharbe/bbAccounts-dev#42 steals 50 from user #99):

DR  2100 User Wallets — Cash        50.00  (subledger: user #99)
CR  2100 User Wallets — Cash        50.00  (subledger: user avatharbe/bbAccounts-dev#42)

Ticket purchase (user avatharbe/bbAccounts-dev#42 buys ticket for 10):

DR  2100 User Wallets — Cash        10.00  (subledger: user avatharbe/bbAccounts-dev#42)
CR  4030 Lottery Ticket Revenue      10.00

Prerequisites

• bbAccounts Phase 1 complete (Point sources: what generates journal entries? #1)
• Ledger service API stable
• Migration path for existing UP data → journal entries

Open Questions

• Fork UP or contribute upstream?
• Data migration strategy for existing UP installations
• Which UP version to base the rewrite on

Priority

This is a future milestone, not part of bbAccounts Phase 1. Tracked here for architectural alignment.

Tasks

Decomposition deferred until Phase 2 closes. The Phase 3 plan will be drafted after #2 (point-sources architectural decision) lands; that decision shapes the source-adapter interface every Phase 3 task will build on.

• (to be filed once Phase 3 is planned — contrib/plans/ will get a bbaccounts-phase3-plan.md)

[avandenberghe]

Integration pattern: direct service call (not events)

Capturing the decision before this gets decomposed into PR-sized tickets. Anchors on the scope already in this issue body — UP stays as a single gamification extension, all storage moves to bbAccounts.

Decision

ultimatepoints integrates with bbAccounts via a direct service call, same shape as #4. The gamification modules (lottery / robbery / bonus) inject @avathar.bbaccounts.service.ledger and call ledger::create_entry() synchronously inside their own DB transactions. Each call namespaces the entry through reference_source (ultimatepoints.lottery, ultimatepoints.robbery, ultimatepoints.bonus, ultimatepoints.transfer, etc.) so cross-extension audit trails stay unambiguous.

No events flow from UP → bbAccounts. UP can emit its own observability events (ultimatepoints.lottery.after_draw, etc.) for third parties; bbAccounts itself does not subscribe to anything UP-side.

Why direct, not events

• Source-agnostic principle. bbAccounts ships no UP-specific listeners. Integration logic lives entirely on the UP side.
• Transactional correctness. A lottery draw and the journal entries that move the jackpot need to be in the same DB transaction. Synchronous service calls fit naturally inside UP's own sql_transaction. Event dispatch doesn't give that guarantee.
• Local failure surface. If create_entry() rejects (unbalanced, inactive account), the gamification action fails as a whole — no divergent state where the UI says the lottery paid out but no journal entry exists.

What gets deleted from the legacy UP

Hard cut, no backward-compat shim. The existing scope already lists what moves to bbAccounts; the implementation-level deletions:

• phpbb_users.user_points column — dropped via migration
• points_bank, points_log, points_values tables — dropped (history backfilled into bbAccounts as opening-balance + per-row import entries)
• add_points() / substract_points() global functions — gone; every caller in UP goes through the ledger service
• Lottery state tables (points_lottery_*) — stay in UP since they're gamification state, not point storage

Migration utility

A one-shot migration step (lives in UP's own migration chain) backfills existing data:

• Each user's current user_points value → one opening-balance journal entry against the seeded "User Wallets" subledger account, with reference_type='import' and reference_source='ultimatepoints.legacy'.
• Each points_log row → one journal entry, same reference_source. Reference id is the original log row id so admins can reconcile.
• After migration verifies (sum of journal balances per user == old user_points value), the UP migration drops the legacy tables/column.

Open questions before decomposition

• Fork or upstream? dmzx maintains UP actively; an upstream PR that throws out half the extension is unlikely to land. Realistic path is fork-and-rename, point users at the fork. To resolve in the Phase 3 plan.
• Migration verification fail-stop. If sum-check mismatches mid-migration, what's the recovery? Probably refuse to drop legacy tables and surface a reconciliation tool — but worth deciding before the migrator is written.
• Bank/savings as separate accounts vs. a single wallet. Existing UP has points_bank separate from user_points. Modeling that in bbAccounts: one subledger account per "pocket" (Cash + Bank as separate liability accounts), or a single wallet with memo-tagged transfers? The first is more accountant-correct; the second is simpler for UP-style UI.

These get resolved in the Phase 3 plan doc, not in this issue.

cc #4 — same integration pattern; cc #2 — source-adapter interface this depends on.