Athenian Role Management

Developer starting point

This baseline was generated from the local athenian-role-management source folder and the linked product record. The source folder is the reviewed implementation boundary for this pass; runtime behavior and repository commit identity should be reconciled before treating this as release-grade API reference.

Technical Architecture

Bootstrap Flow

The main plugin file defines constants and loads the core classes:

define( 'ARM_VERSION', '0.2.1' );
define( 'ARM_FILE', __FILE__ );
define( 'ARM_DIR', plugin_dir_path( __FILE__ ) );
define( 'ARM_URL', plugin_dir_url( __FILE__ ) );

On plugins_loaded, the plugin boots:

• Athenian\RoleManagement\Plugin
• Athenian\RoleManagement\Role_Discounts
• Athenian\RoleManagement\Admin\Role_Discounts_Admin
• Athenian\RoleManagement\REST\Rest_Role_Discount_Endpoint

Main Classes

| Class | Namespace | Responsibility | |---|---|---| | Plugin | Athenian\RoleManagement | Core loader, activation defaults, admin/AJAX dependency loading. | | Admin | Athenian\RoleManagement | Registers the Role Management admin menu, enqueues admin assets, adds plugin action links. | | Admin_Page | Athenian\RoleManagement | Renders the main Users → Role Management screen and JSON bootstrap payload. | | Ajax | Athenian\RoleManagement | Handles role lifecycle, capability updates, user search, user assignment, import/export, audit, and settings AJAX. | | Util | Athenian\RoleManagement\Lib | Capability checks, nonce utilities, role accessors, sanitization, capability grouping, audit logging. | | Role_Discounts | Athenian\RoleManagement | Stores, normalizes, resolves, and exposes role discount rules. | | Role_Discounts_Admin | Athenian\RoleManagement\Admin | Renders WooCommerce Role Discounts admin page and AJAX product/term search. | | Rest_Role_Discount_Endpoint | Athenian\RoleManagement\REST | Registers legacy /ath-pricing/v1/role-discount endpoint. |

File Structure

athenian-role-management.php
includes/
  class-arm-plugin.php
  class-role-discounts.php
  lib/
    util.php
  admin/
    class-admin.php
    class-admin-page.php
    class-ajax.php
    class-role-discounts-admin.php
  rest/
    class-rest-role-discount-endpoint.php
assets/
  admin.css
  admin.js
  admin/
    arm-admin.css
    arm-admin.js
docs/
  athenian-role-management-marketing-document.md
  athenian-platform-marketing.md
  athenian-platform-technical.md

Syntax Review

A PHP lint pass was run against all PHP files in the ZIP. No syntax errors were reported.

---

WordPress Hooks and Integration Points

Actions

| Hook | Purpose | |---|---| | plugins_loaded | Boots plugin services after WordPress plugins load. | | admin_menu | Adds Role Management and Role Discounts admin pages. | | admin_enqueue_scripts | Enqueues CSS/JS for admin screens. | | admin_init | Registers settings and handles Role Discounts save submissions. | | rest_api_init | Registers the legacy role-discount REST route. |

AJAX Actions

| AJAX Action | Purpose | |---|---| | arm_get_roles | Return roles, capability groups, and settings. | | arm_create_role | Create a new role, optionally from a base role. | | arm_clone_role | Clone an existing role to a new role key/name. | | arm_rename_role | Rename an existing role. | | arm_delete_role | Delete a non-protected role. | | arm_update_caps | Replace a role’s capability map with the selected grants. | | arm_search_users | Search users by login, email, or display name. | | arm_apply_role | Add or replace roles for selected users. | | arm_export | Export role definitions as arm_roles_v1 JSON. | | arm_import | Import role definitions in merge or replace mode. | | arm_get_audit | Return recent audit entries. | | arm_clear_audit | Clear the audit log. | | arm_save_settings | Save audit and safety settings. | | arm_role_discount_search_products | Search products/variations for discount targeting. | | arm_role_discount_search_terms | Search product categories or tags for discount targeting. |

Filters

| Filter | Purpose | |---|---| | ath/apc/role_discount_for_price | Canonical Athenian Platform role-discount lookup used by pricing consumers. | | plugin_action_links_{plugin} | Adds an “Open” link from the Plugins screen to the Role Management admin page. |

REST Route

| Route | Method | Authentication | Purpose | |---|---|---|---| | /wp-json/ath-pricing/v1/role-discount | GET | Logged-in users only | Returns the current user’s roles and resolved discount. |

---

Data Model and Storage

