Athenian AI Chat & Recommendations

Developer starting point

This baseline documents the reviewed chat/recommendation architecture. It does not claim that an external AI provider request or end-user conversation has been exercised.

Technical Architecture

Bootstrap and Load Order

The main plugin file defines constants, helper functions, includes the module files in an intentional order, registers activation hooks, and boots the plugin on plugins_loaded.

Key constants include:

define( 'AWCAI_PLUGIN_FILE', __FILE__ );
define( 'AWCAI_PLUGIN_DIR', plugin_dir_path( __FILE__ ) );
define( 'AWCAI_PLUGIN_URL', plugin_dir_url( __FILE__ ) );
define( 'AWCAI_PLUGIN_VERSION', '1.0.1' );

Load order is important because REST handlers and live chat modules depend on the core, credentials, tools, conversations, and live chat classes being available first.

Primary PHP Classes

| Class | Responsibility | |---|---| | AWC_AI_Config | Default theme values and system prompt template. | | AWC_AI_Creds | OpenAI/Twilio credential lookup, preferring SecureStore when available. | | AWC_AI_Core | Central OpenAI and tool-calling facade. | | AWC_AI_Tools | Tool schema registry and dispatcher. | | AWC_AI_Router | Search-plan construction and keyword extraction. | | AWC_AI_REST | Main REST endpoints for chat and index status. | | AWC_AI_Shortcode | [awc_ai_chat] shortcode and frontend asset registration. | | AWC_AI_Indexer | WooCommerce product index build/status/integrity logic. | | AWC_AI_Index_Search | JSON index loading, prompt normalization, scoring, and fallback search. | | AWC_AI_Customer_Context | Customer, order, address, phone, and tracking context helpers. | | AWC_AI_Conversations | Conversation and message table management. | | AWC_AI_LiveChat | Popup widget, state table, capabilities, auto-injection helpers. | | AWC_AI_LiveChat_REST | Live chat REST endpoints for users and agents. | | AWC_AI_LiveChat_Admin | WooCommerce admin live chat console. | | AWC_AI_SMS_Router | Twilio SMS webhook and debug routes. | | AWC_AI_Voice_Router | Twilio voice webhook and TwiML response handling. | | AWC_AI_Twilio | Twilio SMS/MMS send helper. | | AWC_AI_TTS | Extension point for speech synthesis URL generation. |

Frontend and Admin Assets

| Asset | Purpose | |---|---| | assets/js/chat.js | Embedded shortcode chat behavior, REST submission, message rendering, recommendation cards. | | assets/css/chat.css | Embedded chat UI styling. | | assets/js/chat-popup.js | Popup/live chat widget, conversation open, polling, streaming, send fallback. | | assets/css/chat-popup.css | Popup widget styling. | | assets/js/admin-livechat.js | Admin agent console behavior. | | assets/css/admin-livechat.css | Admin live chat console styling. |

Assets use a cache-busting helper that appends filemtime() to the plugin version where possible.

---

REST API Surface

Main Chat Routes

| Method | Route | Purpose | Permission | |---|---|---|---| | POST | /wp-json/awcai/v1/chat | Handles embedded chat messages and product recommendations. | Public | | GET | /wp-json/awcai/v1/index-status | Returns product index status. | manage_options |

Live Chat Routes

| Method | Route | Purpose | |---|---|---| | POST | /wp-json/awcai/v1/conversation/open | Opens/creates a web conversation. | | GET | /wp-json/awcai/v1/conversations | Lists conversations for agents. | | GET | /wp-json/awcai/v1/conversation/{id} | Reads conversation state/details. | | GET | /wp-json/awcai/v1/conversation/{id}/messages | Reads conversation messages. | | POST | /wp-json/awcai/v1/conversation/{id}/send | Sends a user message with non-streaming response. | | POST | /wp-json/awcai/v1/conversation/{id}/send-stream | Sends a user message with streaming response. | | POST | /wp-json/awcai/v1/conversation/{id}/agent-send | Sends an agent reply. | | POST | /wp-json/awcai/v1/conversation/{id}/takeover | Switches conversation to human/agent mode. | | POST | /wp-json/awcai/v1/conversation/{id}/handoff-ai | Returns conversation to AI mode. | | POST | /wp-json/awcai/v1/conversation/{id}/close | Closes a conversation. |

Live chat permissions distinguish guest users, conversation owners, logged-in users, and agents. Agent actions require the awcai_live_chat_agent capability and REST nonce verification where appropriate.

SMS and Voice Routes

| Method | Route | Purpose | |---|---|---| | POST | /wp-json/awcai/v1/sms | Handles inbound SMS/Twilio webhook messages. | | GET | /wp-json/awcai/v1/sms-context | Debug route for sender/customer context. | | GET | /wp-json/awcai/v1/sms-search | Debug route for SMS product search. | | POST | /wp-json/awcai/v1/voice | Handles Twilio Voice webhook requests. |

---

Data Model

Database Tables

#### wp_awcai_conversations

