Athenian Creator Manager

Developer starting point

This baseline is generated from the reviewed local technical reference and source folder. Deployed-version parity and external-provider effects remain separate verification steps.

7. Plugin Architecture

The plugin is organized as a modular WordPress plugin with a small bootstrap file and feature-specific service classes.

Bootstrap File

athenian-creator-manager.php defines plugin metadata, constants, class includes, activation hooks, and the main plugins_loaded bootstrap.

Important constants:

| Constant | Purpose | |---|---| | ACM_VERSION | Current plugin version, inspected as 0.2.4. | | ACM_PLUGIN_FILE | Main plugin file path. | | ACM_PLUGIN_DIR | Plugin directory path. | | ACM_PLUGIN_URL | Plugin asset URL. |

Main Classes

| Class | File | Responsibility | |---|---|---| | Install | class-acm-install.php | Activation, database table creation, default settings, rewrite flushing, upgrades. | | Plugin | class-acm-plugin.php | Main plugin bootstrap and admin asset enqueueing. | | Post_Types | class-acm-post-types.php | Registers creator CPT and attachment taxonomies. | | Relationships | class-acm-relationships.php | Shared creator relationship model across products, content, and media. | | Creator_Profile | class-acm-creator-profile.php | Creator social/location profile fields. | | Creators_Admin | class-acm-creators-admin.php | Creator admin workspace, settings, columns, metaboxes. | | Commissions_Admin | class-acm-commissions-admin.php | Commission ledger admin screen and paid/unpaid bulk actions. | | Payouts | class-acm-payouts.php | Unpaid payout summary screen. | | Media | class-acm-media.php | Media list attribution and preview image support. | | Tracking | class-acm-tracking.php | Referral URLs, cookies, and click logging. | | Users | class-acm-users.php | User attribution from referral cookies. | | WooCommerce | class-acm-woocommerce.php | Order processing and commission ledger creation. | | Creator_Assets | class-acm-creator-assets.php | Creator asset library, cart/order persistence, Store API data, APF bridge. | | Shortcodes | class-acm-shortcodes.php | Creator dashboard and public profile shortcodes. | | Creator_Register | class-acm-creator-register.php | Public creator registration UI shortcode. | | Creator_Register_REST | class-acm-creator-register-rest.php | REST endpoint for creator application submission. | | Assets | class-acm-assets.php | Frontend asset registration/enqueueing and localized gallery/dashboard data. | | Account_Endpoint | class-acm-account-endpoint.php | WooCommerce My Account creator dashboard endpoint. |

Frontend Assets

| Asset | Purpose | |---|---| | assets/css/public.css | Public profile, registration, creator dashboard, gallery, asset library, and frontend UI styling. | | assets/js/public-register.js | Multi-step creator registration form behavior and REST submission. | | assets/js/public-gallery.js | Creator dashboard pickers, asset AJAX saving/uploading, public gallery filters, product suggestions, and lightbox behavior. |

Admin Assets

| Asset | Purpose | |---|---| | assets/css/admin.css | Creator admin workspace, pickers, columns, tabs, and preview selector styling. | | assets/js/admin.js | Admin multi-pickers, tabs, copy-to-clipboard actions, and media preview picker behavior. |

---

8. Data Model

Custom Post Type

#### acm_creator

The plugin registers a public creator custom post type with:

• Admin UI enabled
• REST enabled
• Menu icon dashicons-networking
• Supports title and featured image
• Public permalink slug creator
• Block editor disabled for creator records
• Excluded from search and nav menus

The creator CPT is the primary operational record for a creator, ambassador, affiliate, collaborator, or asset contributor.

Attachment Taxonomies

The plugin registers two non-public attachment taxonomies:

| Taxonomy | Type | Purpose | |---|---|---| | acm_asset_category | Hierarchical | Organizes creator media assets into categories. | | acm_asset_tag | Non-hierarchical | Tags creator media assets for filtering and dashboard management. |

These taxonomies are shown in admin and REST for attachments.

Custom Database Tables

The activation routine creates three custom tables using dbDelta().

#### {prefix}acm_clicks

Stores referral click events.

| Field | Purpose | |---|---| | id | Primary key. | | creator_id | Creator record associated with the click. | | created_at | Click timestamp. | | ref_url | Referrer URL. | | ip_address | Captured IP. | | user_agent | Captured browser/user agent string. |

Indexes include creator_id and created_at.

#### {prefix}acm_commissions

Stores per-order-item commission rows.

