Athenian Fulfillment Platform

Developer starting point

This baseline documents the Fulfillment Platform architecture. It does not claim that a live inventory write, inbound receipt, warehouse action, carrier request, or fulfillment event has been exercised.

3. Architectural decisions

3.1 Inventory authority

The ATHFP client-scoped ledger is authoritative for physical inventory. WooCommerce stock is a derived sales-channel projection.

For a mapped item:

Woo sellable stock = sellable on hand in active allocatable bins - active reservations

The following quantities do not contribute to WooCommerce stock:

• accepted units still in RECEIVING;
• quarantined units;
• damaged units;
• rejected units;
• inventory in inactive or non-allocatable bins;
• incoming quantities that have not been physically received.

This rule prevents WooCommerce product metadata, client systems, and carrier integrations from becoming competing inventory authorities.

3.2 Tenant boundary

Every client-owned operational record includes client_id. Bearer credentials resolve directly to a client context, and the caller cannot replace that tenant with a request parameter.

Physical receiving and putaway are different trust boundaries. They require an authenticated WordPress operator with the appropriate ATHFP capability and an explicit client selection. Client API credentials may declare and submit inbound shipments, but they cannot claim that physical inventory has arrived.

3.3 Standalone core with optional adapters

ATHFP does not call classes from Athenian Platform Core or Athenian WC Dropship as hard dependencies. It exposes:

• a versioned REST API;
• WordPress actions and filters;
• a capability advertisement bridge;
• signed client webhooks;
• WooCommerce shipping-rate integration points.

This keeps the warehouse ledger deployable on its own while allowing a dropship storefront or platform service to connect through a stable contract.

3.4 WooCommerce compatibility

WooCommerce products and variations remain the catalog records. ATHFP stores tenant ownership and warehouse attributes separately and maps each active item to one Woo product or variation.

The plugin declares compatibility with WooCommerce High-Performance Order Storage and Cart/Checkout Blocks. Version 0.1.0 does not yet create outbound WooCommerce orders; later order work is designed to use WooCommerce CRUD APIs rather than direct order-table access.

4. Component architecture

flowchart LR
    Client["Client storefront or ERP"] -->|"Bearer API"| REST["ATHFP REST API"]
    Operator["Warehouse operator"] -->|"WordPress session"| Admin["Fulfillment workspace"]
    Admin --> Services["Application services"]
    REST --> Services
    Services --> Ledger["Inventory operations and immutable ledger"]
    Services --> Workflow["Inbound, receipt, lot, and putaway workflow"]
    Ledger --> Balances["Materialized balances"]
    Balances --> Projector["Woo stock projector"]
    Projector --> Woo["WooCommerce products and variations"]
    Services --> Outbox["Event outbox"]
    Outbox --> Webhooks["Signed client webhooks"]
    Woo --> Rates["Woo shipping methods"]
    Rates --> REST
    Carrier["Carrier adapter"] -->|"athfp_shipping_rate_quotes"| Rates

Primary code areas

| Area | Responsibility | | --- | --- | | includes/Activation | Schema installation, upgrades, seeded defaults, capabilities, and lifecycle behavior | | includes/API/Auth | Bearer credentials, client context, cookie operator context, scopes, and tenant enforcement | | includes/API/REST/V1 | Versioned inventory, inbound, task, rate, webhook, health, and identity routes | | includes/Application | Catalog mapping, inventory mutations, inbound workflow, rates, audit, idempotency, and webhook delivery | | includes/Infrastructure/Database | Table naming and repositories for clients, items, lots, balances, ledger entries, and warehouse workflows | | includes/Infrastructure/WooCommerce | Product-editor controls, stock projection, and reconciliation | | includes/Infrastructure/Integrations | Optional Athenian capability and inventory-provider bridge | | includes/Admin | Operator workspace for clients, items, inbounds, receiving, tasks, and diagnostics | | includes/CLI | Health, schema, inventory, projection, and reconciliation commands |

Dependencies are registered in a small internal service container. Source files use the Athenian\FulfillmentPlatform namespace and path-based autoloading.

5. Data model

Activation creates 28 prefixed InnoDB tables. Actual names use the active WordPress database prefix followed by athfp_.

Tenancy and catalog

