Future: bbDKP point storage on bbAccounts ledger

[avandenberghe]

Context

avatharbe/bbDKP currently stores DKP points in fixed-column tables (memberdkp, adjustments) inherited from EQDKP. This was identified as fundamentally flawed in avatharbe/bbDKP#1 — the original issue that inspired bbAccounts.

Long-term goal: replace bbDKP's point storage with bbAccounts journal entries. bbDKP keeps raid management, item tracking, and game-specific features; bbAccounts owns the ledger.

Current bbDKP Architecture

• memberdkp table — one row per member per DKP pool, columns for each point type (member_earned, member_spent, member_adjustment, member_time_bonus, etc.)
• adjustments table — manual point corrections
• items table — loot distribution records (stays)
• raids / raiddetail tables — raid events and attendance (stays)
• Balance = earned − spent + adjustments (computed from columns, not transactions)

Problems (from bbDKP#1)

• New point type = new column
• Deleting a raid requires recalculating every participant's earned total
• No per-raid breakdown of time-based earnings (join/leave time varies per member)
• No audit trail of individual point mutations

Target Architecture

bbDKP (raid management, items, game integration)
  └── depends on → bbAccounts (ledger)

What stays in bbDKP:

• Raid creation/management
• Raid attendance tracking
• Item/loot distribution
• Game-specific modules (WoW, FFXIV, etc.)
• DKP pool configuration

What moves to bbAccounts:

• All point storage → journal entries
• All balance queries → subledger balances
• Adjustments → manual journal entries

How bbDKP calls bbAccounts:

Raid earned (member avatharbe/bbAccounts-dev#42 earns 10 DKP for raid attendance):

DR  5100 DKP Earned — Raids        10.00
CR  2300 Member DKP Balance         10.00  (subledger: user avatharbe/bbAccounts-dev#42)

Item purchased (member avatharbe/bbAccounts-dev#42 spends 25 DKP on item):

DR  2300 Member DKP Balance         25.00  (subledger: user avatharbe/bbAccounts-dev#42)
CR  4100 DKP Spent — Items          25.00

Time bonus (member avatharbe/bbAccounts-dev#42, based on raid duration):

DR  5110 DKP Earned — Time Bonus    3.50
CR  2300 Member DKP Balance          3.50  (subledger: user avatharbe/bbAccounts-dev#42)

Manual adjustment:

DR  5120 DKP Adjustments           15.00
CR  2300 Member DKP Balance         15.00  (subledger: user avatharbe/bbAccounts-dev#42)

Deleting a raid = reversing entry for every participant's original earned entry. Clean, auditable, no recalculation needed.

EP/GP ratio = derived from SELECT SUM(debit), SUM(credit) on the relevant accounts, filtered by subledger_user_id.

Multiple DKP Pools

Each DKP pool could map to its own set of subledger control accounts (e.g., 2300 Pool A — Member Balance, 2310 Pool B — Member Balance), or use a dimension/tag on journal lines. TBD.

Prerequisites

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

Priority

Future milestone. Tracked here for architectural alignment — this is the original use case that inspired the whole system.

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 implementation starts.

Decision

bbDKP integrates with bbAccounts via a direct service call: bbDKP injects @avathar.bbaccounts.service.ledger and calls ledger::create_entry() synchronously when raids/loot/adjustments happen. Each call namespaces the entry through reference_source (bbdkp.raid_attendance, bbdkp.item_purchase, bbdkp.time_bonus, bbdkp.adjustment, etc.) so cross-extension audit trails stay unambiguous.

Why direct, not events

• Preserves source-agnostic principle. bbAccounts ships no bbDKP-specific code or listeners. The integration logic lives entirely on the bbDKP side — exactly the contract bbAccounts has documented since Phase 1. Putting bbdkp.* event listeners inside bbAccounts would invert that.
• Transactional correctness. A raid save and its journal entries need to be in the same DB transaction — partial commits would let DKP balances drift from the raid history. Synchronous service calls fit naturally inside bbDKP's own sql_transaction. Event dispatchers don't give that guarantee out of the box.
• Failure surface stays local. If create_entry() rejects (unbalanced, inactive account, etc.), the raid save fails as a whole — admin gets one error, not a divergent state where the raid exists but the points don't.

Where events still belong

bbDKP should emit events around its own ledger writes — bbdkp.before_post_journal, bbdkp.after_post_journal (with journal_id) — so third-party extensions (analytics, notifications, audit dashboards) can observe without bbDKP knowing about them. That's the right side of the inversion: bbDKP is the source of truth for "raid attendance was recorded," and consumers subscribe to that.

bbAccounts itself does NOT subscribe to those events. Anyone who wants to observe a journal write subscribes to the bbAccounts-side events on ledger::create_entry() (which already exist for the post-write path, or can be added there if not — that's a separate, source-agnostic concern).

Implementation shape on the bbDKP side

// bbdkp/services/raid_writer.php (sketch)
public function record_attendance(int $raid_id, int $user_id, string $dkp_amount): void
{
    $this->db->sql_transaction('begin');
    try {
        // existing bbDKP raid/attendance writes …
        $this->ledger->create_entry(
            $raid->event_date,
            sprintf('Raid #%d attendance', $raid_id),
            [
                ['account_id' => $this->cfg['dkp_earned_raids_id'], 'debit'  => $dkp_amount, 'credit' => '0.00', 'subledger_user_id' => 0],
                ['account_id' => $this->cfg['member_dkp_balance_id'], 'debit' => '0.00',     'credit' => $dkp_amount, 'subledger_user_id' => $user_id],
            ],
            'auto',                          // reference_type
            $raid_id,                        // reference_id
            'bbdkp.raid_attendance',         // reference_source
            (int) $this->user->data['user_id']
        );
        $this->dispatcher->dispatch('bbdkp.after_post_attendance', $raid_id, $user_id, $dkp_amount);
        $this->db->sql_transaction('commit');
    } catch (\Throwable $e) {
        $this->db->sql_transaction('rollback');
        throw $e;
    }
}

Reverting a raid = bbDKP iterates its own bbdkp.raid_attendance reference rows in bbaccounts_journal for that raid_id and calls ledger::reverse_entry() on each. Clean audit trail, no recalculation.

Implications for sub-tickets

When this epic gets decomposed:

• bbDKP-side tasks: chart-of-accounts seed (the DKP accounts above), config keys for the account_id → role mapping, raid/loot/adjustment write paths refactored to call the ledger service, migration that backfills existing memberdkp totals as opening-balance entries.
• bbAccounts-side tasks: none that are bbDKP-specific. If anything bbAccounts-side surfaces from this work, it's a generic gap (e.g. a hook some integration needs that doesn't exist yet) — file as a separate ticket.

cc #2 (point-sources architecture) — the same pattern applies for ultimatepoints (#3) and any future source.