Athenian Order Fulfillment

Developer starting point

This baseline was generated from the local athenian-order-fulfillment source folder and the linked product record. The source folder is the reviewed implementation boundary for this pass; runtime behavior remains deployment-dependent; the GitHub repository identity for this documentation baseline is verified.

Technical Architecture

Plugin identity

• Plugin name: Athenian Order Fulfillment
• Plugin slug: athenian-order-fulfillment
• Version: 0.2.0
• Primary file: athenian-order-fulfillment.php
• Requires PHP: 8.0
• Requires plugin: WooCommerce
• Text domain: athenian-order-fulfillment
• Core CPT: ath_fulfillment
• Core capability: aof_manage

Main file structure

athenian-order-fulfillment.php
assets/admin/admin.css
assets/admin/admin.js
docs/aof-marketing-document.md
docs/athenian-platform-marketing.md
docs/athenian-platform-technical.md
includes/Plugin.php
includes/Setup.php
includes/Admin/Assets.php
includes/Admin/Menu.php
includes/Admin/Tabs.php
includes/Admin/Pages/Dashboard.php
includes/Admin/Pages/Queue.php
includes/Admin/Pages/Settings.php
includes/Ajax/Tasks.php
includes/Models/Fulfillment.php
includes/Services/Inventory.php
includes/Services/Planner.php
includes/Services/Shipping.php
modules/fulfillment-rules/
modules/notify-back-in-stock/
modules/order-fulfillment-statuses/
modules/product-acknowledgements/

Boot process

The main plugin file loads includes/Plugin.php and includes/Setup.php, initializes activation handling, and boots the singleton on plugins_loaded.

The Plugin class then:

• Defines constants for AOF and bundled module paths/URLs.
• Loads the core model, service, admin, and AJAX classes.
• Includes consolidated module code.
• Registers the ath_fulfillment CPT on init.
• Registers the aof_manage capability on administrator and shop manager roles.
• Adds the Fulfillment admin menu and submenus.
• Registers AJAX task endpoints.
• Hooks fulfillment planning into WooCommerce order lifecycle events.
• Declares WooCommerce HPOS compatibility when WooCommerce’s FeaturesUtil class is available.

Namespaces and primary classes

Core namespaces:

• Athenian\OrderFulfillment
• Athenian\OrderFulfillment\Admin
• Athenian\OrderFulfillment\Admin\Pages
• Athenian\OrderFulfillment\Ajax
• Athenian\OrderFulfillment\Models
• Athenian\OrderFulfillment\Services

Bundled module namespaces:

• Athenian\OrderFulfillmentStatus
• ColumbiaCoatings\NotifyBackInStock
• ColumbiaCoatings\NotifyBackInStock\Admin
• ColumbiaCoatings\NotifyBackInStock\CLI
• ColumbiaCoatings\HeatHold
• CCPA
• CCPA\Admin
• CCPA\Frontend

Primary classes:

• Athenian\OrderFulfillment\Plugin
• Athenian\OrderFulfillment\Setup
• Athenian\OrderFulfillment\Models\Fulfillment
• Athenian\OrderFulfillment\Services\Planner
• Athenian\OrderFulfillment\Services\Inventory
• Athenian\OrderFulfillment\Services\Shipping
• Athenian\OrderFulfillment\Ajax\Tasks
• Athenian\OrderFulfillment\Admin\Menu
• Athenian\OrderFulfillment\Admin\Tabs
• Athenian\OrderFulfillment\Admin\Assets
• Athenian\OrderFulfillment\Admin\Pages\Dashboard
• Athenian\OrderFulfillment\Admin\Pages\Queue
• Athenian\OrderFulfillment\Admin\Pages\Settings
• Athenian\OrderFulfillmentStatus\Plugin
• ColumbiaCoatings\NotifyBackInStock\Plugin
• ColumbiaCoatings\NotifyBackInStock\Repository
• ColumbiaCoatings\NotifyBackInStock\StockWatcher
• ColumbiaCoatings\NotifyBackInStock\Mailer
• ColumbiaCoatings\HeatHold\Options
• ColumbiaCoatings\HeatHold\Shipping
• ColumbiaCoatings\HeatHold\Frontend
• CCPA\Plugin
• CCPA\Admin\Admin
• CCPA\Frontend\Frontend
• CCPA\Frontend\WC_AJAX

Data Model

Fulfillment task CPT

AOF stores fulfillment work as private WordPress posts using the ath_fulfillment post type.

