Athenian Data Intelligence

Fleet parity boundary

The reviewed local source baseline is ADI 0.2.9, but the active Athenian Spa deployment reports version 0.1.0 and main-file SHA-256 c59a36193c12a6ef781cfc29fc85b1ed1ec387efd947d3e72a6cbe240924fa92. Treat the local repository commit as a source baseline, not as the deployed runtime identity, until a normalized tree comparison is completed.

Developer starting point

This baseline documents Data Intelligence collection and dashboard architecture. It does not claim historical completeness, AI-provider success, or production reporting correctness.

Technical Architecture

File Structure

athenian-data-intelligence.php
assets/
  admin.css
  admin.js
  vendor/chart.umd.min.js
dashboards/
  ai.json
  credits.json
  customers.json
  executive.json
  financial.json
  marketplace.json
  openai.json
  operations.json
  platform.json
  swap-shop.json
  vendors.json
docs/
  adi-marketing-document.md
includes/
  Autoload.php
  Plugin.php
  API/
    GraphQL.php
    REST.php
  Admin/
    Admin.php
  Core/
    Alerts.php
    Collector.php
    DB.php
    OpenAIReports.php
    Registry.php
    Rollups.php
    AI/
      Pricing.php
    Capture/
      APCAI.php
      Credits.php
      OpenAI.php
      OwlPay.php
      WooCommerce.php

Boot Flow

The main plugin file defines constants, loads includes/Autoload.php, and starts \Athenian\ADI\Plugin::instance().

Plugin::boot() initializes:

1. Registry
2. Database upgrade checks
3. Collector
4. Rollups
5. OpenAI report sync
6. WooCommerce capture
7. OpenAI HTTP capture
8. APC AI capture
9. Credits capture
10. OwlPay capture
11. REST routes
12. WPGraphQL routes, when available
13. Admin UI, when in the WordPress admin

Database Tables

ADI creates three custom tables.

#### wp_adi_events

Stores raw event records.

Important columns:

• id
• ts
• event_key
• site_id
• actor_id
• object_type
• object_id
• dim_vendor_id
• dim_customer_id
• amount
• currency
• meta

Indexes support event/time queries, object references, vendor dimensions, and customer dimensions.

#### wp_adi_rollups_daily

Stores daily metric rollups.

Important columns:

• day
• metric_key
• site_id
• dim_vendor_id
• dim_product_id
• dim_customer_id
• value_sum
• value_count
• value_min
• value_max
• extra

The table includes a unique key across day, metric, site, vendor, product, and customer dimensions.

#### wp_adi_alert_runs

Stores alert evaluation history.

Important columns:

• ran_at
• alert_key
• status
• message
• meta

---

Credits and Payout Integration

Credits Capture

ADI listens to credit-related hooks:

• cpm_credit_transaction_recorded
• cpm_credit_balance_changed
• ath_credits_deducted
• ath_credits_added

It classifies credit events into purchases, spend, refunds/reversals, cashouts, and AI-related spend.

OwlPay Capture

ADI listens to OwlPay ledger hooks:

• ath_owlpay/ledger/entry_created
• ath_owlpay/ledger/entry_updated

It records payout entries and classifies them as held or released based on availability timing. When a previously held entry becomes available, ADI records a release metric.

---

Developer Integration Guide

Record a Custom ADI Event

do_action('ath_adi_event', 'custom.metric.key', [
    'amount' => 1,
    'meta'   => [
        'source' => 'my-plugin',
        'note'   => 'Custom event payload',
    ],
    'dims'   => [
        'vendor_id'   => 123,
        'customer_id' => 456,
    ],
    'ctx'    => [
        'object_type' => 'custom_object',
        'object_id'   => 789,
    ],
]);

Register Custom Metrics or Dashboards

add_action('ath_adi_register', function ($registry_class) {
    $registry_class::register_metric([
        'key'         => 'my.metric.total',
        'label'       => 'My Metric',
        'type'        => 'count',
        'unit'        => '',
        'dimensions'  => ['site', 'vendor', 'customer'],
        'source'      => 'my-plugin',
        'description' => 'A custom metric emitted by my plugin.',
    ]);

    $registry_class::register_dashboard('my-dashboard', [
        'id'     => 'my-dashboard',
        'label'  => 'My Dashboard',
        'kpis'   => [
            ['metric' => 'my.metric.total', 'label' => 'My Metric'],
        ],
        'charts' => [
            [
                'metric'      => 'my.metric.total',
                'label'       => 'My Metric Trend',
                'type'        => 'line',
                'description' => 'Custom metric over time.',
            ],
        ],
    ]);
});

Provide Order Cost Data

add_filter('ath_adi_order_cost_total', function ($cost, $order) {
    // Return a numeric cost total to enable ADI margin reporting.
    return $cost;
}, 10, 2);

Control OpenAI Host Detection

add_filter('ath_adi_is_openai_host', function ($is_openai, $host, $url) {
    if ($host === 'my-openai-proxy.example.com') {
        return true;
    }
    return $is_openai;
}, 10, 3);

Disable HTTP Count or Usage Rollups When APC AI Handles Counts

add_filter('ath_adi_openai_http_counts_enabled', '__return_false');
add_filter('ath_adi_openai_http_usage_enabled', '__return_false');

Control Rollup Eligibility

add_filter('ath_adi_should_rollup_metric', function ($should, $metric_key, $event_row) {
    if ($metric_key === 'custom.lifecycle.event') {
        return false;
    }
    return $should;
}, 10, 3);

---

Security and Permissions

ADI uses WordPress capabilities to protect analytics access:

• Dashboard REST access requires manage_woocommerce or manage_options.
• Admin settings require manage_woocommerce or manage_options.
• OpenAI credential configuration is restricted to manage_options users.
• Admin settings submissions use WordPress nonces.
• REST dashboard requests use a localized REST nonce.
• OpenAI URLs are redacted before storage to avoid persisting sensitive query parameters.
• Internal OpenAI report requests use X-ATH-ADI-Internal so they are not counted as regular OpenAI app usage.

---

Notable Implementation Details

• The plugin header lists version 0.1.0, while ATH_ADI_VERSION is set to 0.2.0; this should be normalized before packaging a formal release.
• Rollup cron registration exists through the ath_adi_cron_rollups hook, but activation currently schedules OpenAI report cron rather than explicitly scheduling rollup cron in the inspected code.
• Alerts include an evaluator class and settings UI, but the inspected boot sequence does not show a scheduled alert runner calling Alerts::evaluate() automatically.
• Some dashboard areas are forward-looking and become more valuable when upstream plugins emit the associated metrics, especially marketplace, vendor, platform, and Swap Shop metrics.
• OpenAI cost estimation depends on configured pricing JSON or filter-provided pricing tables.
• OpenAI report sync requires appropriate OpenAI Admin/organization credentials and, for Codex workspace analytics, a valid workspace ID and analytics key.
• The REST summary endpoint is deterministic and not currently an AI-generated narrative.

---