Architecture Reference

System architecture

Order Daemon is a rules-driven automation layer on top of WooCommerce. It listens to order and external events, evaluates configurable rules (triggers + conditions), and executes actions. All activity is recorded as structured timelines.

classDiagram
    class Plugin {
        +bootstrap()
        +register_post_type()
        +initialize_core()
        +initialize_admin_components()
        +initialize_api_endpoints()
    }

    class Core {
        +init()
        +handle_payment_complete()
        +handle_order_status_change()
        +schedule_completion_check()
    }

    class UniversalEvent {
        +eventType
        +sourceGateway
        +primaryObjectType
        +primaryObjectID
        +components
    }

    class UniversalEventProcessor {
        +processEvent()
        +evaluateRules()
        +executeActions()
    }

    class RuleComponentRegistry {
        +get_triggers()
        +get_conditions()
        +get_actions()
        +register_component()
    }

    class GuardChecker {
        +check(Guard, context)
    }

    Plugin --> Core : Initializes
    Plugin --> UniversalEventProcessor : Uses
    Core --> UniversalEvent : Creates
    UniversalEventProcessor --> RuleComponentRegistry : Uses
    Plugin --> GuardChecker : Uses for security
    Core --> GuardChecker : Uses for security

Event processing flow

sequenceDiagram
    participant WooCommerce
    participant Core
    participant UniversalEventProcessor
    participant RuleRegistry
    participant AuditLog

    WooCommerce->>Core: woocommerce_payment_complete(order_id)
    Core->>Core: synthesize_payment_complete_event()
    Core->>UniversalEventProcessor: processEvent(universal_event)
    UniversalEventProcessor->>RuleRegistry: get_matching_rules()
    RuleRegistry-->>UniversalEventProcessor: matching_rules
    UniversalEventProcessor->>UniversalEventProcessor: evaluate_conditions()
    UniversalEventProcessor->>UniversalEventProcessor: execute_actions()
    UniversalEventProcessor->>AuditLog: log_event()

Core component groups

1. Bootstrap

Plugin.php – Main entry point; controlled initialization sequence; registers CPT, loads options, initializes Core/admin/REST.
Installer.php – Database schema management and version upgrades.
Custom post type odcm_order_rule registered early (priority 5) to prevent race conditions.

2. Universal events

UniversalEvent – Standardized event envelope with real timestamps, gateway source, primary object type/ID.
UniversalEventProcessor – Central event processing pipeline: match rules → evaluate conditions → execute actions → log.
Event adapters – Gateway-specific adapters normalize external webhooks into UniversalEvent objects.

3. Rule engine

RuleComponentRegistry – Discovers and manages triggers, conditions, and actions.
Evaluator – Rule matching and condition evaluation.
ActionExecutor – Safe action execution with error handling.

4. Security

GuardChecker – Central guard execution with audit logging.
CapabilityGuard – Role-based access control.
NonceGuard – Request CSRF validation.

See Security guards for usage examples.

5. Logging and audit

ProcessLogger – Structured timeline logging.
AuditLogEndpoint – REST API for reading audit data.
odcm_log_event() – Public function for emitting structured audit events.

6. Fail-safe mechanisms

CheckoutCircuitBreaker – Prevents checkout failures if processing fails.
DuplicatePrevention – Idempotent operation handling (uses idempotency keys from gateway adapters).

Key classes and files

Class / file	Role
`src/Plugin.php`	Bootstrap, CPT registration, orchestration
`src/Core/Core.php`	WooCommerce hook listeners, event dispatch
`src/Core/Events/UniversalEvent.php`	Normalized event envelope
`src/Core/Events/UniversalEventProcessor.php`	Rule evaluation and action execution
`src/Core/RuleComponents/RuleComponentRegistry.php`	Component discovery and registry
`src/Core/RuleComponents/Interfaces/`	`TriggerInterface`, `ConditionInterface`, `ComponentInterface`
`src/Core/Security/GuardChecker.php`	Security execution + audit logging
`src/Includes/functions.php`	Public helper functions (`odcm_log_event`, etc.)
`src/API/RuleBuilderApiController.php`	Rule CRUD REST endpoints
`src/API/AuditLogEndpoint.php`	Audit/Insight timeline REST endpoints
`src/API/WebhookController.php`	Inbound webhook receiver

Extension points

Extension type	How
Custom rule components	Implement `TriggerInterface`, `ConditionInterface`, or `ActionInterface`; register via `odcm_register_components`
Custom event sources	Build a class extending `AbstractGatewayAdapter`; register via `odcm_register_gateway_adapters`
REST API extensions	Add endpoints via `rest_api_init`; use the guard system for security
Audit log entries	Call `odcm_log_event()` from anywhere

Navigation