| Column | Notes | |---|---| | id | Primary key. | | channel | Conversation channel such as web/SMS/voice. | | sender_key | User, phone, session, or call-derived sender key. | | session_key | Session identifier. | | created_at | Conversation creation time. | | updated_at | Last update time. |

Indexes include channel_sender and channel_sender_session.

#### wp_awcai_messages

| Column | Notes | |---|---| | id | Primary key. | | conversation_id | Parent conversation ID. | | role | system, user, assistant, tool, or agent. | | content | Message content. | | meta | JSON metadata. | | created_at | Message timestamp. |

Indexes include conv_created and conv_role.

#### wp_awcai_conversation_state

| Column | Notes | |---|---| | conversation_id | Primary key and link to conversation record. | | mode | Conversation mode, default ai. | | status | Conversation status, default open. | | assigned_agent | Optional user ID of assigned agent. | | meta | JSON metadata. | | last_user_seen_at | User read marker. | | last_agent_seen_at | Agent read marker. | | updated_at | Last state update timestamp. |

Indexes include mode_status, assigned_agent, and updated_at.

File-Based Index Data

The catalog index is stored as:

uploads/awcai-index/index.json

The index contains products and _meta details such as build time, schema version, source count, and indexed product count. Atomic writes reduce the risk of partial/corrupt index files during rebuilds.

Debug Log

The plugin includes a JSON-line debug logger that writes to:

uploads/awcai-debug/chat.log

Debug entries are used across chat, prefetch, index rebuild, search, and related observability flows.

---

Admin Workflow

A typical merchant/admin workflow is:

1. Install and activate the plugin.
2. Configure credentials through Athenian Secure API Key Manager or plugin-local settings.
3. Open Settings → Athenian AI Chat.
4. Enter or verify OpenAI configuration.
5. Customize the chat theme colors.
6. Review or override the system prompt template.
7. Rebuild the WooCommerce product index.
8. Run the index integrity check.
9. Add [awc_ai_chat] to a page or template area.
10. Add [awc_ai_chat_popup] or enable auto-injection for the floating widget.
11. Grant selected staff the awcai_live_chat_agent capability.
12. Use WooCommerce → Live Chat to monitor, take over, reply to, or close conversations.

---

Customer and Agent Workflow

Shopper Workflow

1. Shopper opens chat on the storefront.
2. Shopper asks a product or support question.
3. The plugin normalizes the message and pre-searches the WooCommerce product index when the prompt looks like a catalog lookup.
4. Matching products are returned as recommendation cards when available.
5. For broader support questions, OpenAI receives structured context and available tool schemas.
6. The assistant responds with grounded product/account/order guidance.
7. If the conversation needs a human, support staff can take over the same thread.

Authenticated Customer Workflow

1. Logged-in customer asks about orders, tracking, or account details.
2. Customer context resolves from the active WordPress user.
3. Tool calls can retrieve account, order, and tracking data.
4. Address-update operations require explicit confirmation safeguards before changing metadata.

Live Agent Workflow

1. Agent opens WooCommerce → Live Chat.
2. Agent reviews open conversations.
3. Agent selects a thread and reads context/history.
4. Agent clicks Take over to switch the conversation away from AI mode.
5. Agent sends a human reply.
6. Agent can click Return to AI or Close when complete.

---

Security and Privacy Notes

• OpenAI credentials are looked up through Athenian Secure API Key Manager when available.
• Plugin-local OpenAI key entry is still available as a fallback.
• Agent routes require the awcai_live_chat_agent capability.
• Management/index routes require manage_options.
• Logged-in REST POST actions use nonce verification where appropriate.
• Guest live chat is tracked with a generated awcai_sid cookie instead of requiring a user account.
• Customer account/order tools require authenticated customer context.
• Address updates require both tool-level confirmation and recent-message verification.
• The system prompt explicitly instructs the AI not to fabricate products, customer data, bookings, orders, or completed actions.
• SMS opt-outs are tracked in the awcai_sms_optouts option.

---

Implementation Notes from Code Inspection

• PHP syntax checks passed for all PHP files in the uploaded package.
• The package does not register custom post types or taxonomies.
• The plugin uses custom database tables for conversations and live chat state.
• The plugin uses file-based JSON indexing rather than a custom product-index database table.
• The main OpenAI call currently targets https://api.openai.com/v1/chat/completions.
• AWC_AI_TTS::synthesize_to_url() is currently a lightweight extension point and does not implement a production TTS provider by itself.
• The voice and SMS endpoints are public webhook endpoints by design, and should be protected in production with shared-secret validation, Twilio request validation, WAF rules, or gateway restrictions where appropriate.
• The get_openai_api_key() helper in the bootstrap reads awcai_openai_api_key, while AWC_AI_Creds prefers SecureStore and then reads awcai_settings. This is workable as layered fallback behavior, but production configuration should standardize where credentials are stored.
• The admin settings page currently registers awcai_openai_api_key, awcai_theme, and awcai_system_prompt; additional credential fields for Twilio/model settings appear to be read from awcai_settings or filters rather than fully exposed in the inspected admin page.
• The bundled docs/response-contract-training-fixtures.json reinforces safe response behavior for no-results catalog searches, catalog matches, and account-address update confirmation.

---