Architecture overview
The Web App Blueprint runs a working web application in each plat account of the AWS Baseline: a Python Flask API on Amazon EKS behind an internet-facing Application Load Balancer, a React single-page app served from S3 through CloudFront, DocumentDB for data and ElastiCache Redis for caching. ArgoCD inside each cluster deploys the API from a GitOps repository, so a commit reaches production through pull requests.
How it works
The browser loads the single-page app from CloudFront and calls the API on its own host name. The API reads and writes items in DocumentDB and caches reads in Redis. ArgoCD watches the GitOps repository and rolls the API forward when a stage's image tag changes.
Three repositories
| Repository | What it holds |
|---|---|
acme-aws-blueprint-webapp-infra | The infrastructure of every stage as OpenTofu modules and Terragrunt units: EKS, data stores, certificates, DNS, CloudFront |
acme-aws-blueprint-webapp-gitops | The Helm chart of the API and the image tag each stage runs |
acme-aws-blueprint-webapp-code | The Flask API, the React app, the tests and the build and release workflows |
The infrastructure repository creates the platform, including ArgoCD. The code repository builds images and opens pull requests against the GitOps repository. ArgoCD applies what the GitOps repository says.
One stage, one stack
Each stage (dev, staging and prod) lives in its own plat account and is built from the same template of 16 Terragrunt units, split in two groups:
- Shared infrastructure: the EKS cluster, Karpenter and Cluster Autoscaler, the public and internal certificates, the AWS Load Balancer Controller, two ExternalDNS releases (public and private zones), the External Secrets Operator, Fluent Bit and ArgoCD.
- The application: the application namespace and its identity, the DocumentDB security group, the DocumentDB cluster, the Redis replication group and the CloudFront front end.
Only a handful of values change between stages: domains, node counts, the ceiling on the capacity Karpenter may add, ArgoCD high availability and sync mode, log retention and the size of the data stores. Dev runs single instances; staging and prod run the multi-AZ layout, and prod adds deletion protection on DocumentDB and requires a manual sync in ArgoCD.
Delivery chain
The image is built once, on merge, and never rebuilt. A release adds a version tag to the same image, and promotion to production is a manual workflow that opens a pull request a person merges. The pattern is described in immutable artifacts and environments and promotion.
What it builds on
The blueprint does not create networks or accounts. It reads the VPC and subnets of each plat account from the values the AWS Baseline publishes, pushes images to the registry in the artifacts account, writes DNS records in the Baseline's public and private zones, and runs under the Baseline's security services. Firewall Manager in the Baseline attaches the web application firewall policy to the API's load balancer. Application secrets reach the pods from SSM Parameter Store, which is where the Secrets Blueprint delivers them too.
For the full list of services, see the service inventory. For what a customer receives, see what you receive.