Athenian Taste Intelligence Platform

Developer starting point

This baseline documents the Taste Intelligence architecture. It does not claim that a live profile, recommendation, AI request, feedback record, or partner report has been exercised.

Technical and Marketing Brief

Version documented: plugin 0.3.0 Platform: WordPress, WooCommerce, PHP 7.4+ Primary audience: Athenian Brands operators, food and snack brands, manufacturers, distributors, retail partners, marketplace partners, and implementation teams

---

2. Configurable Catalog Field Definitions

The plugin includes an admin screen for defining extra product, ingredient, and nutrition fields.

Field Families

Dynamic fields are grouped into:

• Product
• Ingredient
• Nutrition

Supported Field Types

• Text
• Textarea
• Number
• Select
• Multi-select

Field Targeting

Fields can be shown for all products or targeted by:

• WooCommerce product categories
• WooCommerce product tags
• Taste tags
• Dietary tags
• Usage contexts

AI and Reporting Controls

Each field can be configured for:

• AI weight from 0 to 10
• Required data quality flag
• Filterable/facet availability
• Use in recommendations
• Use in reports
• Use in embedding payloads

Seeded Default Fields

The plugin seeds a practical food and snack catalog schema, including:

• Package size
• Package type
• Servings per container
• Shelf life
• Storage instructions
• Preparation instructions
• Snack occasions
• Flavor families
• Flavor notes
• Audience segments
• Texture traits
• Aroma notes
• Finish traits
• Ingredient statement
• Key ingredients
• Certifications
• Sourcing notes
• May-contain statements
• Ingredient claims
• Serving size
• Calories
• Protein
• Total fat
• Carbohydrates
• Total sugars
• Dietary fiber
• Sodium
• Nutrition positioning

This lets the platform support product discovery, AI prompts, merchandising, nutrition filters, and partner reporting without hardcoding every future field into PHP.

---

3. Taste, Dietary, and Usage Taxonomies

The plugin registers three private but admin-visible product taxonomies:

• ath_taste_tag
• ath_dietary_tag
• ath_usage_context

These taxonomies are available in the WordPress admin and REST API. They are not public-facing archive taxonomies by default, which keeps them focused on internal intelligence, reporting, and recommendation logic.

Practical Examples

Taste tags might include:

• Sweet
• Savory
• Smoky
• Citrus
• Spicy
• Nutty

Dietary tags might include:

• Vegan
• Gluten-free
• Keto-friendly
• Halal
• Low sodium

Usage contexts might include:

• Lunchbox
• Movie night
• Post-workout
• Party sharing
• On-the-go
• Desk snack

---

8. Partner API

The plugin includes a partner-facing REST API for controlled external access.

API Key Model

Partner keys are:

• Created from the WordPress admin
• Linked to a WordPress user account
• Stored only as password hashes
• Identified internally by a key prefix
• Revocable
• Tracked with last-used timestamp and IP address

Access Scoping

Each key can be scoped by:

• Linked vendor CPT IDs
• Explicit product IDs
• Allowed custom post types
• API scopes

Supported scopes:

• products.read
• reports.read
• cpt.read

Vendor Product Resolution

Vendor-linked product access can be resolved through common vendor meta keys:

• vendor
• vendor_id
• _vendor
• _vendor_id
• ab_vendor
• ab_vendor_id
• apc_vendor_id

The plugin also exposes filters so developers can customize partner product access and vendor meta resolution.

Partner Use Cases

The partner API supports:

• Manufacturer access to only their products
• Distributor access to a bounded catalog set
• Vendor-facing product performance dashboards
• External reporting tools
• Retail partner data feeds
• White-label portals
• Integration with Athenian Brands internal systems

---

REST API Reference

Base namespace:

/wp-json/ath-tip/v1

Public Feedback Endpoint

POST /feedback

Stores product taste feedback. Publicly callable when the feedback widget is active.

Common payload fields:

