Athenian Service Provider Platform

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.

Admin and Operator Workflow

1. Configure WooCommerce Service Products

Operators create service products or service variations in WooCommerce. These products can be categorized under the plugin's ath_service_cat taxonomy so provider onboarding can present relevant service categories and catalog options.

2. Create or Sync Provider Identity

Providers can be represented through ASU person records, WordPress users, vendor profiles, or a combination of those records. The plugin includes helper logic to resolve the best person record for a user and create or connect vendor records where possible.

3. Create Service Offers

Operators create ath_sp_offer records and assign:

• Provider person ID.
• Vendor profile ID.
• Vendor user ID or override.
• Service key, such as delivery, handyman, or another operational filter.
• Active/inactive status.
• SwapShop availability.
• One or more WooCommerce product or variation targets.
• Offer-level labels, notes, details, and vendor pricing context.

4. Validate Offer Readiness

The Service Offer admin metabox displays readiness checks for person, vendor, user, target, and geo state. This makes it easier to identify incomplete service offers before exposing them through marketplace search, quote, cart, or request-order workflows.

5. Manage Provider Pricing

Offer catalog items can sync vendor pricing into product/variation metadata using canonical vendor pricing rows. This supports regular price, sale price, tier pricing, minimum quantities, lead days, enabled/paused status, notes, source, and updated timestamps.

6. Publish Frontend Marketplace Pages

Operators can add frontend pages using the plugin shortcodes, preferably referenced as single-quoted shortcode strings when used in page-builder copy to avoid accidental rendering:

• '[ath_sp_provider_onboard]' for provider onboarding.
• '[ath_sp_provider_dashboard]' for provider offer management.
• '[ath_sp_marketplace]' for location-aware marketplace search.
• '[ath_sp_offer_builder]' for service offer customization and add-to-cart.
• '[ath_sp_messages]' for buyer/provider inbox and threaded messaging.

Frontend User Workflows

Provider Onboarding

The provider onboarding flow captures profile details, service radius, address/geolocation, phone, website, credentials, enablement status, service category selections, and service variation selections. It also allows missing-service suggestions to be submitted for operator review.

Provider Dashboard

The provider dashboard loads editable service offers linked to the current user through vendor user ID, vendor profile, or provider person record. It exposes offer tabs, status badges, saved catalog item counts, product counts, active state, service key, SwapShop status, service catalog editing, and vendor pricing updates.

Marketplace Discovery

The marketplace UI supports address or browser geolocation input, radius filtering, result limits, optional service key filtering, a Leaflet map, and an offer feed. The public /ath-sp/v1/providers route returns providers near the searched location with offer and item summaries.

Offer Builder

The offer builder loads a selected service offer and its enabled items, displays selectable service options, quantity, notes, vendor price summaries, quote refresh, and add-to-cart. It uses the REST quote endpoint and offer add-to-cart endpoint to preserve vendor and offer context.

Messaging Inbox

The messaging shortcode renders an inbox with conversation threads, unread indicators, selected conversation detail, messages, and reply controls. Threads can be tied to a service offer so buyer/provider communication stays connected to the service being discussed.

Shortcodes

| Shortcode reference | Purpose | Notes | | --- | --- | --- | | '[ath_sp_provider_onboard]' | Provider onboarding wizard. | Requires WooCommerce. Logged-out users see a login-required message. | | '[ath_sp_provider_dashboard]' | Provider-facing offer management dashboard. | Requires login and linked editable offers. | | '[ath_sp_marketplace]' | Public marketplace discovery UI. | Supports radius_km, limit, service_key, height, and details_page_url. | | '[ath_sp_offer_builder]' | Service offer configuration and add-to-cart UI. | Supports offer_id, target_id, title, subtitle, show_quote, cart_redirect, and empty_message. | | '[ath_sp_messages]' | Buyer/provider messaging inbox. | Supports thread_id, title, subtitle, and refresh_sec. |

Technical Architecture

Plugin Bootstrap

The main plugin file defines the plugin constants, guards against double-loading with ATH_SP_BOOTSTRAPPED, and boots the platform on plugins_loaded priority 20 through Athenian\ServiceProvider\Plugin::instance()->boot().

Core loaded components include:

• Util
• PostTypes
• Roles
• Assets
• Messaging
• Integrations\ASU
• Shortcodes\ProviderOnboard
• Shortcodes\ProviderDashboard
• Shortcodes\Marketplace
• Shortcodes\OfferBuilder
• Shortcodes\Messages
• REST\Routes
• Admin AJAX handlers in admin-like contexts

Main Namespaces and Classes

