Architecture · Deep dive · Deployment model
AWS Deployment Wizard Architecture for WordPress Teams
A practical architecture for turning WP Suite product choices into repeatable CloudFormation deployments that live in the customer’s AWS account.
Architecture thesis: The Deployment Wizard is not a cosmetic setup screen. It is the bridge between WordPress product intent and AWS infrastructure ownership: collect a few meaningful decisions, open a CloudFormation Create stack review flow, deploy into the right account, then wire the resulting outputs back into WordPress.
Why deployment UX is part of the architecture
Most WordPress users do not want to design API Gateway, Lambda, Cognito, DynamoDB, WAF or Bedrock by hand. Most AWS architects do not want critical infrastructure to be created by a plugin that hides what it did. WP Suite needs both sides to be comfortable.
The Deployment Wizard solves that tension by staying deliberately thin. It collects product-level decisions, generates a prefilled CloudFormation flow, and lets AWS remain the place where the stack is reviewed, created and owned.
That is why this deserves its own architecture article: the provisioning model is part of the trust story. It explains how WP Suite can offer advanced AWS patterns without becoming an opaque hosted SaaS dependency.
System boundary
WP Suite / plugin settings
user chooses feature intent and a few important options
│
▼
Deployment Wizard
validates choices and builds CloudFormation parameters
│
▼
AWS Console → CloudFormation → Create stack (review)
customer reviews resources, parameters, IAM and outputs
│
▼
Customer-owned AWS stack
Cognito / AI backend / Flow backend / protected delivery stack
│
▼
CloudFormation Outputs
ApiBaseUrl, UserPoolId, role ARNs, distribution/domain details, bucket names
│
▼
WordPress plugin configuration
Gatey, AI-Kit, Flow or static protection components call the deployed backend
The important boundary is ownership. WP Suite can generate the path to deployment, but the runtime belongs to the AWS account where the stack is created.
The wizard contract
| Contract element | What the wizard owns | What AWS/CloudFormation owns |
|---|---|---|
| Decision collection | Ask only the few product decisions that change the stack shape: features, auth mode, optional protections, domains and integration values. | Validate parameters, create resources, track drift/updates and expose outputs. |
| Template source | Point CloudFormation to the correct S3-hosted template artifact version. | Read the template and create the declared resources in the target account/region. |
| Review step | Send the user to Create stack review with prefilled parameters. | Show the final resource/IAM/change set context before deployment. |
| Post-deploy wiring | Tell the user which outputs must be copied into WordPress settings. | Produce outputs such as API base URLs, Cognito IDs, role ARNs, bucket names or distribution settings. |
| Version control | Expose safe product decisions and keep developer-controlled release values out of normal user choices. | Use template versions to update deployed infrastructure predictably. |
Why not just deploy everything from WordPress?
A WordPress plugin can provide a friendly UI, but it should not silently become an infrastructure control plane for production AWS accounts. For CTOs and agencies, the AWS review step is not friction; it is the governance point where IAM, regions, billing, DNS and operational ownership are visible.
| Hidden plugin provisioning | Deployment Wizard + CloudFormation | Why WP Suite chooses the second |
|---|---|---|
| Easy first click, weak audit trail | User sees a CloudFormation stack in the AWS account | Infrastructure remains discoverable by the customer or agency. |
| Plugin needs broad AWS credentials | AWS Console handles stack creation permissions | WP Suite does not need to store long-lived customer cloud credentials. |
| Hard to reproduce across clients | Parameters and outputs form a repeatable contract | Agencies can write runbooks and compare environments. |
| Vendor account may own runtime | Customer account owns runtime resources | Data, logs, costs and security controls stay closer to the customer. |
Parameter design: ask less, not hide more
A good deployment wizard does not expose every CloudFormation parameter. It exposes the decisions that change the architecture and hides the ones that belong to the publishing/release process. For example, an AI backend wizard may ask which frontend features and protections are needed, while keeping DeploymentVersion developer-controlled.
Feature toggles
Enable only what the site needs
A site that only needs DocSearch should not deploy every possible public AI route by accident.
Auth modes
Separate frontend and admin surfaces
Admin APIs can default toward Cognito/scope enforcement while public routes can use reCAPTCHA, WAF or Cognito depending on the use case.
Domain choices
DNS is optional but explicit
Custom domains, certificates and Route53 records should be visible choices because they affect ownership and troubleshooting.
Security controls
Protections are architecture choices
WAF, IP allowlists, reCAPTCHA, KMS and GuardDuty-style options change how the backend can be safely exposed.
Artifact source
Templates must be CloudFormation-readable
CloudFormation requires an S3 template URL when using direct template links; the artifact bucket policy must allow the CloudFormation service principal to read it.
Integration handoff
Stack outputs connect the pieces
Values such as ApiBaseUrl should be copied from CloudFormation, not guessed from naming conventions.
Stack families in the WP Suite model
| Stack family | Wizard intent | Typical output contract | Why it matters |
|---|---|---|---|
| Cognito / Gatey identity | Create or attach a reusable Cognito identity backbone with app client, groups, triggers and optional custom domain. | User Pool ID, App Client ID, Identity Pool ID, role ARNs, domain values. | Login becomes a reusable runtime identity layer, not a page-level plugin setting. |
| AI-Kit backend | Enable backend fallback, chatbot, DocSearch/RAG and protected AI/admin routes in the customer account. | ApiBaseUrl, route/auth settings, KB/storage identifiers where applicable. | Private AI becomes a deployable backend capability rather than a SaaS-only plugin feature. |
| Flow backend | Deploy forms, submissions, drafts, uploads, templates, workflows, email and webhook runtime. | API base URL/custom domain, bucket/table/function outputs and route/auth choices. | Forms become durable workflows that can survive static delivery and external integrations. |
| Protected static delivery | Create the edge authorization pattern for private static paths. | CloudFront distribution/domain, signer/API endpoints, key/cookie settings. | Private static WordPress can be enforced at the CDN/object layer. |
| Static Publisher target | Publish rendered WordPress output to AWS delivery targets; no dedicated stack is required for the publisher itself. | Deployment target configuration rather than a separate runtime stack. | Publishing and runtime architecture stay related but not confused. |
The output contract is where WordPress reconnects
The deployment is only useful when WordPress can use it. That connection should be boring and explicit: deploy stack, copy outputs, paste into plugin settings, test the route. AI-Kit is the cleanest example: after deployment, the user copies ApiBaseUrl from CloudFormation outputs into AI-Kit Settings → API Settings.
| Output type | Example value | WordPress usage |
|---|---|---|
| API base URL | https://abc123.execute-api.region.amazonaws.com/prod or custom domain | AI-Kit/Flow blocks and admin screens know where to send backend requests. |
| Cognito identifiers | User Pool ID, App Client ID, Identity Pool ID | Gatey can render the Authenticator and acquire tokens for protected APIs. |
| Role ARNs / scopes | IAM role ARNs, group-derived scopes, admin scopes | APIs can enforce authorization instead of trusting hidden frontend state. |
| Distribution/domain values | CloudFront distribution domain, signed-cookie issuer endpoint | Static protection and publishing targets can be documented and verified. |
| Bucket/table names | Payload bucket, template bucket, data tables | Runbooks and diagnostics can point operators to the correct AWS resources. |
Agency and CTO governance model
Client ownership
Runtime lands in the right AWS account
Agencies can deploy into their own account or the client account depending on contract, compliance and support model.
Reviewable IAM
Stack review exposes permissions
Architects can inspect IAM and resource creation before launch instead of trusting a black-box plugin flow.
Repeatable support
Same template, different parameters
Runbooks can describe parameters, outputs, DNS, certificates, logs and rollback once, then reuse the pattern across clients.
Cost visibility
AWS billing follows the deployed account
The client or agency can see API, Lambda, model, storage, WAF and logging costs directly.
Change control
Updates are stack changes
A new runtime feature can be introduced by updating a stack/version rather than hand-editing console resources.
Exit path
Resources remain visible
Even if the WordPress plugin changes later, the deployed AWS resources are not hidden inside an unreachable vendor account.
Failure modes the article should make explicit
| Failure mode | What happens | How to document it |
|---|---|---|
| Wrong region | Stack deploys but related resources such as certificates or Cognito configuration are in another region. | List required regions per stack family and call out certificate/domain constraints. |
| Output not copied | WordPress plugin still points to an old or empty endpoint. | Make output-copying a deployment checklist item, not tribal knowledge. |
| Admin auth mismatch | Backend expects Cognito/IAM/scopes that the plugin is not configured to send. | Document auth mode, scopes and test calls immediately after deployment. |
| DNS/certificate half-configured | Custom domain exists but certificate, Route53 or API mapping is incomplete. | Separate “stack deployed” from “custom domain live” in the runbook. |
| Version drift | A site uses old stack resources with newer plugin UI expectations. | Track template versions and plugin versions together in the client record. |
Implementation path
- Start from the product feature: identity, AI backend, Flow backend, protected static content or delivery target.
- Define the smallest set of user-facing choices needed to shape that stack.
- Generate a CloudFormation Create stack review URL with prefilled parameters.
- After deployment, copy the relevant outputs into the matching WP Suite plugin settings.
- Test public, protected and admin routes separately.
- Record parameters, outputs, DNS, certificates, auth modes, logs and rollback guidance in the site runbook.
Related resources
Deep dive
WordPress on AWS Reference Architecture
The pillar article that places deployment, identity, static delivery, AI and workflow runtime into one model.
Deep dive
Private AI and RAG Backend
The AI-Kit backend article where the ApiBaseUrl output becomes the WordPress integration contract.
Deep dive
Event-Driven Forms and Workflow Backend
The Flow backend stack as a concrete example of guided deployment for forms and workflows.
Solution
WordPress for Agencies on AWS
The business/operational case for repeatable client-owned infrastructure.
FAQ
Is the Deployment Wizard a separate runtime stack?
No. It is a guided provisioning layer. The runtime stack is the thing it helps deploy, such as Cognito, AI-Kit backend, Flow backend or protected static delivery.
Why use CloudFormation instead of a custom API that creates AWS resources?
CloudFormation gives the customer a reviewable, account-owned stack with parameters, outputs and lifecycle management. It also avoids requiring WP Suite to store broad long-lived cloud credentials.
What should be documented after deployment?
At minimum: selected parameters, stack outputs, copied plugin settings, DNS/certificate choices, auth modes/scopes, log groups, cost-sensitive resources and rollback steps.
Deploy WP Suite runtime stacks without hiding the AWS architecture
Use guided CloudFormation deployment to create customer-owned AWS backends, then connect the stack outputs back to WordPress.