How manuuell/p04-s3-cloudfront-cdn works
1. Purpose and shape of the system
This repository builds a static website platform on AWS with a global CDN front door. There is no application server or container runtime; the “app” is HTML/CSS content in web/ served through CloudFront, with infrastructure managed entirely as code.
2. Public request path
End users access the site through CloudFront. CloudFront is the only public entry point, and it is tied to an ACM certificate in us-east-1. The edge response path is augmented by Lambda@Edge, which injects security headers before the response reaches the browser.
3. Edge security boundary
The lambda/security-headers/ project is a small Node.js 20+ Lambda@Edge function. Its sole job is to enforce browser security policy headers such as HSTS, CSP, X-Frame-Options, and X-Content-Type-Options. Tests in lambda/security-headers/tests/ verify that these headers are present and that existing headers are safely overridden when needed.
4. Origin and storage layout
The S3 layer is split by responsibility:
- s3-assets: private/static origin for the website content
- s3-uploads: private object storage for uploads, with lifecycle rules moving data through IA/Glacier before deletion
- s3-logs: destination for CloudFront access logs with retention
CloudFront uses Origin Access Control (OAC) to reach the asset bucket, so the bucket is not publicly exposed.
5. Infrastructure-as-code decomposition
The terraform/ directory is the main control plane. It is broken into reusable modules for:
- s3
- cloudfront
- lambda_edge
- acm
- route53
This suggests the architecture is assembled from separate concerns rather than a single monolithic Terraform file. Environment-specific values live under terraform/envs/dev and terraform/envs/prod.
6. State and deployment bootstrap
scripts/bootstrap.sh creates the remote Terraform backend used for collaboration and locking. The repo is set up to store Terraform state remotely and use a lock table, which is important for multi-user infrastructure changes.
7. CI/CD behavior
GitHub Actions splits validation from publication:
- build.yml runs on pull requests and checks the Lambda tests plus Terraform formatting/validation.
- publish.yml runs on pushes to main, uses AWS OIDC federation (no long-lived AWS secrets in GitHub), syncs web/ to the asset bucket, and invalidates the CloudFront cache.
- deploy-infra.yml is the infrastructure deployment pipeline, separate from content publication.
8. Content publishing flow
The static site is deployed independently from the infrastructure. After Terraform creates the buckets and CDN, the site content is pushed with aws s3 sync web/ ..., and then CloudFront is invalidated so users see the updated HTML/CSS promptly.
9. Security posture
The architecture is designed around a strong edge/security posture: private S3 origins, OAC, Lambda@Edge headers, ACM-managed TLS, and GitHub OIDC for CI/CD authentication. The README also calls out an A+ securityheaders.com grade, which is a direct consequence of the edge header policy.
10. Observability and retention
CloudFront access logs are sent to a dedicated S3 bucket rather than mixed with content. That keeps request telemetry separate from assets and allows explicit retention management.
11. Environment boundaries
The repo supports at least dev and prod environments via Terraform variables and backend config files. That means the architecture can be diagrammed as one logical platform with environment-specific instances, rather than a single hard-coded deployment.
12. What to show in a diagram
A correct architecture diagram should center on:
Browser → CloudFront → S3 origin
with a sidecar Lambda@Edge security-header function, plus separate S3 buckets for assets, uploads, and logs. Around that, show Terraform/GitHub Actions as the delivery plane, and ACM/Route53/IAM/DynamoDB state backend as supporting control-plane services.
Main entry points: cloudfront/main.tf CloudFront · modules Terraform Modules · terraform/main.tf Terraform · publish.yml Publish CI
Components 17
Client & Edge
Public request path and response hardening at the CDN edge.
- Browser · End users requesting the site over HTTPS.
- CloudFront · Global entry point and cache layer for the static site.
terraform/modules/cloudfront/main.tf - Security Headers · Edge function that injects browser security headers.
lambda/security-headers/index.js
Storage
Private buckets for site assets, uploads, and logs.
- Assets Bucket · Private origin bucket for the static website content.
terraform/modules/s3/main.tf - Uploads Bucket · Private bucket for uploaded objects with lifecycle transitions.
terraform/modules/s3/main.tf - Logs Bucket · Dedicated bucket for CloudFront access logs with retention.
terraform/modules/s3/main.tf
Control Plane
Infrastructure provisioning, DNS, certificates, and state backend.
- ACM Cert · TLS certificate for the CloudFront distribution.
terraform/modules/acm/main.tf - Route 53 · DNS records and zone wiring for the site.
terraform/modules/route53/main.tf - Terraform · Main infrastructure control plane assembled from modules and envs.
terraform/main.tf - Terraform Modules · Reusable modules for S3, CloudFront, Lambda@Edge, ACM, and Route 53.
terraform/modules - Env Config · Environment-specific values for dev and prod deployments.
terraform/envs - Backend Bootstrap · Creates the remote Terraform backend and lock resources.
scripts/bootstrap.sh - State Backend · Remote Terraform state and locking storage.
terraform/backend.tf
Delivery
CI/CD paths for validation, infrastructure deployment, and content publication.
- Build CI · Pull-request validation for tests, formatting, and Terraform checks.
.github/workflows/build.yml - Publish CI · Main-branch content sync and cache invalidation using AWS OIDC.
.github/workflows/publish.yml - Deploy Infra · Infrastructure deployment pipeline separate from content publication.
.github/workflows/deploy-infra.yml
Site Content
Static website files served as the application payload.
- Web Assets · HTML and CSS content published independently of infrastructure.
web/index.html
Connections 23
- Browser → CloudFront: HTTPS requests · Users reach the site through the CDN front door.
- CloudFront → Security Headers: viewer response · CloudFront invokes the edge function to add security headers.
- CloudFront → Assets Bucket: origin fetch · CloudFront reads site assets from the private S3 origin via OAC.
- CloudFront → Logs Bucket: access logs · CloudFront writes access logs to a separate bucket.
- ACM Cert → CloudFront: TLS cert · CloudFront uses the ACM certificate for HTTPS.
- Route 53 → CloudFront: DNS alias · DNS points the site hostname at the CDN.
- Terraform → Terraform Modules: assembles · Root Terraform composes the reusable modules.
- Terraform → Env Config: parameterizes · Environment-specific values feed the root deployment.
- Backend Bootstrap → State Backend: creates · Bootstrap script provisions the remote backend and locking storage.
- Terraform Modules → Assets Bucket: defines · The S3 module creates the private asset origin.
- Terraform Modules → Uploads Bucket: defines · The S3 module creates the uploads bucket.
- Terraform Modules → Logs Bucket: defines · The S3 module creates the logs bucket.
- Terraform Modules → CloudFront: defines · The CloudFront module builds the distribution and origin wiring.
- Terraform Modules → Security Headers: defines · The Lambda@Edge module packages and publishes the header function.
- Terraform Modules → ACM Cert: defines · The ACM module provisions the certificate.
- Terraform Modules → Route 53: defines · The Route 53 module manages DNS records.
- Build CI → Security Headers: tests · Pull requests validate the edge function and its headers.
- Build CI → Terraform: validates · Pull requests run Terraform formatting and validation checks.
- Publish CI → Web Assets: syncs · Main-branch publishes push the static site content to the asset bucket.
- Publish CI → CloudFront: invalidates · Published content triggers cache invalidation.
- Publish CI → State Backend: uses · Deployment tooling relies on the remote Terraform state backend.
- Deploy Infra → Terraform: applies · Infrastructure deployment runs separately from content publication.
- Web Assets → CloudFront: served by · Static HTML and CSS are delivered through the CDN.