# thunder-so/cdk-spa architecture

> Architecture diagram of the GitHub repository thunder-so/cdk-spa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thunder-so/cdk-spa
- Repository: https://github.com/thunder-so/cdk-spa

## Overview

##### Project Type and Purpose
- This is an open-source AWS CDK library and CLI tool (`@thunderso/cdk-spa`) for deploying client-side SPAs or SSG sites to AWS S3/CloudFront with optional CI/CD.
- It provides a CLI (`bin/app.ts`, `cli/*.mjs`) to scaffold and manage a CDK App, a set of CDK constructs in `lib/`, CloudFormation stacks in `stack/`, and optional GitHub Actions or AWS CodePipeline support.

##### File Structure → Architecture Mapping
- bin/app.ts: CLI entrypoint (Node/TypeScript)
- cli/*.mjs: actual commands (init, deploy, destroy) that bootstrap or orchestrate the CDK App.
- lib/*.ts: core construct definitions (hosting, pipeline, events, deploy logic).
- stack/SPAStack.ts & SPAProps.ts: user-consumable stack API, where you configure domains, redirects, headers, pipeline settings.
- templates/spa.ts: boilerplate CloudFormation template for initial scaffold.
- package.json & workflows: define scripts, dependencies (aws-cdk, tsx), and GitHub Actions config for publishing to NPM.

##### Main Components
a. Developer Environment & Source Code
- Developer machine (Node.js, AWS CLI, CDK CLI)
- Local Code Repository (bin/, cli/, lib/, stack/, templates/)
b. CLI Layer
- `cdk-spa-init` → generates `stack/index.ts` from `templates/spa.ts`
- `cdk-spa-deploy`/`destroy` → invokes `npx cdk deploy` or `destroy`
c. CDK App & CloudFormation
- CDK App (bin/app.ts + lib/ + stack/) → synth → CloudFormation templates
- CloudFormation Service → creates/updates AWS resources
d. AWS Infrastructure
- S3 Bucket (static site hosting)
- CloudFront Distribution (edge cache)
- ACM Certificate (us-east-1)
- Route53 Hosted Zone & DNS Records
- Lambda@Edge Functions (redirects, rewrites, headers)
- Optional CodeBuild / CodePipeline (build & deploy pipeline)
e. CI/CD (two flavors)
- GitHub Actions Workflow (.github/workflows/deploy.yml) → checkout → build → `cdk deploy`
- AWS CodePipeline with CodeBuild
- Source: GitHub (via Personal Access Token in Secrets Manager)
- Build: CodeBuild project (buildspec or buildProps)
- Deploy: CDK CloudFormation

##### Component Interactions & Data Flows
- Developer runs `npx cdk-spa-init` → scaffolds stack code
- Developer edits stack/index.ts → configures `SPAProps`
- Developer (or GitHub Actions) runs `npx cdk deploy` → CDK CLI → AWS CloudFormation → provisions AWS Services
- Application build artifacts (from `outputDir`) uploaded to S3 → CloudFront distribution picks them up
- Lambda@Edge functions attached to CloudFront for redirects/rewrites/headers
- Route53 DNS records point domain/subdomain to CloudFront
- In CI/CD mode: GitHub Actions or CodePipeline automatically repeat the above on code pushes

##### Architectural Patterns & Principles
- Infrastructure as Code (IaC) with AWS CDK and CloudFormation
- Modular CDK Constructs (separate hosting, pipeline, events logic in `lib/`)
- CLI-Driven Developer Experience (init/deploy/destroy commands)
- Optional Pipelines: declarative (GitHub Actions) or managed (CodePipeline/CodeBuild)
- Edge-Computing: Lambda@Edge for URL handling and HTTP header customizations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer / Local Layer
    subgraph "Developer / Local" 
        direction TB
        CLI_ENTRY["CLI Entry Point\nbin/app.ts"]:::code
        subgraph "CLI Commands" 
            direction TB
            INIT["cdk-spa-init"]:::code
            DEPLOYCMD["cdk-spa-deploy"]:::code
            DESTROYCMD["cdk-spa-destroy"]:::code
        end
        subgraph "CDK App" 
            direction TB
            CDKJSON["cdk.json"]:::code
            INDEXTS["index.ts"]:::code
            subgraph "Core Constructs" 
                direction TB
                HOSTING["hosting.ts"]:::code
                PIPELINE["pipeline.ts"]:::code
                EVENTS["events.ts"]:::code
                DEPLOYLOGIC["deploy.ts"]:::code
                INDEXLIB["index.ts"]:::code
            end
            subgraph "User Stack API" 
                direction TB
                STACK["SPAStack.ts"]:::code
                PROPS["SPAProps.ts"]:::code
            end
        end
        subgraph "Templates" 
            direction TB
            TEMPLATE["spa.ts"]:::code
        end
        CLI_ENTRY --> INIT
        CLI_ENTRY --> DEPLOYCMD
        CLI_ENTRY --> DESTROYCMD
        INIT --> TEMPLATE
        INIT --> STACK
        DEPLOYCMD --> CDKJSON
        DESTROYCMD --> CDKJSON
        CDKJSON --> INDEXTS
        INDEXTS --> HOSTING
        INDEXTS --> PIPELINE
        INDEXTS --> EVENTS
        INDEXTS --> DEPLOYLOGIC
        INDEXTS --> INDEXLIB
        STACK --> PROPS
    end

    %% CI/CD Layer
    subgraph "CI/CD Layer" 
        direction TB
        subgraph "GitHub Actions" 
            ACTIONS["publish.yml"]:::pipeline
        end
        subgraph "CodePipeline" 
            direction TB
            GITSOURCE["GitHub (Source)"]:::external
            CODEBUILD["CodeBuild Project"]:::pipeline
            CPPROJ["CodePipeline"]:::pipeline
        end
        ACTIONS -.->|triggers| DEPLOYCMD
        GITSOURCE --> CODEBUILD
        CODEBUILD --> CPPROJ
        CPPROJ --> DEPLOYCMD
    end

    %% AWS Control Plane
    subgraph "AWS Control Plane" 
        direction TB
        CFN["CloudFormation"]:::aws
    end
    DEPLOYCMD -->|"synth & deploy"| CFN
    CPPROJ -->|"deploy via CDK"| CFN
    ACTIONS -->|"deploy via CDK"| CFN

    %% AWS Data Plane (Resources)
    subgraph "CloudFormation Stack" 
        direction TB
        S3["S3 Bucket"]:::storage
        CF["CloudFront Distribution"]:::aws
        ACM["ACM Certificate"]:::aws
        DNS["Route53 DNS"]:::aws
        LAMBDA["Lambda@Edge\n(redirects/rewrite/headers)"]:::aws
        S3 --> CF
        CF --> LAMBDA
        CF --> DNS
        CF --> ACM
    end
    CFN --> S3
    CFN --> CF
    CFN --> ACM
    CFN --> DNS
    CFN --> LAMBDA

    %% Click events
    click CLI_ENTRY "https://github.com/thunder-so/cdk-spa/blob/main/bin/app.ts"
    click INIT "https://github.com/thunder-so/cdk-spa/blob/main/cli/cdk-spa-init.mjs"
    click DEPLOYCMD "https://github.com/thunder-so/cdk-spa/blob/main/cli/cdk-spa-deploy.mjs"
    click DESTROYCMD "https://github.com/thunder-so/cdk-spa/blob/main/cli/cdk-spa-destroy.mjs"
    click CDKJSON "https://github.com/thunder-so/cdk-spa/blob/main/cdk.json"
    click INDEXTS "https://github.com/thunder-so/cdk-spa/blob/main/index.ts"
    click HOSTING "https://github.com/thunder-so/cdk-spa/blob/main/lib/hosting.ts"
    click PIPELINE "https://github.com/thunder-so/cdk-spa/blob/main/lib/pipeline.ts"
    click EVENTS "https://github.com/thunder-so/cdk-spa/blob/main/lib/events.ts"
    click DEPLOYLOGIC "https://github.com/thunder-so/cdk-spa/blob/main/lib/deploy.ts"
    click INDEXLIB "https://github.com/thunder-so/cdk-spa/blob/main/lib/index.ts"
    click STACK "https://github.com/thunder-so/cdk-spa/blob/main/stack/SPAStack.ts"
    click PROPS "https://github.com/thunder-so/cdk-spa/blob/main/stack/SPAProps.ts"
    click TEMPLATE "https://github.com/thunder-so/cdk-spa/blob/main/templates/spa.ts"
    click ACTIONS "https://github.com/thunder-so/cdk-spa/blob/main/.github/workflows/publish.yml"

    %% Styles
    classDef code fill:#e0f7fa,stroke:#006064,color:#006064
    classDef aws fill:#fff3e0,stroke:#ef6c00,color:#ef6c00
    classDef storage fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
    classDef pipeline fill:#f3e5f5,stroke:#6a1b9a,color:#6a1b9a
    classDef external fill:#eceff1,stroke:#607d8b,color:#607d8b
```