The CPT is registered as:

• public => false
• show_ui => false
• show_in_menu => false
• supports => ['title', 'custom-fields']
• rewrite => false

The queue and dashboard use custom admin pages rather than exposing the CPT’s native edit screen.

Fulfillment task meta schema

Each task stores operational metadata:

| Meta key | Type | Purpose | |---|---:|---| | _order_id | integer | Source WooCommerce order ID. | | _group_key | string | Idempotent task grouping key such as store:wh:default or vendor:123. | | _group_type | string | store or vendor. | | _vendor_id | integer | Vendor ID for vendor tasks; 0 for store tasks. | | _warehouse_id | string | Warehouse handle for store tasks. | | _status | string | Operational task status. | | _items_json | JSON string | Simplified fulfillment lines for the task. | | _shipment_id | integer | Shipment Manager shipment record ID, when created. | | _notes | string | Internal notes. |

Fulfillment line schema

The planner normalizes each order line into a compact structure:

| Field | Purpose | |---|---| | item_id | WooCommerce order item ID. | | product_id | Product or variation product ID. | | variation_id | Variation ID when the line is a variation. | | sku | Product SKU. | | name | Order item name. | | qty | Quantity to fulfill. |

The line array is filterable through aof_fulfillment_line.

Fulfillment task statuses

The model and queue support statuses such as:

• pending
• reserved
• picking
• packed
• shipped
• done
• hold

The current UI exposes quick actions for packed, done, and shipment creation. Inventory reservation can move a store task to reserved; failed reservation moves it to hold.

Order fulfillment-status meta

The fulfillment-status module stores one or more values on the WooCommerce order under:

_cofs_fulfillment_status

The module deletes and re-adds this metadata when statuses are saved, allowing a single order to hold multiple operational status slugs.

Fulfillment-status option storage

Configured fulfillment statuses are stored in:

cofs_statuses

Each status definition contains a label and slug.

Back-in-stock custom table

The notify-back-in-stock module creates a custom database table:

{$wpdb->prefix}cc_nbis_signups

Table fields include:

| Column | Purpose | |---|---| | id | Signup ID. | | email | Subscriber email. | | user_id | Logged-in user ID, when available. | | product_id | Product ID. | | variation_id | Variation ID, when relevant. | | status | pending, confirmed, notified, unsubscribed, or related admin-managed states. | | token | Unique public confirm/unsubscribe token. | | created_at | Signup timestamp. | | confirmed_at | Double opt-in confirmation timestamp. | | notified_at | Back-in-stock notification timestamp. | | ip | Signup IP address. | | user_agent | Signup user agent. | | note | Admin note. |

The table includes indexes for email, product, variation, status, token, product/status, and variation/status lookups.

Product acknowledgement option storage

The product acknowledgements module stores settings in:

ccpa_settings

Settings include enable state, base CSS, and an ordered list of acknowledgement rules. Each rule can contain tag IDs, title, message, confirmation button text, custom CSS, and enabled state.

Fulfillment rules option storage

The fulfillment-rules module stores settings in:

cchh_settings

Settings include global enable state, accent color, and rule definitions. Each rule can define priority, active date range, product matchers, package handling, shipping action, service patterns, customer messaging, acknowledgement behavior, line-item labels, and internal notes.

AJAX, Admin Actions & Shortcodes

Core AOF AJAX actions

All core AOF AJAX actions require the aof_manage capability and verify the aof_nonce nonce.

| Action | Purpose | |---|---| | aof_lookup_order | Load order status, total, currency, shipping/billing address, line items, vendor IDs, and existing fulfillment tasks. | | aof_plan_order | Manually run fulfillment planning for an order. | | aof_list_tasks | Return recent fulfillment tasks for the dashboard or queue. | | aof_mark_done | Update a task status, commonly to done or packed. | | aof_create_shipment | Reserve inventory for store tasks, create Shipment Manager shipment, attach shipment ID, and open packing workflow. |

Notify Back In Stock AJAX and public actions

| Surface | Purpose | |---|---| | wp_ajax_cc_nbis_subscribe | Logged-in customer signup. | | wp_ajax_nopriv_cc_nbis_subscribe | Guest signup. | | ?cc_nbis_confirm={token} | Public confirmation endpoint. | | ?cc_nbis_unsub={token} | Public unsubscribe endpoint. |

Product acknowledgement AJAX actions

| Action | Purpose | |---|---| | ccpa_should_ack | Returns whether a product requires acknowledgement and provides modal payload. |