{
  "product_id": 123,
  "source": "product_page",
  "overall_rating": 5,
  "taste_match": 5,
  "repurchase_intent": 4,
  "would_recommend": 1,
  "age_band": "35-44",
  "region": "Midwest",
  "household_type": "Family",
  "dietary_identity": "Gluten-free",
  "tasting_notes": "Crunchy texture with a balanced savory finish.",
  "metadata": {
    "preferred_flavor_notes": ["Cheese", "Sea Salt"],
    "avoided_flavor_notes": ["Smoke"],
    "preferred_textures": ["Crunchy"],
    "sweetness_preference": "Balanced",
    "heat_preference": "Mild",
    "adventurousness": "Balanced"
  }
}

Admin Report Endpoint

GET /report?from=2026-04-01&to=2026-04-30

Requires manage_woocommerce or manage_options.

Returns summary metrics, top products, demographic breakdowns, regional breakdowns, and taste tag breakdowns.

Admin Product Intelligence Endpoint

GET /product/{id}

Requires manage_woocommerce or manage_options.

Returns a product intelligence profile and feedback summary.

Recommendation Endpoint

GET /recommendations

Common query parameters:

• product_id
• limit
• context_label
• dietary_identity
• exclude_allergens
• product_ids
• track_impression
• include_prompt
• include_profile

Example:

GET /recommendations?product_id=123&limit=6&context_label=lunchbox&exclude_allergens=peanuts&include_prompt=1

Shopper Profile Endpoint

GET /profile

Returns the current logged-in user or session taste profile.

Recommendation Event Endpoint

POST /recommendation-event

Records recommendation interactions.

Allowed event types:

• impression
• click
• add_to_cart
• purchase
• dismiss
• feedback_submitted

Example:

{
  "product_id": 123,
  "event_type": "click",
  "event_value": 1,
  "context_label": "recommended_for_you",
  "metadata": {
    "surface": "product_page"
  }
}

Partner Endpoints

All partner endpoints require an API key in X-API-Key or Authorization: Bearer.

GET /partner/me
GET /partner/products
GET /partner/products/{id}
GET /partner/reports/summary
GET /partner/reports/products
GET /partner/cpt/{post_type}

Example:

curl -H "X-API-Key: YOUR_KEY" "https://example.com/wp-json/ath-tip/v1/partner/reports/summary"

---

Data Model

The plugin creates dedicated database tables.

Feedback Table

Table:

wp_ath_taste_feedback

Purpose:

• Stores product feedback submissions.
• Supports product reporting, demographic breakdowns, taste profile generation, and recommendation quality signals.

Key fields:

• Product ID
• User ID
• Session ID
• Source
• Context label
• Overall rating
• Taste match
• Repurchase intent
• Would recommend
• Age band
• Region
• Household type
• Dietary identity
• Tasting notes
• Metadata JSON
• Created timestamp

Partner Keys Table

Table:

wp_ath_taste_partner_keys

Purpose:

• Stores scoped API key records for external partners.

Key fields:

• Linked user ID
• API label
• Key prefix
• Key hash
• Vendor IDs
• Product IDs
• Allowed post types
• Scopes
• Status
• Created timestamp
• Last used timestamp
• Last used IP
• Revoked timestamp

User Profiles Table

Table:

wp_ath_taste_user_profiles

Purpose:

• Stores cached taste profiles by logged-in user or anonymous session.

Key fields:

• Identity type
• Identity key
• User ID
• Session ID
• Profile JSON
• Feedback count
• Confidence
• Last feedback timestamp
• Updated timestamp

Recommendation Events Table

Table:

wp_ath_taste_recommendation_events

Purpose:

• Stores recommendation impressions and downstream interactions.

Key fields:

• Identity type
• Identity key
• User ID
• Session ID
• Product ID
• Event type
• Event value
• Context label
• Metadata JSON
• Created timestamp

---

Security and Access Control

WordPress Capability Checks

Admin reporting and product intelligence endpoints require:

• manage_woocommerce, or
• manage_options

Admin pages use the same capability model.

Public Endpoints

The feedback endpoint is public so shoppers can submit product feedback. The recommendation and profile endpoints are public only when the recommendations feature is enabled in plugin settings.

Partner Authentication

Partner endpoints require API authentication. Keys are never stored in plain text after creation. The plugin stores a password hash and checks submitted keys with WordPress password verification.

Partner Authorization

Partner keys support:

• Scope checks
• Product scoping
• Vendor scoping
• Allowed post type scoping
• Revocation

Privacy Considerations