| Field | Purpose | |---|---| | id | Primary key. | | created_at, updated_at, paid_at | Ledger lifecycle timestamps. | | order_id, order_item_id | WooCommerce order and line item context. | | creator_id, creator_user_id | Creator CPT and linked WordPress user. | | asset_link_id, attachment_id | Creator asset linkage. | | product_id, variation_id | Product context. | | source_url | Media/source URL when detected. | | asset_title, order_item_name | Human-readable display context. | | line_total | Order line total used for commission math. | | asset_price | Creator asset credit amount where applicable. | | commission_amount | Amount owed to the creator. | | credit_source | Source label such as creator_commission or creator_asset. | | status | Commission status, typically unpaid, paid, or reversed. | | notes | Attribution notes such as source and multi-creator split info. |

Indexes include creator, creator user, asset link, order, status, and created date.

#### {prefix}acm_creator_assets

Stores creator asset configurations linked to attachments and products.

| Field | Purpose | |---|---| | id | Primary key. | | created_at, updated_at | Asset assignment timestamps. | | creator_id, creator_user_id | Creator owner and linked user. | | attachment_id | WordPress media attachment. | | product_id, variation_id | Product/variation context. | | asset_price | Creator asset price/credit. | | is_public | Whether the asset is available publicly. | | status | Asset status, default active. |

A unique key prevents duplicate creator/attachment/product/variation rows.

Key Post Meta

| Meta Key | Object | Purpose | |---|---|---| | _acm_user_id | Creator | Linked WordPress user. | | _acm_email | Creator | Creator contact email. | | _acm_platform | Creator | Primary social/content platform. | | _acm_handle | Creator | Creator handle. | | _acm_ref_slug | Creator | Referral slug for /@slug links. | | _acm_status | Creator | Business status, currently active/inactive. | | _acm_commission_type | Creator | Optional override: percent or flat. | | _acm_commission_rate | Creator | Optional override rate. | | _acm_payout_email | Creator | Payout contact email. | | _acm_tagline | Creator | Public tagline. | | _acm_bio | Creator | Public creator bio. | | _acm_location_name | Creator | Public location. | | _acm_social_* | Creator | Social profile URLs. | | _acm_product_ids | Creator | Related product IDs. | | _acm_post_ids | Creator | Related post/page IDs. | | _acm_attachment_ids | Creator | Related media attachment IDs. | | _acm_creator_ids | Product/content/attachment | Creator IDs associated with an object. | | _acm_creator_id | Attachment | Legacy primary creator compatibility key. | | _acm_creator_user_id | Attachment | Legacy creator user compatibility key. | | _acm_asset_price | Attachment | Asset price/credit. | | _acm_asset_public | Attachment | Asset public/private flag. | | _acm_asset_product_ids | Attachment | Related product IDs. | | _acm_processed | Order | Prevents duplicate commission processing. | | _acm_creator_ids | Order | Creator IDs credited on the order. | | _acm_commission_total | Order | Total commission recorded for the order. | | _acm_creator_assets_json | Order item | Serialized creator asset payload. | | _acm_creator_asset_unit_total | Order item | Creator asset amount per unit. | | _acm_creator_asset_line_total | Order item | Creator asset total for the line. | | _acm_creator_id | User | First creator attributed to a registered/logged-in user. |

Plugin Settings

Settings are stored in the acm_settings option.

| Setting | Default | Purpose | |---|---:|---|

> Source reference excerpt truncated; use the linked technical reference and repository baseline for the full implementation context.

9. Creator Registration Workflow

The plugin provides a public-facing creator registration experience through two shortcode aliases:

[acm_register_creator]
[acm_creator_register]

The registration UI is implemented as a multi-panel form with JavaScript-driven progress/navigation and REST submission.

Registration Form Areas

The form collects creator/business context such as:

• Display name
• Email
• Primary platform
• Handle
• Share slug
• Payout email
• Website
• Phone
• Location
• Tagline
• Content niches
• Primary content types
• Audience size
• Posting frequency
• Portfolio/channel links
• Bio
• Collaboration goals
• Additional notes
• Confirmation checkbox

REST Endpoint

The form submits to:

POST /wp-json/acm/v1/creator/register

The endpoint is public, but it uses basic protective controls:

• Required field validation
• Email validation
• Agreement/confirmation validation
• Honeypot field named company_fax
• IP/user-agent based transient rate limiting
• Creator slug collision checks
• Sanitization for text, email, URL, textarea, handle, and slug values

Registration Output

On successful submission, the endpoint either creates a new acm_creator post or updates an existing linked creator record when the user is logged in and authorized for that creator. New creator records default to pending post status and internal _acm_status defaults to inactive until reviewed.

The endpoint saves the submitted intake fields into creator post meta and builds an intake summary for admin review. It also sends admin and creator notification emails for new submissions.