| Class | Responsibility | | --- | --- | | Athenian\ServiceProvider\Plugin | Bootstraps the plugin, loads modules, extends ASU schema, and performs versioned rewrite flushing. | | Athenian\ServiceProvider\PostTypes | Registers CPTs, taxonomies, Service Offer metaboxes, person offer metaboxes, and Service Offer save behavior. | | Athenian\ServiceProvider\Roles | Adds ath_sp_provider capability to administrators, ASU roles, or a fallback ath_service_provider role. | | Athenian\ServiceProvider\Assets | Registers frontend/admin CSS and JavaScript assets for onboarding, dashboard, marketplace, messaging, offer builder, and offer catalog management. | | Athenian\ServiceProvider\Util | Houses provider, person, vendor, offer, geo, catalog, pricing, quote, cart, request-order, and SwapShop helper logic. | | Athenian\ServiceProvider\Messaging | Registers message REST routes and handles thread/message creation, unread tracking, and ASU message mirroring. | | Athenian\ServiceProvider\REST\Routes | Registers the main ath-sp/v1 REST API surface. | | Athenian\ServiceProvider\Integrations\ASU | Adds ASU editor integration, message permission behavior, and service request alerts. | | Athenian\ServiceProvider\Admin\Ajax | Provides nonce-protected admin AJAX search for people, vendors, and products. |

Custom Post Types

| CPT | Purpose | Public | REST | | --- | --- | --- | --- | | ath_vendor_profile | Legacy/local vendor profile record. | No | Yes | | ath_service_suggestion | Submitted missing-service suggestions. | No | Yes | | ath_sp_offer | Primary Service Offer model. | No | Yes | | ath_sp_message_thread | Buyer/provider message thread. | No | Yes | | ath_sp_message | Individual message inside a thread. | No | Yes |

Custom Taxonomies

| Taxonomy | Object Types | Purpose | | --- | --- | --- | | ath_service_cat | product, ath_vendor_profile | Hierarchical service categories used for onboarding and catalog filtering. | | ath_sp_service | ath_sp_offer | Non-hierarchical service type taxonomy for Service Offer classification. |

Data Model and Metadata

Service Offer Metadata

| Meta key | Purpose | | --- | --- | | _ath_sp_provider_person_id | Linked ASU/person record for the service provider. | | _ath_sp_vendor_id | Linked vendor profile ID. | | _ath_sp_vendor_user_id | Vendor user override or resolved vendor user. | | _ath_sp_active | Active/inactive state for search and quote flows. | | _ath_sp_service_key | Machine-friendly service key for filters and APIs. | | _ath_sp_offer_items_json | JSON array of offer catalog items. | | _ath_sp_swapshop_enabled | Whether the offer can be used for SwapShop listing flows. | | _ath_sp_target_id | Primary product or variation target. | | _ath_sp_product_id | Parent/simple product ID associated with the primary target. | | _ath_sp_geo_lat | Resolved offer latitude. | | _ath_sp_geo_lng | Resolved offer longitude. | | _ath_sp_geo_label | Resolved offer location label. |

Provider and Person Metadata

| Meta key | Purpose | | --- | --- | | ath_sp_provider_type | Provider type, such as freelance or licensed business. | | ath_sp_enabled | Provider marketplace enablement flag. | | ath_sp_website | Provider website. | | ath_sp_credentials | Credentials, licenses, insurance, or other provider notes. | | ath_sp_service_term_ids | JSON term ID list for selected service categories. | | ath_sp_variation_ids | JSON variation ID list for selected services. | | ath_sp_vendor_id | Vendor ID linked to a person. | | geo_lat | Person/provider latitude. | | geo_lng | Person/provider longitude. | | geo_label | Person/provider address or location label. | | geo_radius_mi | Provider service radius in miles. | | _ath_sp_person_user_id | Canonical person-to-user mapping helper. | | _ath_sp_person_offer_map | Person-level mapping of offer IDs to target IDs. |

Vendor Pricing Metadata

| Meta key | Purpose | | --- | --- | | _ab_vendor_pricing_offers | Canonical vendor pricing rows on product/variation targets. | | _apc_vendor_offers | Compatibility/listing rows for vendor offers. | | _regular_price | Baseline WooCommerce price persisted when needed for cart purchaseability. | | _price | WooCommerce active price persisted when needed for cart purchaseability. |

Vendor offer rows can contain:

• vendor_id
• price
• regular
• regular_price
• sale
• sale_price
• min_qty
• tiers
• lead_days
• status
• notes
• source
• updated_at

Messaging Metadata

