Architecture · Local AI + governed backend
Private AI and RAG Backend Architecture for WordPress
Use supported on-device AI where it fits, then route workloads that need server-side models, RAG, citations or public frontend access to a configured backend rather than a mandatory shared plugin SaaS runtime.
WordPress editor / frontend
├→ supported local AI
└→ configured API endpoint
↓
API Gateway + Lambda
├→ Bedrock model access
├→ knowledge retrieval
└→ logs / controls
WordPress remains the content source; backend ownership is explicit.
Trust and data path
Local processing and backend processing are distinct execution modes
AI-Kit can perform supported tasks locally in compatible browsers. Pro workflows can instead use a configured API endpoint, typically in the customer's AWS account. Public chatbot and DocSearch features need a browser-reachable backend path because the visitor cannot depend on WordPress PHP after static publishing.
Editor task
├→ local browser model when supported
└→ /admin/* configured backend route
Visitor chatbot / DocSearch
→ /frontend/* configured backend route
→ retrieval / model execution
→ answer + source data
Knowledge sources
WordPress content → prepared documents + metadata → knowledge backend
Boundary A configured backend does not make every AI action local or private by definition. The important architectural decision is where each workload executes, which content crosses that boundary, and who controls the backend, logs and model access.
What the AI-Kit backend stack provisions
The backend is a collection of explicit runtime responsibilities, not one opaque AI proxy. This inventory shows the API, model, retrieval, storage, abuse-control and observability components behind the configured path.
| Building block | Purpose | Key design choice | Operational note |
|---|---|---|---|
| API Gateway REST API | Exposes admin and optional frontend AI routes | /admin/* is always the trusted surface; /frontend/* appears only when feature toggles enable it | Keep public and privileged routes separate even when they share handler code. |
| AiHandlerFunction | Unified Lambda handler for prompt and language capabilities | One warm execution path for prompt, write, rewrite, summarize, translate, proofread, detect-language and KB listing | Shared validation, metrics, guardrails and middleware reduce operational spread. |
| Amazon Bedrock models | Runs generation, translation-style tasks and RAG answer synthesis | Frontend model can be cheaper/lighter than admin model through parameterized model selection | Model IDs are architecture parameters, not hard-coded plugin assumptions. |
| Bedrock Knowledge Base + S3 Vectors | Provides managed retrieval over documentation or client content | Create a new KB or reuse an existing one via stack parameters | KnowledgeBaseId and DataSourceId outputs are part of the integration contract. |
| Docs and temp assets S3 bucket | Stores KB documents and temporary prompt image uploads | Separate document prefix, configuration prefix and temp-assets prefix | Temp image objects should expire quickly; KB documents should be versioned deliberately. |
| KnowledgeBaseSyncFunction | Runs document ingestion workflows | S3/EventBridge/DynamoDB debounce loop avoids starting ingestion for every small file event | Useful when WordPress regenerates multiple KB documents during publishing. |
| reCAPTCHA + SSM/KMS | Protects open frontend endpoints | Secret stored as encrypted SSM parameter and fetched by handlers | Important when FrontendApiAuthMode is NONE for static-site friendliness. |
| AWS WAF and throttling | Limits abuse on public/admin API paths | Separate allow/deny/rate rules for frontend and admin surfaces | AI endpoints are cost-bearing; public access needs protection beyond CORS. |
| CloudWatch, DLQ and alerts | Provides logs, metrics, failed invocation capture and optional notifications | Per-function log retention, custom metrics and shared SQS DLQ | AI features need observability because cost, latency and quality are all runtime concerns. |
Endpoint surface: one backend, two trust zones
The backend can expose several capabilities, but admin and frontend routes must remain distinct. This table shows which visitor routes exist only when their feature is enabled and which configuration routes stay admin-only.
| Capability | Admin route | Frontend route | When frontend is created | Design note |
|---|---|---|---|---|
| Prompt / chatbot / DocSearch | /admin/prompt | /frontend/prompt | EnableChatbotBackend=true | Can use KB, citations, regeneration, feedback metadata and optional image inputs. |
| Generate upload URL | /admin/generate-upload-url | /frontend/generate-upload-url | EnableChatbotBackend=true | Uploads images to S3 via presigned PUT, then passes keys to prompt requests. |
| Summarize | /admin/summarize | /frontend/summarize | EnableSummarizerBackend=true | Summarization usually disables KB by default because the source text is already supplied. |
| Writer | /admin/write | /frontend/write | EnableLanguageAIBackend=true | Useful as backend fallback for editor or frontend generation features. |
| Rewriter | /admin/rewrite | /frontend/rewrite | EnableLanguageAIBackend=true | Honors tone, format and length controls while keeping secrets out of the browser. |
| Translator | /admin/translate | /frontend/translate | EnableLanguageAIBackend=true | Can be paired with automatic language detection flows. |
| Proofreader | /admin/proofread | /frontend/proofread | EnableLanguageAIBackend=true | Returns corrected text and structured correction metadata. |
| Language detector | /admin/detect-language | /frontend/detect-language | EnableLanguageAIBackend=true | Uses a backend language detection path instead of assuming the browser always provides it. |
| Knowledge bases | /admin/knowledge-bases | Not a public route | Admin only | Listing and selecting backend knowledge resources belongs to trusted configuration UX. |
Grounding policy is a product decision
Retrieval behavior should match the risk and user expectation of the experience. This table compares strict KB-only answers, clarification-first behavior and KB-preferred answers.
| Grounding mode | When to use | Behavior when KB has no relevant snippets | Editorial implication |
|---|---|---|---|
| KB_ONLY | Regulated, high-stakes or strict documentation answers | State that the documentation does not contain the requested information | Authors must keep the KB complete enough for expected questions. |
| ASK_WHEN_NO_KB | Ambiguous source sets or category-dependent answers | Ask one clarification question instead of guessing | Metadata taxonomy becomes part of UX design. |
| KB_PREFERRED | Marketing, product education and general support | Use KB when available; otherwise answer with clear separation from retrieved docs | Good balance for public websites that mix documentation and general explanation. |
Authentication and protection matrix
Admin routes, public chat, language tools, uploads and knowledge management have different trust levels. This matrix shows the default posture and the protection each surface needs.
| Surface | Default posture | Possible auth modes | Recommended protection | Why |
|---|---|---|---|---|
| Admin AI routes | Trusted/admin | IAM or Cognito | IAM by default, optional IP allow list, logs and alerts | These routes can expose broader capabilities and should not be public. |
| Frontend chatbot | Public or member-facing | NONE, IAM or Cognito | reCAPTCHA + WAF for public; Cognito scopes for member-only | Chat endpoints are cost-bearing and can receive arbitrary user input. |
| Frontend summarizer/language tools | Feature-gated public surface | NONE, IAM or Cognito | Only enable needed routes; throttle and validate payload size | Each route adds an abuse surface and a model-cost surface. |
| Image upload helper | Temporary asset ingress | Follows prompt surface | Strict content type, size, key prefix and lifecycle expiry | Presigned uploads are powerful and should be bounded tightly. |
| Knowledge Base management | Admin only | IAM or privileged Cognito | Never expose as anonymous frontend endpoint | KB selection and backend resources are configuration, not visitor UX. |
Model selection and cost posture
Different AI workloads create different cost and quality pressures. This table keeps editor tasks, public chat, DocSearch and multimodal requests from being forced into one model and protection profile.
| Workload | Cost pressure | Quality requirement | Architecture choice |
|---|---|---|---|
| Editor rewrite / translate / proofread | Usually moderate and admin-controlled | Consistent output and low friction | Try local AI first, use backend fallback when unavailable or when policy requires backend processing. |
| Frontend chatbot | Potentially high because visitors can trigger usage | Grounded, safe, understandable answers | Enable only needed routes, use lighter frontend model, reCAPTCHA/WAF, and bounded response settings. |
| DocSearch | Depends on search volume and retrieved context | Good citations and accurate source selection | RAG-first approach; optional rerank only where relevance improvement justifies extra calls. |
| Multimodal prompt | Higher because images add storage and processing | Useful for selected support or content workflows | Use presigned S3 uploads, object size limits and lifecycle expiration. |
How the deploy wizard changes the operating model
The wizard turns product-level choices into explicit backend configuration. This table shows how feature selection, authentication, template source and stack outputs affect both CloudFormation and WordPress.
| Wizard decision | CloudFormation effect | WordPress effect |
|---|---|---|
| Frontend features | Enables only the backend routes required for chatbot, DocSearch, summarization or language tools. | The plugin can expose only the surfaces the site actually wants to support. |
| Admin auth mode | Defaults toward Cognito for admin operations and can enforce scopes. | Admin/backend actions are not accidentally treated as public AI calls. |
| Template source | Uses an S3 template URL that CloudFormation can read. | The user sees an AWS-native stack review flow instead of a hidden SaaS provisioning step. |
| Outputs | Produces ApiBaseUrl and other stack outputs. | WordPress stores the endpoint contract; it does not own the backend runtime. |
Implementation path
Choose the execution path from the workload and governance requirement
Do not force every AI feature through one route simply because the plugin can expose several AI capabilities.
- Classify editor and visitor workloads — Separate editor-side rewriting, translation or metadata work from public chatbot, DocSearch and other visitor-triggered requests.
- Use local execution where it is actually supported — Keep compatible on-device tasks in the browser when that meets the capability and policy requirement; do not claim local execution for browsers or tasks that do not support it.
- Configure the backend trust zones — Keep privileged admin routes distinct from public frontend routes and add the appropriate authentication, WAF, throttling or abuse controls for each exposed surface.
- Govern retrieval and source use — Define which WordPress content enters the knowledge source, how it is split or excluded, and how source or citation data is returned so grounded answers can be reviewed.
When this architecture adds useful control
Good fit
AI workloads with different privacy and runtime needs
- Some editor tasks can stay on-device while other features need a server-side model or retrieval backend.
- You want the configured backend and its AWS resources in an account you control rather than requiring one shared vendor AI proxy.
- Visitor-facing DocSearch or chatbot features need grounded answers and must keep working on a static frontend.
Keep it simpler
A simpler AI path may be enough when
- The site only needs occasional editor-side tasks already covered by supported local browser AI.
- A conventional SaaS AI integration meets the organization's data, governance and operational requirements.
- There is no need for public AI, RAG, citations, backend observability or customer-controlled infrastructure.
Problem guides
Buyer problems this architecture explains
How do I use AI in WordPress without sending every draft through an AI SaaS?
Start with Use AI in WordPress Without Sending Every Draft Through an AI SaaS. It distinguishes supported local processing from the optional configured backend path and avoids claiming that every AI task stays local.
How do I give visitors grounded answers from WordPress content?
See Give Visitors Answers from Your WordPress Content — With Sources. The solution covers DocSearch and chatbot use; this architecture explains the knowledge-source, retrieval and backend boundaries behind grounded answers and sources.
Where does AI image metadata generation fit?
See Fix Missing WordPress Image Alt Text and Metadata at Scale. Media metadata generation is an editor workflow and can use the supported AI-Kit execution modes; human review remains important for accessibility-sensitive alt text.
Can frontend AI still work after static publishing?
Yes when the browser can reach the configured backend directly. See Make WordPress Static Without Losing Dynamic Features for the broader rule that static page delivery and dynamic browser services can remain separate.
Start from the AI data path
Choose where the AI workload should run before choosing the model
Use the Private AI guide for the data-path decision, then use the grounded-answer guide when the site also needs retrieval over WordPress content.