# manuuell/p04-s3-cloudfront-cdn architecture

> Architecture diagram of the GitHub repository manuuell/p04-s3-cloudfront-cdn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/manuuell/p04-s3-cloudfront-cdn
- Repository: https://github.com/manuuell/p04-s3-cloudfront-cdn

## Overview

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: [`terraform/modules/cloudfront/main.tf`](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/modules/cloudfront/main.tf) (CloudFront), [`terraform/modules`](https://github.com/manuuell/p04-s3-cloudfront-cdn/tree/main/terraform/modules) (Terraform Modules), [`terraform/main.tf`](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/main.tf) (Terraform), [`.github/workflows/publish.yml`](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/.github/workflows/publish.yml) (Publish CI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_client_edge["Client & Edge"]
  node_browser(("Browser<br/>client"))
  node_cloudfront["CloudFront<br/>cdn<br/>[main.tf]"]
  node_lambda_edge["Security Headers<br/>lambda@edge<br/>[index.js]"]
end

subgraph group_group_storage["Storage"]
  node_s3_assets[("Assets Bucket<br/>s3 private origin<br/>[main.tf]")]
  node_s3_uploads[("Uploads Bucket<br/>s3 object store<br/>[main.tf]")]
  node_s3_logs[("Logs Bucket<br/>s3 logs<br/>[main.tf]")]
end

subgraph group_group_control["Control Plane"]
  node_acm["ACM Cert<br/>tls cert<br/>[main.tf]"]
  node_route53["Route 53<br/>dns<br/>[main.tf]"]
  node_terraform_root["Terraform<br/>iac root<br/>[main.tf]"]
  node_tf_modules["Terraform Modules<br/>iac modules"]
  node_tf_envs["Env Config<br/>iac envs"]
  node_bootstrap["Backend Bootstrap<br/>script<br/>[bootstrap.sh]"]
  node_state_backend[("State Backend<br/>remote state<br/>[backend.tf]")]
end

subgraph group_group_delivery["Delivery"]
  node_build_workflow["Build CI<br/>github actions<br/>[build.yml]"]
  node_publish_workflow["Publish CI<br/>github actions<br/>[publish.yml]"]
  node_deploy_infra_workflow["Deploy Infra<br/>github actions<br/>[deploy-infra.yml]"]
end

subgraph group_group_app["Site Content"]
  node_web_content["Web Assets<br/>static site<br/>[index.html]"]
end

node_browser -->|"HTTPS requests"| node_cloudfront
node_cloudfront -->|"viewer response"| node_lambda_edge
node_cloudfront -->|"origin fetch"| node_s3_assets
node_cloudfront -->|"access logs"| node_s3_logs
node_acm -->|"TLS cert"| node_cloudfront
node_route53 -->|"DNS alias"| node_cloudfront
node_terraform_root -->|"assembles"| node_tf_modules
node_terraform_root -->|"parameterizes"| node_tf_envs
node_bootstrap -->|"creates"| node_state_backend
node_tf_modules -->|"defines"| node_s3_assets
node_tf_modules -->|"defines"| node_s3_uploads
node_tf_modules -->|"defines"| node_s3_logs
node_tf_modules -->|"defines"| node_cloudfront
node_tf_modules -->|"defines"| node_lambda_edge
node_tf_modules -->|"defines"| node_acm
node_tf_modules -->|"defines"| node_route53
node_build_workflow -->|"tests"| node_lambda_edge
node_build_workflow -->|"validates"| node_terraform_root
node_publish_workflow -->|"syncs"| node_web_content
node_publish_workflow -->|"invalidates"| node_cloudfront
node_publish_workflow -->|"uses"| node_state_backend
node_deploy_infra_workflow -->|"applies"| node_terraform_root
node_web_content -->|"served by"| node_cloudfront

click node_cloudfront "https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/modules/cloudfront/main.tf"
click node_lambda_edge "https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/lambda/security-headers/index.js"
click node_acm "https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/modules/acm/main.tf"
click node_route53 "https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/modules/route53/main.tf"
click node_terraform_root "https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/main.tf"
click node_tf_modules "https://github.com/manuuell/p04-s3-cloudfront-cdn/tree/main/terraform/modules"
click node_tf_envs "https://github.com/manuuell/p04-s3-cloudfront-cdn/tree/main/terraform/envs"
click node_bootstrap "https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/scripts/bootstrap.sh"
click node_state_backend "https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/backend.tf"
click node_s3_assets "https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/modules/s3/main.tf"
click node_s3_uploads "https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/modules/s3/main.tf"
click node_s3_logs "https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/modules/s3/main.tf"
click node_web_content "https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/web/index.html"
click node_build_workflow "https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/.github/workflows/build.yml"
click node_publish_workflow "https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/.github/workflows/publish.yml"
click node_deploy_infra_workflow "https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/.github/workflows/deploy-infra.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_cloudfront,node_lambda_edge toneBlue
class node_s3_assets,node_s3_uploads,node_s3_logs toneAmber
class node_acm,node_route53,node_terraform_root,node_tf_modules,node_tf_envs,node_bootstrap,node_state_backend toneMint
class node_build_workflow,node_publish_workflow,node_deploy_infra_workflow toneRose
class node_web_content toneIndigo
```

## Components

### Client & Edge

Public request path and response hardening at the CDN edge.

- **Browser**: client · End users requesting the site over HTTPS.
- [CloudFront](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/modules/cloudfront/main.tf): cdn · Global entry point and cache layer for the static site. · `terraform/modules/cloudfront/main.tf`
- [Security Headers](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/lambda/security-headers/index.js): lambda@edge · Edge function that injects browser security headers. · `lambda/security-headers/index.js`

### Storage

Private buckets for site assets, uploads, and logs.

- [Assets Bucket](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/modules/s3/main.tf): s3 private origin · Private origin bucket for the static website content. · `terraform/modules/s3/main.tf`
- [Uploads Bucket](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/modules/s3/main.tf): s3 object store · Private bucket for uploaded objects with lifecycle transitions. · `terraform/modules/s3/main.tf`
- [Logs Bucket](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/modules/s3/main.tf): s3 logs · Dedicated bucket for CloudFront access logs with retention. · `terraform/modules/s3/main.tf`

### Control Plane

Infrastructure provisioning, DNS, certificates, and state backend.

- [ACM Cert](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/modules/acm/main.tf): tls cert · TLS certificate for the CloudFront distribution. · `terraform/modules/acm/main.tf`
- [Route 53](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/modules/route53/main.tf): dns · DNS records and zone wiring for the site. · `terraform/modules/route53/main.tf`
- [Terraform](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/main.tf): iac root · Main infrastructure control plane assembled from modules and envs. · `terraform/main.tf`
- [Terraform Modules](https://github.com/manuuell/p04-s3-cloudfront-cdn/tree/main/terraform/modules): iac modules · Reusable modules for S3, CloudFront, Lambda@Edge, ACM, and Route 53. · `terraform/modules`
- [Env Config](https://github.com/manuuell/p04-s3-cloudfront-cdn/tree/main/terraform/envs): iac envs · Environment-specific values for dev and prod deployments. · `terraform/envs`
- [Backend Bootstrap](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/scripts/bootstrap.sh): script · Creates the remote Terraform backend and lock resources. · `scripts/bootstrap.sh`
- [State Backend](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/terraform/backend.tf): remote state · Remote Terraform state and locking storage. · `terraform/backend.tf`

### Delivery

CI/CD paths for validation, infrastructure deployment, and content publication.

- [Build CI](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/.github/workflows/build.yml): github actions · Pull-request validation for tests, formatting, and Terraform checks. · `.github/workflows/build.yml`
- [Publish CI](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/.github/workflows/publish.yml): github actions · Main-branch content sync and cache invalidation using AWS OIDC. · `.github/workflows/publish.yml`
- [Deploy Infra](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/.github/workflows/deploy-infra.yml): github actions · Infrastructure deployment pipeline separate from content publication. · `.github/workflows/deploy-infra.yml`

### Site Content

Static website files served as the application payload.

- [Web Assets](https://github.com/manuuell/p04-s3-cloudfront-cdn/blob/main/web/index.html): static site · HTML and CSS content published independently of infrastructure. · `web/index.html`

## Connections

- 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.