| Table suffix | Purpose | | --- | --- | | clients | House Account and external fulfillment clients | | client_users | WordPress user membership and client role | | credentials | Hashed bearer secrets, scopes, status, IP restrictions, and usage timestamps | | items | Client SKU ownership and Woo product or variation mapping | | warehouses | Fulfillment origins and address settings | | bins | Receiving, storage, quarantine, damaged, returns, staging, and packing locations | | lots | Client item lot code, expiration, and lot status |

Inventory and inbound operations

| Table suffix | Purpose | | --- | --- | | inventory_operations | Idempotent business operation header | | inventory_ledger | Append-only quantity deltas and post-operation balances | | inventory_balances | Current balance by client, item, warehouse, bin, condition, and lot | | reservations | Schema foundation for outbound allocation | | inbounds | Client-declared inbound shipment header and state | | inbound_lines | Expected and received quantities by item | | receipts | One idempotent physical receiving session | | receipt_lines | Accepted, damaged, quarantined, and rejected results | | workflow_tasks | Warehouse work queue header | | workflow_task_lines | Putaway and future execution lines |

Outbound-ready and integration records

| Table suffix | Purpose in 0.1.0 | | --- | --- | | fulfillment_orders | Reserved for the outbound order phase | | fulfillment_order_lines | Reserved for outbound item execution | | shipping_quotes | Trusted, expiring rate results and opaque quote tokens | | shipments | Reserved for outbound shipment execution | | shipment_items | Reserved for shipped-line quantities | | packages | Reserved for dimensions, labels, and provider references | | idempotency | Request hash, processing state, and response replay | | webhook_subscriptions | Client endpoint, event selection, encrypted signing secret, and status | | outbox_events | Durable event envelope and retry state | | webhook_deliveries | Per-subscription attempt evidence | | audit_log | Actor, action, entity, request, and before/after context |

9. REST API surface

The base route is:

/wp-json/athfp/v1

The API currently provides:

• public minimal health status;
• authenticated identity, tenant, scopes, and capabilities;
• warehouse and bin discovery;
• client item mapping and item inventory details;
• inbound creation, listing, detail, and submission;
• operator receiving and putaway;
• workflow-task listing;
• shipping-rate calculation and persisted quote tokens;
• webhook subscription creation, listing, and revocation.

See [api-v1.md](api-v1.md) for the route table, payloads, authentication rules, and examples.

11. Events and integration hooks

Committed events are published through the outbox and WordPress hooks. Current event families include item mapping, inbound creation and submission, receipt recording, inventory operations, putaway completion, and webhook administration.

Primary extension points:

| Hook | Purpose | | --- | --- | | athfp_domain_event | Receive every published ATHFP event | | athfp/{domain}/{event} | Receive a specific slash-form event action | | athfp_shipping_rate_quotes | Add carrier or logistics rate results | | athfp_woo_product_inventory | Resolve ATHFP inventory for a Woo product | | athfp_capabilities | Add or inspect ATHFP feature capabilities | | athenian_platform_capabilities | Advertise fulfillment support to Athenian Platform Core | | athfp/integrations/ready | Discover the active plugin version, API namespace, and capabilities |

13. Installation and first validation

1. Back up the WordPress database.
2. Install and activate WooCommerce.
3. Upload and activate ATHFP.
4. Open Fulfillment > Diagnostics and verify all 28 tables, InnoDB engines, required bins, cryptography, queue availability, and zero negative balances.
5. Create a test client.
6. Map a non-production WooCommerce product.
7. Create and submit an inbound for that item.
8. Receive accepted and exception quantities.
9. Confirm Receiving inventory is not yet sellable.
10. Complete putaway into an allocatable bin.
11. Confirm ATHFP available inventory and WooCommerce stock agree.
12. Retry the receiving request with the original idempotency key and confirm no duplicate stock.

The complete validation procedure is available in [live-test-checklist.md](live-test-checklist.md).

14. Data retention and recovery

Deactivation stops scheduled work but does not delete operational data. Uninstall also preserves clients, mappings, inventory, receipts, ledger entries, audit history, and integration evidence. This is intentional: warehouse records should not disappear because plugin code was temporarily removed.

Database backups must include all athfp_ tables together with the WordPress and WooCommerce records they reference. WordPress authentication salts are also required to decrypt existing webhook signing secrets after a restore.