| Meta key | Purpose | | --- | --- | | _ath_sp_msg_user_one_id | First thread participant. | | _ath_sp_msg_user_two_id | Second thread participant. | | _ath_sp_msg_pair_key | Normalized participant pair key. | | _ath_sp_msg_offer_id | Offer associated with the thread. | | _ath_sp_msg_subject | Thread subject. | | _ath_sp_msg_last_message_at | Last message timestamp. | | _ath_sp_msg_last_message_id | Last message post ID. | | _ath_sp_msg_last_sender_id | Last sender user ID. | | _ath_sp_msg_last_preview | Last message preview string. | | _ath_sp_msg_context_kind | Context type, such as offer or general. | | _ath_sp_msg_thread_id | Parent thread reference stored on individual message posts. | | _ath_sp_msg_last_read_{user_id} | Per-user read timestamp for unread tracking. |

REST API Surface

The plugin exposes a broad REST namespace under ath-sp/v1.

Utility and Debug

| Route | Method | Purpose | | --- | --- | --- | | /ath-sp/v1/ping | GET | Lightweight health check. | | /ath-sp/v1/debug/whoami | GET | Returns current user, roles, and capability context for debugging REST auth. |

Geography

| Route | Method | Purpose | | --- | --- | --- | | /ath-sp/v1/geo/autocomplete | GET | Server-side Google Places autocomplete proxy. | | /ath-sp/v1/geo/place | GET | Server-side Google Place Details proxy. |

Taxonomy and Catalog

| Route | Method | Purpose | | --- | --- | --- | | /ath-sp/v1/taxonomy/service-cats | GET | Lists ath_service_cat terms. | | /ath-sp/v1/catalog/variations | POST | Returns WooCommerce service variations based on selected service terms. | | /ath-sp/v1/catalog/search | GET | Staff-facing product/variation search for offer catalog editing. |

Onboarding

| Route | Method | Purpose | | --- | --- | --- | | /ath-sp/v1/onboard/save-profile | POST | Saves provider profile, geo, contact, website, credentials, and enablement data. | | /ath-sp/v1/onboard/save-categories | POST | Saves selected provider service category IDs. | | /ath-sp/v1/onboard/save-services | POST | Saves selected service variation IDs. | | /ath-sp/v1/suggest-service | POST | Creates an ath_service_suggestion record. |

Offer and Dashboard Management

| Route | Method | Purpose | | --- | --- | --- | | /ath-sp/v1/dashboard/state | GET | Returns legacy dashboard state for provider variation offers. | | /ath-sp/v1/offers/save | POST | Saves vendor pricing rows for provider offer items. | | /ath-sp/v1/offers/backfill | POST | Backfills offer linkages. | | /ath-sp/v1/offers | GET | Staff list of service offers. | | /ath-sp/v1/offers/{id} | GET | Returns a full offer payload when the user can access the offer. | | /ath-sp/v1/offers/{id}/link | PUT | Updates offer person, vendor, vendor user, target, and geo/product linkage. | | /ath-sp/v1/offers/{id}/items/upsert | POST | Adds or updates one offer item. | | /ath-sp/v1/offers/{id}/items/remove | POST | Removes an offer item by target ID. | | /ath-sp/v1/offers/{id}/catalog | GET | Returns expanded offer catalog items and product rows. | | /ath-sp/v1/offers/{id}/catalog | POST | Saves offer catalog items and syncs vendor pricing. | | /ath-sp/v1/offers/{id}/add-to-cart | POST | Adds a service item to WooCommerce cart with vendor/offer context. | | /ath-sp/v1/offers/competing | GET | Staff-facing comparison of other offers attached to a target product/variation. | | /ath-sp/v1/offers/people/search | GET | Staff-facing people lookup. | | /ath-sp/v1/offers/vendors/search | GET | Staff-facing vendor lookup. | | /ath-sp/v1/offers/products/search | GET | Product/variation lookup for offer editing. |

Person Offer Mapping

| Route | Method | Purpose | | --- | --- | --- | | /ath-sp/v1/people/{id}/offer-map | GET | Returns person user/vendor linkage and offer map. | | /ath-sp/v1/people/{id}/offer-map | POST | Saves person offer map and can ensure vendor linkage. |

SwapShop Integration

| Route | Method | Purpose | | --- | --- | --- | | /ath-sp/v1/integrations/swapshop/offers | GET | Lists SwapShop-eligible service offer options for the current user. | | /ath-sp/v1/integrations/swapshop/offers/{id}/targets/{target_id} | GET | Returns a service offer snapshot for a selected target. | | /ath-sp/v1/integrations/swapshop/offers/{id}/settings | POST | Updates offer-level SwapShop enablement/settings. |

Marketplace, Quote, and Request Order

| Route | Method | Purpose | | --- | --- | --- | | /ath-sp/v1/providers | GET | Public provider search by lat/lng, service key, radius, and result limit. | | /ath-sp/v1/quote | POST | Calculates quote amount from offer, target, quantity, vendor pricing, and optional pickup/dropoff distance. | | /ath-sp/v1/request-order | POST | Creates a pending WooCommerce service request order with provider/vendor metadata. |