Options

| Option | Purpose | |---|---| | arm_settings | Stores audit and danger-confirmation settings. | | arm_audit_log | Stores recent audit entries. | | arm_role_discounts_v2 | Preferred scoped role-discount rules. | | arm_role_discounts | Legacy v1 role-to-percent discount map. | | ath_pricing_tiers_role_discounts | Legacy fallback discount option. | | apt_role_discounts | Legacy Athenian Pricing Tiers fallback discount option. |

Role Export Format

ARM exports role definitions with this top-level structure:

{
  "format": "arm_roles_v1",
  "site": {
    "url": "https://example.com",
    "name": "Example Site",
    "generated_at": "2026-07-01T00:00:00+00:00"
  },
  "roles": {
    "custom_role": {
      "name": "Custom Role",
      "capabilities": {
        "read": true,
        "upload_files": true
      }
    }
  }
}

Role Discount v2 Rule Shape

[
    'wholesale_customer' => [
        'enabled'  => true,
        'percent'  => 10.0,
        'priority' => 50,
        'scope'    => [
            'include' => [
                'products'   => [123],
                'categories' => [10],
                'tags'       => [7],
            ],
            'exclude' => [
                'products'   => [],
                'categories' => [],
                'tags'       => [],
            ],
        ],
    ],
]

Scope Behavior

• Exclude rules always win.
• Product ID and parent product ID are both considered.
• Product category and product tag matches check both the product and parent product where relevant.
• If no include buckets are configured, the rule behaves as a global rule unless excluded.
• If any include bucket is configured, the product must match at least one include bucket.

---

Security and Permissions

Main Role Management Permissions

The main role management UI is added under the Users menu with the promote_users capability. Internal permission checks allow users who can either manage_options or promote_users.

Role Discount Permissions

The WooCommerce role-discount screen requires:

manage_woocommerce

The discount product and term search AJAX handlers also require manage_woocommerce and validate a dedicated nonce.

Request Protection

• Admin AJAX actions validate the arm_nonce nonce.
• Role Discount save actions use check_admin_referer().
• REST discount lookup requires is_user_logged_in().
• Input values are sanitized using WordPress helpers such as sanitize_key(), sanitize_text_field(), wp_unslash(), and normalization methods.
• The administrator role is protected from deletion by the plugin UI/API.

Safety Notes

Role/capability editors can affect access to the site. ARM includes a danger-confirmation setting and audit logging, but production operators should still test role changes carefully in staging before applying them to critical admin roles.

---

WooCommerce and Athenian Platform Integration

WooCommerce Integration

ARM integrates with WooCommerce primarily through the Role Discounts admin screen and product/taxonomy-aware discount scoping.

The plugin can search and target:

• Products.
• Product variations.
• Product categories.
• Product tags.

The role-discount logic does not appear to directly replace WooCommerce price display or cart totals by itself. Instead, it exposes a discount decision through the Athenian filter contract so a pricing layer such as Athenian Platform Core / PriceDelegate can consume the result and apply pricing behavior consistently.

Athenian Platform Compatibility

ARM preserves compatibility with Athenian pricing flows through:

ath/apc/role_discount_for_price

and:

/wp-json/ath-pricing/v1/role-discount

This allows ARM to operate as a focused role-discount policy source while broader pricing plugins decide how and where to apply the resolved discount.

Legacy Pricing Compatibility

ARM checks multiple storage locations for legacy role-discount definitions:

• arm_role_discounts
• ath_pricing_tiers_role_discounts
• apt_role_discounts

That makes the plugin useful in environments migrating from earlier Athenian Pricing Tiers or custom role-discount implementations.

---

Implementation Notes and Caveats

• The main plugin is version 0.2.1.
• The primary role-management screen is registered under the Users menu as users.php?page=athenian-role-management.
• The Role Discounts page is registered under WooCommerce as admin.php?page=arm-role-discounts.
• The Role Discounts system stores preferred v2 rules in arm_role_discounts_v2 while retaining legacy fallback behavior.
• The plugin exposes role discounts through a filter and REST endpoint; direct price replacement/cart recalculation should be handled by a consuming pricing layer.
• The role import flow can rename existing roles and merge or replace capabilities, so imports should be tested before production use.
• Capability updates remove all existing caps for a role and then re-add the submitted grants. This makes the submitted capability map authoritative.
• The administrator role is protected from deletion, but administrators should still be careful when editing capabilities for high-privilege roles.
• A PHP lint pass found no syntax errors in the included PHP files.

---