# moorthy-m/static-site-cicd-terraform architecture

> Architecture diagram of the GitHub repository moorthy-m/static-site-cicd-terraform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moorthy-m/static-site-cicd-terraform
- Repository: https://github.com/moorthy-m/static-site-cicd-terraform

## Overview

##### What this project is (type + purpose)
This is a **production-style static website deployment** project on AWS with **Infrastructure as Code + CI/CD** as the primary deliverable.

- **“Application”**: a Vite/React static site under `/site` that builds to static assets.
- **“Platform/Infra”**: Terraform modules split into:
- **Bootstrap layer** (`/bootstrap`): IAM + GitHub OIDC trust + least-privilege roles/policies so GitHub Actions can deploy without long-lived credentials.
- **Application layer** (`/infra`): private S3 bucket + CloudFront distribution with OAC + permissions for cache invalidation.

##### CI/CD (GitHub Actions)
`.github/workflows/`
- `terraform-bootstrap-ci.yml` / `terraform-bootstrap-cd.yml`
- `terraform-ci.yml` / `terraform-cd.yml`
- `terraform-site-ci.yml` / `terraform-site-cd.yml`

This strongly suggests **three pipelines/domains**:

##### Terraform layers
- `/bootstrap/*.tf`: providers, variables, IAM/OIDC
- `/infra/*.tf`: main resources, outputs, vars (`prod-infra.auto.tfvars` indicates an environment)

As **two Terraform stacks** with explicit dependency:
- Bootstrap must exist first to allow GitHub Actions auth.
- App infra depends on bootstrap-provisioned IAM (roles/policies) and then provisions runtime resources.

##### Static site
- `/site`: Vite/React app (pages/components/data)
- `site/src/utils/api.js` likely just local helper; no backend indicated.

Site as a **build artifact** (HTML/CSS/JS) deployed to S3, served via CloudFront.

- **S3 bucket is private** (no public ACLs/policies)
- **CloudFront uses OAC** (Origin Access Control) to fetch from S3
- **GitHub Actions uses OIDC** to assume roles (no long-lived keys)
- **Cache invalidation** happens on deployment (CD step)
- **No ACM/custom domain** (so HTTPS details can be omitted or noted as “default CloudFront domain”)

##### PR triggers CI (no deploy)
- GitHub PR → Actions CI (site build validation; terraform fmt/validate/plan depending on workflow intent)

##### Merge to main triggers CD
- Actions → (OIDC) → AWS STS AssumeRole → IAM Role credentials
- Terraform Apply:
- Bootstrap pipeline provisions IAM/OIDC trust.
- Infra pipeline provisions S3 + CloudFront + OAC + needed permissions.
- Site pipeline:
- Build Vite app → artifacts
- Upload artifacts → S3 (PutObject)
- Create invalidation → CloudFront (InvalidateObject/paths)

**OIDC** as a distinct step:
- GitHub Actions → “AWS STS AssumeRoleWithWebIdentity” → IAM Role

##### User request flow
- Browser → CloudFront Distribution (GET /)
- CloudFront → S3 Origin (via OAC signed request)
- S3 returns objects to CloudFront → Browser

**blocked path** (important security invariant):
- Browser → S3 bucket (direct) = denied (private bucket, no public access)

##### Architectural patterns/principles used
- **Layered Terraform stacks**: bootstrap vs application (separation of concerns)
- **Least privilege IAM**: separate deploy role, restricted permissions
- **Private origin**: S3 not public, only accessible through CloudFront OAC
- **Immutable-ish deployment**: build artifacts uploaded, CDN invalidated
- **Credentialless CI/CD**: OIDC federation rather than static keys

##### Relevant technologies
- Terraform (bootstrap/app layers)
- GitHub Actions (CI/CD)
- AWS: S3, CloudFront, IAM, STS, OIDC
- Vite/React build (static assets)

##### Don’t overthink: “separate into as many components as possible”
For maximum accuracy/detail, prefer *explicit nodes* even if they’re small:
- Separate “OIDC Provider” from “IAM Role” from “STS”
- Separate “Build artifact” from “S3 bucket”
- Separate “Terraform Plan/Apply” from “Site Upload/Invalidate”
- Separate bootstrap Terraform from app Terraform

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% SOURCE CONTROL / ACTORS
%% =========================
subgraph "Source Control"
  Dev["Developer (Local)"]:::actor
  Repo["GitHub Repo (PRs + main)"]:::scm
end

Dev -->|"push/PR"| Repo