This endpoint is registered for both logged-in and logged-out customers. The add-to-cart validation also checks request data server-side so the confirmation requirement is not purely cosmetic.

Admin post actions

The bundled modules use admin-post handlers for exports and back-in-stock management:

| Action | Purpose | |---|---| | aofs_export_orders_csv | Export fulfillment-status-filtered orders to CSV. | | cofs_export_orders_csv | Legacy export action retained for compatibility. | | cc_nbis_save_settings | Save back-in-stock settings. | | cc_nbis_create | Create a back-in-stock signup from admin. | | cc_nbis_update | Update a signup. | | cc_nbis_delete | Delete a signup. | | cc_nbis_send | Manually send a notification. | | cc_nbis_bulk | Bulk-manage signup rows. |

Shortcodes

| Shortcode | Purpose | |---|---| | [cc_notify_back_in_stock] | Render a back-in-stock signup form for a product or variation. |

Supported shortcode attributes include product_id and variation_id.

WP-CLI commands

The notify-back-in-stock module registers a cc-nbis WP-CLI command when WP-CLI is available.

Examples:

wp cc-nbis dispatch 123
wp cc-nbis dispatch 123 --variation=456
wp cc-nbis list --status=pending
wp cc-nbis list [email protected]

WooCommerce Integration Points

Order lifecycle hooks

The core planner hooks into:

• woocommerce_payment_complete
• woocommerce_order_status_changed

These hooks allow automatic fulfillment task creation after payment or when an order enters configured statuses such as processing.

Order admin hooks

The fulfillment-status module integrates with both legacy and HPOS order admin experiences:

• Adds order edit metaboxes.
• Saves fulfillment statuses during order meta processing.
• Adds fulfillment-status columns to order lists.
• Adds order list filters.
• Filters legacy and HPOS order queries.
• Exports filtered order sets.

Product and cart hooks

The acknowledgement and fulfillment-rule modules integrate with product and cart flows through hooks such as:

• woocommerce_single_product_summary
• woocommerce_after_add_to_cart_form
• woocommerce_loop_add_to_cart_link
• woocommerce_add_to_cart_validation
• woocommerce_get_item_data
• woocommerce_before_cart
• woocommerce_before_checkout_form

These hooks allow the plugin to display notices, inject acknowledgement payloads, and prevent add-to-cart when customer confirmation is missing.

Shipping hooks

The fulfillment-rules module modifies shipping behavior through:

• woocommerce_cart_shipping_packages
• woocommerce_package_rates
• woocommerce_shipping_package_name

This allows matching products to be split into their own packages, lets rules filter available package rates, and updates package names for customer clarity.

Stock hooks

The back-in-stock module listens for:

• woocommerce_product_set_stock_status
• woocommerce_variation_set_stock_status

When an item returns to stock, the module finds pending or confirmed signups and sends configured back-in-stock emails.

Inventory & Warehouse Adapter Layer

The Inventory service is deliberately hook-based. It does not assume a specific ERP, warehouse table, or inventory plugin.

Warehouse discovery

apply_filters('aof_get_warehouses', [])

Expected result examples:

[
    ['id' => 'main', 'name' => 'Main Warehouse'],
    ['id' => 'west', 'name' => 'West Coast Warehouse'],
]

String-only values are also normalized into id/name pairs.

Warehouse selection

apply_filters('aof_select_warehouse_for_order', $default, $order_id, $lines)

A warehouse integration can choose the best warehouse based on destination, stock availability, product type, or operational rules.

Inventory reservation

apply_filters('aof_reserve_inventory', null, $warehouse_id, $lines, $context)

Expected response:

[
    'ok' => true,
    'holds' => [],
    'message' => 'reserved'
]

If no integration handles the filter, the default behavior returns success with an empty hold list. This keeps the core planner usable even before a warehouse adapter is connected.

Inventory release

do_action('aof_release_inventory', $warehouse_id, $holds, $context)

The release action gives external inventory systems a path to clear holds when a task changes state, fails, or is cancelled.

Shipment Manager Integration

The Shipping service checks for:

Athenian\ShipmentManager\Shipment_Store
Athenian\ShipmentManager\Plugin

When available, AOF can call:

Athenian\ShipmentManager\Shipment_Store::create_from_order($order, $meta)

The current shipment creation path uses _status => packed by default, then attaches the returned shipment ID to the fulfillment task and opens the Shipment Manager packing page with the source order ID.