Marketing Value

This transforms creator intake from a passive form submission into an operational record that can be reviewed, approved, linked to a user account, connected to assets/products, and used later for attribution and commission workflows.

---

11. Creator Relationship Model

Athenian Creator Manager supports bidirectional relationships between creators and commerce/content/media objects.

Object-Side Storage

Products, supported content types, and media attachments store creator IDs in:

_acm_creator_ids

Attachments also mirror the first selected creator into legacy keys:

_acm_creator_id
_acm_creator_user_id

Creator-Side Storage

Creator records store related objects in:

_acm_product_ids
_acm_post_ids
_acm_attachment_ids

Relationship Surfaces

The plugin adds creator pickers to:

• WooCommerce products
• Posts and pages
• Additional content post types via the acm_relationship_post_types filter
• Media attachments
• Creator workspace relationship panels

AJAX Search

Admin pickers use the acm_admin_search AJAX action for searchable selector results across:

• Creators
• Products
• Posts/pages
• Media attachments

Marketing Value

This relationship model is what makes the plugin more powerful than generic affiliate attribution. A creator can be connected to a product they helped promote, media they contributed, and content/campaigns where they appear.

---

14. Storefront, Cart & Store API Behavior

Athenian Creator Manager is built to preserve creator asset selections through WooCommerce cart and checkout.

Classic Cart Hooks

The plugin hooks into classic WooCommerce cart flow through:

| Hook | Purpose | |---|---| | woocommerce_add_cart_item_data | Captures selected creator asset payloads during add-to-cart. | | woocommerce_get_cart_item_from_session | Restores creator asset payloads from session. | | woocommerce_before_calculate_totals | Adds creator asset credit amounts to cart line pricing. | | woocommerce_get_item_data | Displays creator asset metadata in cart/checkout item data. | | woocommerce_checkout_create_order_line_item | Persists creator asset payloads and display meta to order items. | | woocommerce_order_item_get_formatted_meta_data | Formats creator asset meta for display. |

Store API Hooks

The plugin also supports WooCommerce Store API / Blocks-style cart behavior through:

| Hook / API | Purpose | |---|---| | woocommerce_store_api_add_to_cart_data | Captures creator asset selections from Store API add-to-cart data. | | woocommerce_store_api_cart_add_item_data | Captures creator asset selections from cart add item data. | | woocommerce_store_api_cart_item | Enriches Store API cart items with creator asset details. | | woocommerce_store_api_register_endpoint_data | Registers acm namespace data on cart items. |

Store API Data Namespace

The Store API extension namespace is:

acm

Registered fields include:

• creator_assets
• asset_total
• asset_line_total
• asset_unit_total
• quantity

Pricing Behavior

Selected creator asset prices are summed as a creator asset total. The plugin derives a unit adjustment by dividing the asset line total by quantity, then adds that amount to the cart line product price during woocommerce_before_calculate_totals.

This allows creator credit to become part of the order line economics while also persisting the underlying creator asset context.

Order Item Persistence

Order line items receive:

• _acm_creator_assets_json
• _acm_creator_asset_unit_total
• _acm_creator_asset_line_total
• Display meta for Creator Asset
• Display meta for Creator Surface, when present
• Display meta for Creator
• Display meta for Creator Credit

Product Selector Note

The plugin includes a render_product_selector() helper that can render a product-page selector for active public creator assets linked to a product. In the inspected code, this helper is present but is not automatically attached to a WooCommerce product-page hook. It appears intended for use by a template, integration layer, or future hook wiring.

---

19. Media Library Integration

The Media class enhances WordPress Media Library behavior.

Creator Column

The plugin adds a “Creator” column to the Media Library list view, displaying up to two linked creators with a count indicator for additional creators.

Attachment Creator Attribution

Media attachment edit screens receive creator attribution controls through the shared relationship model.

Preview Images for Model Files

For non-image media/model files, the plugin allows an admin or creator workflow to assign a preview image. This is especially useful for STL and other 3D/model formats that need a visual storefront representation.

Supported model-like extensions include:

• STL
• OBJ
• 3MF
• GLB
• GLTF
• FBX
• PLY
• STEP
• STP

Marketing Value

The plugin supports visual merchandising for creator-supplied files and 3D assets, which is especially useful for creator customization, 3D product mockups, and print/production workflows.

---

20. REST, AJAX, Shortcodes & Hooks Reference

REST Routes

| Route | Method | Purpose | |---|---|---| | /wp-json/acm/v1/creator/register | POST | Public creator registration/application submission. |

Public Shortcodes