%% =========================
%% CI/CD (GitHub Actions)
%% =========================
subgraph "CI/CD: GitHub Actions"
  WFDir["Workflows Directory"]:::scm

  subgraph "Bootstrap Workflows"
    BCI["Bootstrap Pipeline (CI)\nterraform-bootstrap-ci.yml"]:::cicd
    BCD["Bootstrap Pipeline (CD)\nterraform-bootstrap-cd.yml"]:::cicd
  end

  subgraph "Infra Workflows"
    ICI["Main Infra Pipeline (CI)\nterraform-ci.yml"]:::cicd
    ICD["Main Infra Pipeline (CD)\nterraform-cd.yml"]:::cicd
  end

  subgraph "Site Workflows"
    SCI["Site Pipeline (CI)\nterraform-site-ci.yml"]:::cicd
    SCD["Site Pipeline (CD)\nterraform-site-cd.yml"]:::cicd
  end
end

Repo -->|"PR_trigger"| BCI
Repo -->|"PR_trigger"| ICI
Repo -->|"PR_trigger"| SCI

Repo -->|"merge_to_main"| BCD
Repo -->|"merge_to_main"| ICD
Repo -->|"merge_to_main"| SCD

WFDir --- BCI
WFDir --- BCD
WFDir --- ICI
WFDir --- ICD
WFDir --- SCI
WFDir --- SCD

%% =========================
%% AUTH / IDENTITY (AWS Control Plane)
%% =========================
subgraph "AWS Control Plane (Identity + Provisioning)"
  OIDC["GitHub OIDC Provider (AWS IAM)"]:::security
  STS["AWS STS\nAssumeRoleWithWebIdentity"]:::security

  RoleBootstrap["IAM Role: Bootstrap Apply\n(least-privilege)"]:::security
  RoleInfra["IAM Role: Infra Apply\n(least-privilege)"]:::security
  RoleSite["IAM Role: Site Deploy\n(S3_put + CF_invalidate)"]:::security

  subgraph "Terraform Stacks (IaC)"
    subgraph "Bootstrap Terraform Stack (/bootstrap)"
      BTStack["Terraform: Bootstrap Stack"]:::terraform
      BTProviders["providers.tf"]:::tf
      BTMain["main.tf"]:::tf
      BTVars["variable.tf"]:::tf
    end

    subgraph "Application Terraform Stack (/infra)"
      ITStack["Terraform: Application/Infra Stack"]:::terraform
      ITProviders["providers.tf"]:::tf
      ITMain["main.tf"]:::tf
      ITVars["variables.tf"]:::tf
      ITOutputs["outputs.tf"]:::tf
      ITProd["prod-infra.auto.tfvars"]:::tfvars
    end
  end
end

%% OIDC federation path (prominent)
BCI -.->|"OIDC_token"| STS
BCD -.->|"OIDC_token"| STS
ICI -.->|"OIDC_token"| STS
ICD -.->|"OIDC_token"| STS
SCI -.->|"OIDC_token"| STS
SCD -.->|"OIDC_token"| STS

STS -.->|"assume_role"| RoleBootstrap
STS -.->|"assume_role"| RoleInfra
STS -.->|"assume_role"| RoleSite

%% Bootstrap provisions IAM OIDC + roles/policies
RoleBootstrap -.->|"terraform_plan/apply"| BTStack
BTStack -.->|"creates"| OIDC
BTStack -.->|"creates"| RoleBootstrap
BTStack -.->|"creates"| RoleInfra
BTStack -.->|"creates"| RoleSite

BTStack --- BTProviders
BTStack --- BTMain
BTStack --- BTVars

%% Infra stack depends on bootstrap roles existing
RoleInfra -.->|"terraform_plan/apply"| ITStack
BTStack -.->|"dependency"| ITStack

ITStack --- ITProviders
ITStack --- ITMain
ITStack --- ITVars
ITStack --- ITOutputs
ITStack --- ITProd

%% =========================
%% SITE (BUILD) + DEPLOY ARTIFACTS
%% =========================
subgraph "Static Site (Build)"
  SiteRoot["Site (Vite/React)"]:::frontend

  ViteCfg["vite.config.js"]:::frontend
  Pkg["package.json (build scripts)"]:::frontend
  IndexHtml["index.html"]:::frontend
  MainJsx["src/main.jsx"]:::frontend
  AppJsx["src/App.jsx"]:::frontend
  Pages["src/pages/"]:::frontend
  Components["src/components/"]:::frontend
  Data["src/data/"]:::frontend
  ApiUtil["src/utils/api.js\n(local helper; no backend)"]:::frontend

  Artifact["Build Artifacts\n(HTML/CSS/JS)"]:::artifact
end

SiteRoot --- ViteCfg
SiteRoot --- Pkg
SiteRoot --- IndexHtml
SiteRoot --- MainJsx
SiteRoot --- AppJsx
SiteRoot --- Pages
SiteRoot --- Components
SiteRoot --- Data
SiteRoot --- ApiUtil

