Architecture¶

Module overview¶

The package is bootstrapped by AnnualRecurringRevenue (uses the Module singleton trait from base-plugin). It wires up four subsystems:

Class	Role
`SubscriptionWatcher`	Listens to WooCommerce/WordPress hooks and registers subscriptions to be observed
`ScheduledCalculations`	Runs deferred ARR recalculations via WP-Cron
`AddonProducts`	Adjusts ARR when subscription add-on products are added or removed
`RecurringCoupons`	Adjusts renewal totals when recurring coupons are applied
`Migrator`	Runs database migrations on init

Data flow¶

sequenceDiagram
    participant WC as WooCommerce/WordPress hooks
    participant SW as SubscriptionWatcher
    participant SWM as SubscriptionWatchObjectMap
    participant SWO as SubscriptionWatchObject
    participant CALC as CalculatorHelper
    participant LOG as Log (DB)

    WC->>SW: Hook fires (save / status change / meta update)
    SW->>SWM: watch($subscription)
    SWM-->>SWO: Creates or returns existing watch object
    SWO->>SWO: Snapshots current ARR
    Note over SWO: On shutdown / scheduled job
    SWO->>CALC: calculate_arr($subscription)
    CALC-->>SWO: new ARR value
    SWO->>LOG: Persists Log + Reasons + Contexts if ARR changed

Key filter hooks¶

Hook	Purpose
`arr/calculate/args`	Modify calculation arguments before renewals are projected
`arr/calculate/renewal-totals`	Modify the array of projected renewal totals (e.g. apply coupons)