Architecture and Data Storage
The bootstrap assembles settings, local assistants, response service, security/logging, admin modules, tools, WhatsApp, scraper, database, design preview, wizard, and private updater.
The architecture reference identifies where a request enters, which services transform it, and where state remains afterward. WordPress options hold most configuration, a custom table holds detailed logs, uploads hold knowledge and copied widget files, transients hold short-lived response/security state, browser storage holds visitor state, and external providers hold AI/channel/tool data.
Start with the smallest safe step: start at ai-website-chat.php and confirm the deployed plugin source. Do not consider the task finished before you update the feature coverage matrix whenever behavior changes; this is where the configuration is tested in the context that truly consumes it.
What this feature does and when to use it
Section titled “What this feature does and when to use it”Use this map for extension, backup, incident response, and documentation audits.
Use this feature in the following situations:
- You are planning backup, migration, incident response, privacy deletion, or an extension.
- A user-facing feature must be traced from admin control to saved state and runtime consumer.
- A plugin release changes schema, service construction, or an external data flow.
Where to find it
Section titled “Where to find it”Before you begin
Section titled “Before you begin”- Read-only access to the exact deployed plugin source.
- WordPress/PHP development experience.
- A sanitized staging database; never inspect production secrets casually.
Set it up step by step
Section titled “Set it up step by step”- Start at ai-website-chat.php and confirm the deployed plugin source.
- Trace run_ai_website_chat() service construction.
- Trace public REST chat into Smartsite_OpenAI_Response_Service, Security, tool execution, response state, and Conversation Logger.
- Trace admin tabs through class-admin.php, views, JavaScript, handlers, options, and runtime consumers.
- Inventory WordPress options, transients, uploads, OpenAI vector/files/responses, browser localStorage, and the log table.
- Confirm activation/deactivation/updater paths.
- Update the feature coverage matrix whenever behavior changes.
Fields, controls, and important values
Section titled “Fields, controls, and important values”These storage locations show which information contributes to a reply and which information supports delivery, history, analytics, or security. Tracing a value to its owner helps developers avoid stale state and accidental disclosure. Changes to assistant options, knowledge mappings, response chains, or tool results can alter generated context; changing logs alone does not retrain or improve the AI.
| Field, control, or status | What SmartSite Assistant does with it | How to use it and why it matters |
|---|---|---|
| Local assistant options | ai_chat_assistants and ai_website_chat_openai_assistant_id. | These options hold the profile collection and the identifier of the profile selected for runtime. Changes can directly alter model choice and instructions, so use the public management flow rather than editing serialized values by hand. |
| Knowledge options/uploads | Selected pages, page metadata/vector mappings, vector store ID/files, and WordPress uploads for knowledge files/copied app assets. | This state connects selected WordPress sources, metadata, remote mappings, vector-store files, and copied assets. Keeping those relationships consistent is essential; a dangling mapping can make current content appear synchronized while retrieval still points elsewhere. |
| Configuration options | OpenAI keys/project, smartsite_visibility_settings, design_settings, smartsite_agent_tools, smartsite_channel_whatsapp, smartsite_security_settings, wizard data. | “Configuration options” defines an audience or assistant scope, not permission to disclose sensitive information. Keep the scope as narrow as practical, test one allowed and one denied case, and enforce real authorization inside every data-returning tool. |
| Custom table | {$wpdb->prefix}smartsite_logs, schema/database version 1.5.0. | The SmartSite log table records conversation and operational evidence used by analytics, diagnostics, and moderation. It does not train the model or improve replies automatically, and its full prompt and response columns require careful access and retention controls. |
| Transient/browser/remote state | Rate/behavior and response-chain caches; localStorage user_token/chat_messages; OpenAI stored responses/vector/files; Meta/tool destinations. | Short-lived counters, response-chain identifiers, browser history, and provider-side resources span several owners. Trace which layer supplies context before clearing it, because removing a browser cache may leave server continuity intact and deleting a transient may affect follow-up coherence. |
How to confirm it is working
Section titled “How to confirm it is working”Use a separate test session to confirm Architecture and Data Storage. This keeps existing login, browser storage, and response history from hiding the change, and it shows whether the result reaches the complete workflow rather than stopping at WordPress storage.
Practical example
Section titled “Practical example”A page metadata change updates local metadata/hash state, becomes Pending, then sync replaces the remote OpenAI file and records the new hash.
Recommended practice
Section titled “Recommended practice”- Change one part of Architecture and Data Storage at a time and keep a short record of the previous value and test result.
- Verify the saved result in the screen, visitor session, or connected service that actually consumes the setting.
Important warnings
Section titled “Important warnings”Common problems and focused checks
Section titled “Common problems and focused checks”| Problem | What to check and what to do next |
|---|---|
| Architecture and Data Storage is missing or does not match this guide. | Confirm the plugin is active and the account can manage WordPress options. Trace the request through capability, nonce or public validation, storage, runtime consumption, and error handling. |
| A change on Architecture and Data Storage does not produce the expected result. | Keep the exact notice and test case, then review the browser console and WordPress/PHP log. Trace the request through capability, nonce or public validation, storage, runtime consumption, and error handling. |
Screen reference
Section titled “Screen reference”- Capture
- Create a maintainer diagram from the audited source showing WordPress admin/runtime, OpenAI, browser, Meta/tools, and the log table; use synthetic labels only.
- Show
- Bootstrap/services, options/table/uploads, REST, OpenAI, Meta/tools, browser state
- Viewport
- Desktop, 1440 × 900
- Annotate
- Use numbered callouts only for controls referenced in the procedure.
- Redact
- OpenAI keys, tokens, secrets, personal information, private URLs, IP addresses, and conversation text