Architecture¶

Overview¶

The plugin follows a service-container pattern built on top of league/container. The entry point is woocommerce-klaviyo.php, which bootstraps the Klaviyo singleton (via the Module trait from barberklingen/base-plugin) and delegates all wiring to KlaviyoServiceProvider.

woocommerce-klaviyo.php
└── Klaviyo (singleton)
    └── KlaviyoServiceProvider
        ├── ActionSchedulerProvider
        ├── AjaxProvider
        ├── BackendProvider
        ├── EventProvider
        ├── ExtensionsProvider
        ├── PrivacyProvider
        ├── TrackingProvider
        └── WatchersProvider

Key modules¶

Module	Location	Responsibility
Watchers	`inc/Watchers/`	Listen to WooCommerce/WordPress hooks and schedule events
Events	`inc/Events/`	Event definitions, registry, and scheduler API
Action Scheduler	`inc/ActionScheduler/`	Async dispatch of scheduled events to Klaviyo
API	`inc/API/`	Klaviyo API v3 client (profiles, events, lists, consent)
Storage	`inc/Storage/EventModel.php`	ORM model for the `klaviyo_events` queue table
Backend	`inc/Backend/`	WP-Admin order/subscription actions and WP-CLI commands
Trackers	`inc/Trackers/`	Client-side JS tracking (cart, checkout)
Privacy	`inc/Privacy/`	GDPR erasure/export via WordPress Privacy Tools
Extensions	`inc/Extensions/`	Optional integrations (card expiry, renewal discounts, application status)

Event scheduling flow¶

sequenceDiagram
    participant Hook as WP/WC Hook
    participant Watcher as Watcher
    participant Scheduler as EventSchedulerAPI
    participant DB as klaviyo_events table
    participant AS as Action Scheduler
    participant API as Klaviyo API v3

    Hook->>Watcher: order_status_changed / subscription_* / …
    Watcher->>Scheduler: schedule(event_name, entity_id, …)
    Scheduler->>DB: INSERT (deduplication via UNIQUE KEY)
    AS-->>DB: pick up pending events (async)
    DB-->>AS: EventModel rows
    AS->>API: POST /events or /profiles
    API-->>AS: 200 OK
    AS->>DB: DELETE processed row