SCI -->|"build_check"| Artifact
SCD -->|"build"| Artifact

%% =========================
%% AWS DATA PLANE (RUNTIME)
%% =========================
subgraph "AWS Data Plane (Static Hosting)"
  S3["S3 Private Bucket\n(Block Public Access ON)"]:::storage
  CF["CloudFront Distribution\n(Default domain)"]:::cdn
  OACNode["CloudFront OAC\n(Origin Access Control)"]:::security
  Edge["CloudFront Edge Cache\n(conceptual)"]:::cdn
end

%% Infra provisions runtime resources
ITStack -.->|"provisions"| S3
ITStack -.->|"provisions"| CF
ITStack -.->|"configures"| OACNode

OACNode -->|"signed_origin_requests"| S3
CF -->|"uses_OAC"| OACNode
CF -->|"cached_at_edge"| Edge

%% Site deployment actions
RoleSite -.->|"S3_PutObject"| S3
Artifact -.->|"upload_static_assets"| S3

RoleSite -.->|"CloudFront_CreateInvalidation"| CF
SCD -.->|"deploy_job"| RoleSite

%% =========================
%% USERS / RUNTIME TRAFFIC
%% =========================
subgraph "Users"
  Browser["End-user Browser"]:::actor
end

Browser -->|"HTTPS_GET_static_site"| CF
CF -->|"GET_origin_objects"| S3
S3 -->|"objects"| CF
CF -->|"cached_response"| Browser

%% Explicit deny path: direct S3 access blocked
Browser -.->|"DENY_direct_access"| S3

%% =========================
%% CLICK EVENTS (component_mapping)
%% =========================
click WFDir "https://github.com/moorthy-m/static-site-cicd-terraform/tree/main/.github/workflows/"
click BCI "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/.github/workflows/terraform-bootstrap-ci.yml"
click BCD "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/.github/workflows/terraform-bootstrap-cd.yml"
click ICI "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/.github/workflows/terraform-ci.yml"
click ICD "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/.github/workflows/terraform-cd.yml"
click SCI "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/.github/workflows/terraform-site-ci.yml"
click SCD "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/.github/workflows/terraform-site-cd.yml"

click BTStack "https://github.com/moorthy-m/static-site-cicd-terraform/tree/main/bootstrap/"
click BTMain "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/bootstrap/main.tf"
click BTProviders "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/bootstrap/providers.tf"
click BTVars "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/bootstrap/variable.tf"

click ITStack "https://github.com/moorthy-m/static-site-cicd-terraform/tree/main/infra/"
click ITMain "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/infra/main.tf"
click ITProviders "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/infra/providers.tf"
click ITVars "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/infra/variables.tf"
click ITOutputs "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/infra/outputs.tf"
click ITProd "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/infra/prod-infra.auto.tfvars"

click SiteRoot "https://github.com/moorthy-m/static-site-cicd-terraform/tree/main/site/"
click ViteCfg "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/site/vite.config.js"
click Pkg "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/site/package.json"
click IndexHtml "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/site/index.html"
click MainJsx "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/site/src/main.jsx"
click AppJsx "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/site/src/App.jsx"
click Pages "https://github.com/moorthy-m/static-site-cicd-terraform/tree/main/site/src/pages/"
click Components "https://github.com/moorthy-m/static-site-cicd-terraform/tree/main/site/src/components/"
click Data "https://github.com/moorthy-m/static-site-cicd-terraform/tree/main/site/src/data/"
click ApiUtil "https://github.com/moorthy-m/static-site-cicd-terraform/blob/main/site/src/utils/api.js"

%% =========================
%% STYLES (color required)
%% =========================
classDef actor fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20,stroke-width:1px
classDef scm fill:#E3F2FD,stroke:#0D47A1,color:#0D47A1,stroke-width:1px
classDef cicd fill:#BBDEFB,stroke:#1565C0,color:#0D47A1,stroke-width:1px
classDef terraform fill:#D1C4E9,stroke:#4527A0,color:#311B92,stroke-width:1px
classDef tf fill:#EDE7F6,stroke:#5E35B1,color:#311B92,stroke-width:1px
classDef tfvars fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C,stroke-width:1px
classDef security fill:#FFCDD2,stroke:#B71C1C,color:#7F0000,stroke-width:1.2px
classDef frontend fill:#FFF9C4,stroke:#F57F17,color:#6D4C41,stroke-width:1px
classDef artifact fill:#FFE0B2,stroke:#E65100,color:#6D4C41,stroke-width:1px
classDef storage fill:#C8E6C9,stroke:#2E7D32,color:#1B5E20,stroke-width:1.2px
classDef cdn fill:#C5CAE9,stroke:#283593,color:#1A237E,stroke-width:1.2px
```
