Files
wp-donations/docs/ARCHITECTURE.md
T

3.9 KiB
Raw Permalink Blame History

StreamGoals Donate — Architecture Contract

Target: WordPress 7.x, PHP 8.1+. Single streamer per install. Built/deployed from Gitea (zip artifact, no runtime Composer). Namespace StreamGoals\, PSR-4 rooted at includes/. Text domain streamgoals-donate. Table prefix {$wpdb->prefix}sg_.

Ground rules

  • Money is integer minor units (cents) plus an ISO-4217 currency. Never floats. Zero-decimal currencies (JPY) handled via Core\Money.
  • Pure logic has no WordPress dependency (Core\Money, Core\FeeCalculator, Rules\*) so it is unit-testable with plain PHPUnit.
  • WordPress-touching code (DB, REST, admin) sits behind small classes; escape all output, check capabilities (manage_options), nonces on admin posts.
  • Public endpoints are rate-limited and never expose the real name of an anonymous donor.

Directory ownership (to avoid merge conflicts between agents)

Path Owner
includes/Core/*, streamgoals-donate.php, docs/ARCHITECTURE.md Foundation (done first)
includes/PayPal/*, includes/Rest/DonateController.php, includes/Rest/WebhookController.php, assets/donate/* Agent 1: PayPal + donate flow
includes/Rules/*, includes/Core/GoalRepository.php consumers, tests/Unit/Rules* Agent 2: Goals + rules engine
includes/Overlay/*, includes/Rest/OverlayController.php, assets/overlay/* Agent 3: Overlays
includes/Admin/*, assets/admin/* Later phase (wizard/admin UI)

Database (created by Core\Installer, version in option sg_db_version)

  • sg_goals: id, title, target_minor, currency, status(active|paused|complete), starts_at, ends_at NULL, counts_fees TINYINT(0 = base amount only), created_at
  • sg_donations: id, goal_id, paypal_order_id, paypal_capture_id UNIQUE, base_minor, fee_minor, total_minor, currency, donor_name, is_anonymous, message, status(pending|completed|refunded|reversed), moderation(approved|pending|rejected), created_at
  • sg_rules: id, goal_id, type(add_time|counter|bonus), config JSON, enabled, sort
  • sg_rule_events: id, rule_id, donation_id, delta (seconds or count), reversed TINYINT, created_at — UNIQUE(rule_id, donation_id) for idempotency
  • sg_state: goal_id, key, value — timer ends_at, counter totals, carry-over remainders
  • Options: sg_settings (paypal mode/client_id/secret, fee rates, moderation, anonymity policy, overlay token)

Core interfaces (all in includes/Core)

Money::fromDecimalString(string $amount, string $currency): Money;  // "10.50" -> 1050
FeeCalculator::grossUp(int $baseMinor, FeeRates $rates): int;       // total so recipient nets base
// total = ceil((base + fixed) / (1 - pct))  — rates configurable, default US 3.49% + 49c

Rules engine entry point (Agent 2 implements, Agent 1 calls after a capture is recorded and on refund):

Rules\Engine::applyDonation(Donation $d): void;   // idempotent via sg_rule_events UNIQUE
Rules\Engine::reverseDonation(Donation $d): void; // honors per-rule "reverse on refund"

Rule config examples:

{"type":"add_time","seconds_per_unit":60,"unit_minor":100,"cap_seconds_per_donation":null,"max_total_seconds":null,"basis":"base"}
{"type":"counter","step":1,"per_minor":1000,"carry_over":true,"basis":"base","label":"Pies"}
{"type":"bonus","min_minor":5000,"event":"big_donation"}

Public REST (namespace streamgoals/v1)

  • POST /orders (create order; server computes total incl. optional fee cover), POST /orders/{id}/capture
  • POST /webhook (PayPal signature verified; deduped by capture id)
  • GET /overlay/{token}/{widget} — ETag'd JSON, polled every 2–3 s; widgets: goal, timer, counter, alerts

Fee cover

A toggle on the donate form (default off). Form shows exact total before payment. Goal counts base amount by default (counts_fees per goal).

Defaults

Currency USD (configurable per goal). Sandbox mode is the default until the owner switches to Live.