Architecture · Pillar
WordPress on AWS Reference Architecture
A deep technical map for using WordPress as the editorial layer while AWS owns identity, static delivery, protected runtime, AI and workflows.
Architecture thesis: WordPress should remain the CMS and admin experience, not the single runtime boundary for every feature. WP Suite turns WordPress into a composable application front end by moving identity, protected delivery, AI, APIs and workflows into customer-owned AWS services.
Why this architecture exists
Most WordPress architecture diagrams still start from the same assumption: WordPress owns the public runtime. PHP renders the page, MySQL backs the request, plugins execute inside the same process, and scaling means adding more capacity to the same stack.
WP Suite takes a different path. WordPress remains the editorial and administrative control plane, but runtime responsibilities are split into AWS services that are better suited for the job: static delivery at the edge, identity in Cognito, APIs in API Gateway and Lambda, AI in Bedrock-backed services, and workflows in event-driven infrastructure.
The point is not to replace WordPress with a headless rebuild. The point is to stop forcing every application concern through the WordPress runtime when the site has already become more than a publishing site.
System boundary
Editors / administrators
│
▼
WordPress + Gutenberg
content, layout, settings, admin UX
│
WP Suite integration layer
│
┌─────────────────────────┼─────────────────────────┐
│ │ │
▼ ▼ ▼
Static delivery Identity plane Runtime APIs
Static Publisher Gatey + Cognito API Gateway + Lambda
S3 + CloudFront User/Identity Pools business logic
│ │ │
└──────────────┬──────────┴──────────────┬──────────┘
▼ ▼
Browser runtime AI / workflow plane
Gutenberg-rendered pages Bedrock, S3, DynamoDB,
client-side components EventBridge, SES, WAF
The boundary is deliberately boring: WordPress owns authoring, URL structure, Gutenberg markup, editorial workflows and module configuration. AWS owns execution paths that need independent scaling, stronger isolation, identity-aware access, event processing or model access.
Static Publisher is part of the delivery story, but it is not a CloudFormation stack by itself. It exports and publishes the rendered site into an AWS delivery target; the stack-backed capabilities live around identity, protected delivery, AI backend and workflow runtime.
Capability map
Content plane
WordPress and Gutenberg
The familiar editing layer remains the source of truth for pages, posts, blocks, CPT content, layout, metadata and product configuration.
Delivery plane
Static Publisher, S3 and CloudFront
Rendered pages and assets can be served from S3 and CloudFront so public traffic no longer depends on live PHP/MySQL capacity.
Identity plane
Gatey and Amazon Cognito
Authentication, sign-up, MFA, SSO, groups, JWTs and optional IAM credentials are delegated to Cognito and consumed directly in the browser.
Protected static plane
Static Site Guardian
Selected static paths can be protected at CloudFront using signed cookies, a signer service and Cognito-aware login flows.
Application runtime
API Gateway and Lambda
Runtime behavior such as account actions, protected data, workflow steps and integration logic is exposed as focused APIs rather than WordPress AJAX endpoints.
AI runtime
AI-Kit, Bedrock and S3 Vectors
On-device AI can handle local tasks, while backend fallback and RAG workflows run in a customer-owned AWS backend when needed.
Workflow plane
Flow and event-driven services
Forms and multi-step submissions can become triggers for email, webhook, EventBridge, AI-agent and backend processing flows.
Provisioning plane
Deployment Wizard and CloudFormation
Repeatable AWS capabilities are deployed through guided templates, so agencies and teams can standardize implementation without hand-building every stack.
Canonical request flows
Flow 1
Public static page request
A visitor requests a public page. CloudFront serves the exported HTML and assets from S3. WordPress is not in the request path, so spikes hit the CDN rather than PHP workers and database connections.
Flow 2
Signed-in user state
Gatey renders the Cognito login UI in the page. The browser authenticates against Cognito, receives tokens, and exposes identity state to WP Suite blocks without storing secrets or tokens on the WordPress server.
Flow 3
Protected API call
A frontend component calls API Gateway with JWT or IAM-based authorization. Lambda executes the business logic and returns only the data the authenticated user is allowed to see.
Flow 4
Protected static path
A visitor reaches a protected route. CloudFront checks signed cookies. If they are missing or expired, the user is redirected to sign in; once validated, the signer issues access for the protected path set.
Flow 5
AI/RAG request
AI-Kit tries local browser AI where appropriate. When a backend is required, the browser calls the configured API endpoint, which routes through Lambda to Bedrock, S3 documents, knowledge-base metadata and guardrails.
Flow 6
Form-to-workflow request
A Flow form captures the frontend interaction, then hands off durable work to backend actions, email, webhook, EventBridge or AI steps instead of depending on a single synchronous PHP request.
CloudFormation-backed architecture families
The Deployment Wizard turns a small number of product decisions into CloudFormation parameters, opens the AWS Create stack review flow, and then uses stack outputs such as API base URLs, role ARNs, user pool IDs or distribution settings as the contract back into WordPress. Each template family should map to a real architectural responsibility.
| Template family | Primary responsibility | Typical AWS resources | Article angle |
|---|---|---|---|
| Cognito day‑2 identity | Turn Cognito into a reusable WordPress identity backbone | User Pool, App Client, Identity Pool, IAM roles, Lambda triggers, S3 email templates, optional Route53 | Identity is more than login; it is token design, group mapping, email delivery and API authorization. |
| Static Site Guardian | Protect selected static paths without reintroducing PHP runtime | S3, CloudFront, Key Groups/Public Keys, signer Lambda or edge logic, API Gateway, KMS/SSM, optional Route53 | Static export solves delivery, but private content requires edge authorization and cookie discipline. |
| AI-Kit backend | Provide backend fallback, RAG and chatbot APIs in the customer account | API Gateway, Lambda, Bedrock, S3, S3 Vectors/Knowledge Base, DynamoDB, EventBridge, WAF, SSM/KMS | Private AI is an infrastructure pattern, not just an LLM feature. |
| Flow backend | Execute form-led workflows outside the WordPress request lifecycle | API Gateway, Lambda, DynamoDB tables for forms/submissions/events/templates/workflows/webhooks, S3 payload/template buckets, EventBridge, SES, WAF and reCAPTCHA | Forms become application frontends when validation, drafts, uploads, emails, webhooks and workflow events are owned by a dedicated backend. |
| Static Publisher target | Publish rendered WordPress output into an AWS delivery target | Uses S3/CloudFront deployment targets but does not need its own dedicated stack | Delivery pipeline and runtime architecture are related but not the same thing. |
Security and trust boundaries
The most important design decision is that WordPress should not become the holder of every secret, token and runtime decision. In this model, WordPress stores configuration and renders blocks; the browser, Cognito, CloudFront and API Gateway enforce the security boundaries.
No WordPress client secrets
Public-client Cognito design
Gatey is designed around browser-side Cognito flows. The WordPress server does not need to proxy passwords, persist user tokens or hold a Cognito client secret.
Edge authorization
Protected paths at CloudFront
Static content can still be private when CloudFront enforces signed cookies before S3 objects are served.
API authorization
JWT or IAM at API Gateway
Protected actions should be authorized at the API layer, not hidden with frontend CSS or WordPress-only visibility rules.
Separate surfaces
Admin, frontend and public routes
The admin/editor API surface, frontend visitor API surface and public static surface should be throttled, authenticated and logged independently.
Customer-owned backend
Infrastructure in the client AWS account
The architecture is strongest when sensitive runtime, identity and AI paths live in the customer account instead of a shared SaaS black box.
Least privilege by stack
Small IAM blast radius
Each template should provision only the permissions required by that capability and expose outputs for composition with other stacks.
Performance, cost and scaling model
Traditional dynamic WordPress stacks are often designed for peak load: PHP capacity, database capacity, cache layers and sometimes database clusters sized for rare events. That makes sense for some workloads, but it is expensive when most pages are cacheable and only selected interactions need runtime behavior.
The WP Suite model separates the always-on surface from the on-demand surface. Public HTML and assets are delivered at the edge. Runtime features scale independently and only execute when a visitor signs in, submits a form, asks an AI question, or calls a protected API.
| Dimension | Traditional dynamic WordPress | WP Suite AWS split | Why it matters |
|---|---|---|---|
| Public page delivery | PHP and database are still part of the origin story even with caching | S3 and CloudFront serve exported HTML and assets | Traffic spikes do not automatically imply PHP/database scaling. |
| Identity | Plugin logic often runs inside WordPress and stores session state there | Cognito handles authentication, MFA, SSO and tokens | Authentication can survive static export and remains independent of WordPress hosting. |
| Dynamic behavior | AJAX/admin-ajax or custom PHP endpoints | API Gateway and Lambda per runtime capability | Each feature can scale, fail and be secured independently. |
| AI | External API calls from PHP or third-party SaaS plugin | On-device first, backend fallback in the customer AWS account | Keeps content, prompts, documents and policies closer to the owner. |
| Operational trade-off | Simpler mental model, more runtime coupling | More architecture, less coupling | The split pays off when security, scale, privacy or repeatability matters. |
Operational model
The architecture treats each stack as a bounded subsystem with outputs, logs, permissions and rollback expectations.
Environment strategy
Dev, staging and production stacks
Use separate stacks and domains where possible. Static Publisher can publish the same crawl result to multiple deployment targets when only the domain and bucket differ.
Observability
Logs at the right boundary
CloudFront, API Gateway, Lambda, Cognito triggers, WAF and Bedrock calls should each have a clear log owner and debugging path.
Rollback
Rollback content and runtime separately
A content rollback should not require redeploying identity. A Lambda fix should not require re-exporting the whole site.
Drift control
Templates over console archaeology
CloudFormation-based deployment makes the intended architecture visible and repeatable instead of relying on manually recreated console steps.
Failure isolation
Static shell first
If an AI endpoint is temporarily unavailable, public content should still load. If WordPress admin is down, the static frontend can remain available.
Security review
Review trust boundaries, not just plugins
The meaningful review is where tokens, cookies, keys, roles and protected routes are enforced.
Implementation path
- Map which parts of the site are content-only, authenticated, protected-static, AI-powered, form-driven or API-driven.
- Choose the first AWS capability: identity, secure static protection, AI backend or workflow runtime.
- Deploy the matching template through the Deployment Wizard or CloudFormation path and capture stack outputs.
- Wire the outputs back into the relevant WP Suite plugin configuration.
- Add a runbook: parameters, outputs, DNS, certificates, logs, rollback, and who owns the AWS account.
- Compose the next capability only when its boundary is clear; avoid turning the first project into an all-at-once platform migration.
When this is a good fit
- A WordPress site needs authentication, protected content, AI features, forms or APIs but the public pages should remain fast and low-maintenance.
- An agency wants repeatable client-owned AWS architecture instead of one-off plugin stacks.
- A CTO wants WordPress for editorial productivity but does not want PHP/MySQL to own every runtime concern.
- A documentation, knowledge-base or portal site needs public content, private sections and AI search in the same experience.
- A team wants to reduce origin exposure without rebuilding the site as a fully headless application.
When not to use this
- A simple brochure site has no login, no protected routes, no AI, no workflow and no meaningful runtime requirements.
- The team cannot own or delegate ownership of an AWS account, DNS, certificates and operational monitoring.
- All dynamic behavior must remain inside existing WordPress plugins for organizational or contractual reasons.
- The project needs one-off implementation speed more than reusable architecture.
Related resources
Deep dive
Cognito Day‑2 Identity Architecture
deep dive into the Cognito CloudFormation identity backbone
Deep dive
Secure Static WordPress with Signed Cookies
deep dive into protected static delivery, CloudFront cookies and Cognito login
FAQ
Is this a headless WordPress architecture?
Not in the usual sense. WordPress remains the editing and content system, and the frontend can still be Gutenberg-rendered WordPress output. The runtime is split so selected capabilities move to AWS services.
Does Static Publisher require a CloudFormation stack?
No. Static Publisher is the publishing pipeline. It can publish to AWS delivery targets, but it does not need its own dedicated CloudFormation stack in the WP Suite model.
Which parts are actually template-backed?
The strongest stack-backed families are identity, protected static delivery, AI backend and workflow runtime. They can be adopted independently and composed through outputs and plugin configuration.
Why not just use managed WordPress hosting?
Managed hosting is still a good choice for many sites. The split architecture becomes valuable when identity, private routes, AI, workflows, client-owned infrastructure or strict runtime isolation matter.
Can this be introduced gradually?
Yes. Start with the capability that has a clear boundary, such as Cognito login or a protected static section, then add AI or workflow runtime only when the use case justifies it.
Use WordPress as CMS and AWS as runtime
Use this pillar as your starting point: understand the full system, then deep dive into identity, protected-static, AI and workflow.