Messaging

| Route | Method | Purpose | | --- | --- | --- | | /ath-sp/v1/messages/threads | GET | Lists message threads for the current user and unread count. | | /ath-sp/v1/messages/threads/start | POST | Starts or finds a thread and creates the first message. | | /ath-sp/v1/messages/threads/{id} | GET | Loads thread detail and messages. | | /ath-sp/v1/messages/threads/{id}/reply | POST | Adds a reply to the thread. | | /ath-sp/v1/messages/threads/{id}/read | POST | Marks a thread read for the current user. |

WooCommerce Integration Details

Product and Variation Targets

Offer items can target either simple products or variation IDs. When a target is a variation, the plugin resolves the parent product title, variation label, SKU, image, price HTML, parent status, and target status for editor and frontend payloads.

Vendor Pricing

Vendor pricing is saved against the WooCommerce product or variation target rather than only inside the Service Offer record. This supports broader Athenian vendor routing, comparison, catalog, and dropship workflows.

The plugin normalizes tiered pricing rows and chooses unit price based on the selected quantity. It prefers tier prices when a valid quantity tier is matched, then falls back to sale/regular/price data as available.

Add-to-Cart Context

The add-to-cart endpoint initializes WooCommerce session, customer, and cart state for REST contexts, validates target availability, resolves vendor offer pricing, persists a baseline product price when needed for WooCommerce purchaseability, and inserts cart item data such as:

• ath_sp_vendor_id
• ath_sp_offer_id
• ath_sp_label
• ath_sp_notes
• ath_sp_unit_price
• ath_sp_vendor_offer
• ath_sp_source
• ath_sp_key

Request Order Metadata

When creating a service request order, the plugin stores both order-level and item-level metadata for:

• Offer ID.
• Service key.
• Provider person ID.
• Vendor ID.
• Target ID.
• Quantity.
• Unit price.
• Distance in kilometers.
• Raw request JSON.

It creates the order as pending and returns the order ID, total, currency, and payment URL when available.

Athenian Platform Integrations

Athenian Social Users Core

When ASU is available, the plugin extends the ASU person schema with provider-specific fields, adds a Service Offers tab/panel to the ASU person editor, allows contextual service-provider messages, and can create ASU alerts when a service request order is created.

Athenian WooCommerce Dropship / Vendor Pricing

The plugin detects Athenian WCDropship-style vendor profile structures and reads/writes vendor offer pricing rows. It can resolve a vendor profile from user meta, ASU person metadata, vendor post author, or plugin-defined filters.

Athenian SwapShop

Service offers can be made available to SwapShop. The provider dashboard includes a SwapShop toggle and listing action. REST endpoints expose eligible offer options, target snapshots, and settings updates for listing workflows.

Google Places

The plugin includes helpers for server-side Google Places autocomplete and place details, using the ath_sp_google_maps_key option or a defined key constant. This is intended to keep the Google API key on the server side rather than shipping it directly to browser JavaScript.

Security and Permission Model

• Logged-out users are blocked from provider onboarding saves, dashboard state, service selection saves, messaging, and request-order creation.
• Staff routes generally require edit_posts, edit_products, or manage_woocommerce depending on the endpoint.
• Offer access checks allow administrators/staff or the linked vendor user, linked vendor profile owner, or linked provider person.
• Admin AJAX handlers verify edit capability and accept nonce values for offer editor contexts.
• REST requests use WordPress REST nonces from localized frontend/admin scripts.
• Messaging routes require login and verify that the current user is a participant in the thread unless they are an administrator.
• Service request orders are created only for logged-in users.
• Google Places keys are resolved server side rather than exposed directly by the shortcode.

Hooks and Extension Points

| Hook/filter | Purpose | | --- | --- | | ath_sp/vendor_user_meta_key | Filters the user meta key used for user-to-vendor lookup. | | ath_sp/vendor_post_user_meta_key | Filters the vendor post meta key used for vendor-to-user lookup. | | ath_sp/person_post_type | Filters the person post type, defaulting to asu_person. | | ath_sp/person_user_id_meta_key | Filters the person-to-user meta key. | | ath_sp_swapshop_listing_url | Filters the SwapShop listing URL used by the provider dashboard. | | ath_sp_offer_swapshop_contract_changed | Fires when offer SwapShop contract/options change. | | ath_sp_service_request_order_created | Fires after a service request order is created. | | asu_person_meta_schema | Extended by the plugin when ASU is available. | | asu_message_send_allowed | Allows service-provider platform contextual messages. | | asu_person_editor_tabs | Adds Service Offers tab to ASU person editor. | | asu_person_editor_render_panel | Renders Service Offers panel in ASU person editor. |