The platform can collect demographic and preference data. A production deployment should align the storefront privacy policy, consent language, retention policy, and partner data-sharing terms with the exact fields enabled in settings.

---

Technical Architecture

Bootstrap

The main plugin file defines constants, declares WooCommerce custom order table compatibility, loads the autoloader, and boots the plugin singleton.

Booted Components

On plugins_loaded, the plugin initializes:

• Database installer and upgrades
• Product taxonomies
• Product metadata fields
• Feedback/session handling
• Admin REST routes
• Recommendation REST routes
• Partner REST routes
• Feedback widget
• Admin screens when in the WordPress dashboard

Main Modules

| Module | Responsibility | | --- | --- | | DB\Installer | Creates and upgrades plugin tables, seeds default options and field definitions. | | Core\Product_Meta | Registers product meta, renders WooCommerce product fields, saves product intelligence data. | | Core\Product_Field_Definitions | Manages dynamic product, ingredient, and nutrition field definitions. | | Core\Taxonomies | Registers taste, dietary, and usage-context taxonomies. | | Core\Feedback | Handles feedback sessions, sanitization, inserts, and profile refreshes. | | Core\Profile_Builder | Builds cached user or session taste profiles from feedback history. | | Core\Recommendation_Engine | Scores product recommendations and returns ranked results with reasons. | | AI\Prompt_Builder | Builds OpenAI-ready recommendation prompt payloads from profile and candidate data. | | Core\Reports | Builds admin and partner reporting summaries and CSV rows. | | Core\Partner_Keys | Creates, stores, authenticates, scopes, and revokes partner API keys. | | Core\Partner_Access | Resolves scoped product and CPT access for partner keys. | | API\REST | Registers feedback, admin report, and product profile endpoints. | | API\Recommendations_REST | Registers recommendation, profile, and event endpoints. | | API\Partner_REST | Registers partner API endpoints. | | Frontend\Feedback_Widget | Renders the shortcode and auto-rendered WooCommerce feedback form. | | Admin\Admin | Registers admin menus, settings, reporting dashboard, field editor, partner key UI, and CSV export. |

---

Example End-to-End Workflow

1. An admin defines catalog intelligence fields for snack products.
2. Product managers enrich WooCommerce products with taste, texture, ingredient, nutrition, and demographic-fit data.
3. Products are tagged with private taste, dietary, and usage-context taxonomies.
4. A shopper visits a product page and submits taste feedback.
5. The plugin stores the feedback and refreshes the shopper's taste profile.
6. The recommendation endpoint ranks additional products using the shopper profile and product metadata.
7. The frontend displays recommended products with evidence-based reasons.
8. Recommendation impressions, clicks, add-to-cart actions, purchases, or dismissals can be recorded.
9. Admins review performance in the Taste Intel dashboard.
10. Partners access scoped product and report data through API keys or receive CSV exports.

---

Implementation Status

Implemented Now

• WordPress/WooCommerce plugin bootstrap
• WooCommerce custom order table compatibility declaration
• Product taste intelligence tab
• Base product taste metadata
• Sensory scoring
• Dynamic catalog field definitions
• Seeded product, ingredient, and nutrition fields
• Private taste, dietary, and usage taxonomies
• Product list columns
• Customer-facing feedback widget
• Feedback shortcode
• Automatic WooCommerce product-page rendering
• Feedback database table
• Partner key database table
• Shopper profile database table
• Recommendation event database table
• Admin reporting dashboard
• CSV export
• Admin settings
• Partner API key creation and revocation
• Partner REST API
• Feedback REST endpoint
• Admin report REST endpoint
• Product intelligence REST endpoint
• Recommendation REST endpoint
• Shopper profile REST endpoint
• Recommendation event endpoint
• Deterministic recommendation scoring
• OpenAI-ready recommendation prompt payloads

Current Boundaries

• The plugin prepares OpenAI-ready prompt payloads but does not directly call OpenAI in this version.
• Embedding generation and vector retrieval are not yet implemented.
• Recommendation quality depends on product metadata depth and feedback volume.
• Partner product scoping depends on vendor IDs, explicit product IDs, or custom filters.
• Privacy, consent, and data retention language should be finalized before collecting demographic data at scale.
• Production uninstall behavior and data retention should be reviewed against the desired policy before broad deployment.

---