This makes AOF the planning layer and Shipment Manager the physical packing/shipment execution layer.

Extension Points

Core AOF filters and actions

| Hook | Type | Purpose | |---|---|---| | aof_fulfillment_line | Filter | Modify a normalized fulfillment line before grouping. | | aof_fulfillment_groups | Filter | Modify final fulfillment groups before tasks are created. | | aof_get_warehouses | Filter | Provide warehouse choices to the settings UI and planner. | | aof_select_warehouse_for_order | Filter | Select a warehouse for store-fulfilled lines. | | aof_reserve_inventory | Filter | Reserve inventory for a task before creating a shipment. | | aof_release_inventory | Action | Release inventory holds from an external system. |

Fulfillment status module hooks

| Hook | Type | Purpose | |---|---|---| | aofs/status_options | Filter | Modify normalized status options keyed by slug. | | aofs/status_definitions | Filter | Modify raw status definitions before normalization. | | aofs/default_status_definitions | Filter | Modify seeded default status definitions. | | aofs/order_fulfillment_statuses_updated | Action | Respond after statuses are updated on an order. |

Live fleet review — 2026-10-07

Order Fulfillment is not a single fleet version. Athenian Spa is active on 0.1.0 with installed main-file SHA-256 946b2f5c3c5210b1101efec9725490dcfdd64f644baec3ce7ce15a658cf78319; CatMilk is active on 0.2.1 with installed main-file SHA-256 cf9990cb83032e65d77ef47c1715f231fb97c22ce1163fce73a6307a45061354. The documented source baseline is baseline/devdocs-0.2.1-20261006 at commit 22700022a3a6c59fb76b247c215ed6c710d8e29c; its reviewed canonical main-file hash is 89ade71aeff498eabe072dd9737d15b18c38dca24f648864a70883bb027335ce.

Read-only runtime inspection found 418 ath_fulfillment records on Spa and 3 on CatMilk. Both variants expose the AOF AJAX actions for lookup, listing, planning, completion, and shipment creation. CatMilk also has aof_auto_plan_enabled=yes, a configured auto-plan status list, an empty default warehouse, and a scheduled license-check hook; Spa did not expose those AOF options in the captured option boundary.

The live main-file hashes differ from the documented canonical source and from each other. Treat Spa 0.1.0 and CatMilk 0.2.1 as separate variants; no shared promotion or fulfillment mutation was performed.

Normalized fleet parity — 2026-10-07

The canonical comparison used the reviewed baseline/devdocs-0.2.1-20261006 source at commit 22700022a3a6c59fb76b247c215ed6c710d8e29c. The comparison normalized text line endings and excluded vendor, cache, backup, archive, and site-generated log/task artifacts.

Athenian Spa — reduced 0.1.0 variant

The live tree contains 16 comparable files versus 68 canonical files: 52 canonical files are absent, 11 common files have normalized content differences, and 5 differ only by line endings. This is a materially reduced 0.1.0 implementation, not a packaging-only fork. It does not include the license client bootstrap, consolidated-module boot, Batch Print/Tabs admin surfaces, fulfillment rules, back-in-stock notifications, order-fulfillment statuses, or product acknowledgements present in the 0.2.1 source baseline. The site currently contains 418 ath_fulfillment records.

CatMilk — full-tree fork with three content differences

The live tree has the same 68-file shape as the canonical comparison. 64 raw differences are line-ending-only; 3 normalized content forks remain:

• includes/Plugin.php: the live internal version constant is 0.2.0 while the plugin header is active as 0.2.1; the CCPA constant is 1.2.2 versus the canonical 1.2.1; the Batch Print include is removed.
• modules/product-acknowledgements/assets/frontend/popup.js: the live fork preserves the clicked submitter using requestSubmit() or a hidden fallback and carries that submitter through product-ID resolution and modal paths.
• modules/product-acknowledgements/columbia-coatings-product-acknowledgements.php: the live module version is 1.2.2 versus the canonical 1.2.1.

CatMilk currently contains 3 ath_fulfillment records, exposes aof_auto_plan_enabled=yes with an auto-plan status list and empty default warehouse, and has the scheduled athenian-order-fulfillment_license_check hook. These differences require owner confirmation before treating the tree as a shared release identity.

Promotion boundary

The 0.2.1 GitHub source remains the authoritative documentation reference, but Spa 0.1.0 and CatMilk's live fork remain separate deployment variants. No plugin files, task records, options, queues, order statuses, shipment calls, or fulfillment data were changed during this parity review.