| Shortcode | Purpose | |---|---| | [acm_register_creator] | Creator registration form. | | [acm_creator_register] | Alias for creator registration form. | | [acm_creator_dashboard] | Logged-in creator dashboard and asset manager. | | [acm_creator_profile] | Public creator profile and gallery. |

Public AJAX Actions

| AJAX Action | Auth | Purpose | |---|---|---| | acm_product_search | Auth + no-priv | Product search for gallery filters. | | acm_filter_creator_gallery | Auth + no-priv | Filter public creator gallery results. |

Creator Dashboard AJAX Actions

| AJAX Action | Auth | Purpose | |---|---|---| | acm_dashboard_search | Logged-in creator | Search dashboard resources. | | acm_dashboard_create_tag | Logged-in creator | Create a new asset tag. | | acm_dashboard_save_asset | Logged-in creator | Save asset configuration. | | acm_dashboard_upload_media | Logged-in creator | Upload image/STL creator files. |

Admin AJAX Actions

| AJAX Action | Capability | Purpose | |---|---|---| | acm_admin_search | edit_posts | Search creators/products/content/media for admin pickers. |

WooCommerce Hooks

| Hook | Purpose | |---|---| | woocommerce_checkout_order_processed | Generate commission ledger rows after checkout order processing. | | woocommerce_add_cart_item_data | Capture creator asset selections in classic add-to-cart flow. | | woocommerce_get_cart_item_from_session | Restore creator asset payloads from cart session. | | woocommerce_before_calculate_totals | Apply creator asset pricing to cart line items. | | woocommerce_get_item_data | Display creator asset details in cart/checkout. | | woocommerce_checkout_create_order_line_item | Persist creator asset details to order item meta. | | woocommerce_order_item_get_formatted_meta_data | Format creator asset meta for order displays. | | woocommerce_store_api_add_to_cart_data | Capture creator assets from Store API add-to-cart. | | woocommerce_store_api_cart_add_item_data | Capture creator assets from Store API cart item data. | | woocommerce_store_api_cart_item | Enrich Store API cart item payloads. | | woocommerce_blocks_loaded | Register Store API extension data when available. | | woocommerce_account_menu_items | Add Creator Dashboard to My Account menu. | | woocommerce_account_creator-dashboard_endpoint | Render My Account creator dashboard endpoint. | | woocommerce_thankyou | Tag users with referral cookie attribution after order. |

WordPress Hooks

| Hook | Purpose | |---|---| | init | Register CPT, taxonomies, rewrites, endpoints, Store API extensions. | | rest_api_init | Register creator registration REST route. | | template_redirect | Handle referral links and dashboard submissions. | | wp_footer | Output referral cookie JavaScript fallback. | | user_register | Tag newly registered users from referral cookie. | | wp_login | Tag logged-in users from referral cookie. | | upload_mimes | Allow STL uploads. | | manage_upload_columns | Add creator column in Media Library. | | attachment_fields_to_edit | Add preview image selector for model files. | | attachment_fields_to_save | Save preview image data. | | use_block_editor_for_post_type | Disable block editor for creator CPT. |

Athenian/APF Integration Hook

| Hook | Purpose | |---|---| | apf_media_default_picker_media_ids | Adds public creator assets into APF media picker defaults. |

---

21. Integration Story Within the Athenian Platform

Athenian Creator Manager functions as the creator-program layer inside a broader commerce platform.

With WooCommerce

It ties creator attribution and asset economics directly to WooCommerce cart, checkout, order items, customer users, My Account, and admin screens.

With WordPress Media

It turns media attachments into creator-attributed, optionally priced assets with categories, tags, preview images, public/private state, and product relationships.

With WordPress Content

It allows posts, pages, and filterable custom content types to be creator-tagged, supporting campaign and editorial attribution.

With APF / PrintForge-Style Workflows

It exposes public creator assets to APF media picker flows and preserves asset metadata through cart/order workflows. This makes it a strong complement for PrintGhost.ai and print/customization workflows where creator art, STL files, previews, product assets, or media selections become part of the product experience.

With Creator-Led Marketplaces

The plugin provides the base operating logic for recruiting creators, connecting their assets to products, showing public galleries, tracking commerce influence, and managing commissions.

---

22. Example Operating Workflows

Workflow A — Creator Applies to the Program

1. Visitor opens a page containing [acm_register_creator].
2. The multi-step registration UI collects creator, platform, audience, and collaboration details.
3. The form submits to /wp-json/acm/v1/creator/register.
4. The plugin validates fields, rate limits, checks the honeypot, and sanitizes data.
5. A pending acm_creator record is created.
6. Admin and creator emails are sent.

> Source reference excerpt truncated; use the linked technical reference and repository baseline for the full implementation context.