# swoodford/aws architecture

> Architecture diagram of the GitHub repository swoodford/aws, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swoodford/aws
- Repository: https://github.com/swoodford/aws

## Overview

##### Project type and purpose
- This is an open-source command-line toolkit, composed of standalone Bash scripts that automate AWS operations via the AWS CLI and jq.
- Its purpose is to simplify, standardize, and batch common DevOps tasks across multiple AWS services (EC2, S3, CloudFront, CloudWatch, VPC, WAF, Route53, IAM, Elastic Beanstalk, etc.).

##### File structure
- Top-level scripts (.sh) are grouped by AWS service (e.g., cloudfront-*.sh, ec2-*.sh, s3-*.sh, vpc-*.sh, waf-*.sh, route53-*.sh, iam-*.sh, elastic-beanstalk-*.sh, cloudwatch-*.sh).
- “docs/” and “.github/” contain project governance, contribution, CI, and issue templates.
- Configuration for continuous integration is in .travis.yml.

##### README for additional insights
- The README enumerates each script, its function, and the AWS service it targets.
- It specifies prerequisites: a POSIX shell, AWS CLI (Python), and jq.
- It highlights cross-region and cross-account compatibility.

##### Main components
a. User Environment
- Developer’s machine (macOS/Linux) with Bash shell.
- Local installations: AWS CLI, jq, optional s3cmd, terraform if needed.
b. Project Repository & CI/CD
- GitHub repository (source code host).
- Travis CI (build & lint scripts, run equality_test.sh, enforce coding standards).
c. Script Modules (Logical grouping)
- CloudFront module
- CloudWatch module
- EC2 module
- S3 module
- VPC module
- WAF module
- IAM module
- Route53 module
- Elastic Beanstalk module
- “Other Tools” module (e.g., convert-iplist-cidr-json-array.sh, install-awscli.sh)
d. CLI Abstraction Layer
- AWS CLI (aws)
- jq (JSON parsing)
e. AWS Service Endpoints
- Individual AWS service APIs called by the AWS CLI: S3, EC2, CloudFront, CloudWatch, VPC, WAF, IAM, Route53, Elastic Beanstalk
f. External Dependencies
- Optional third-party tools (cli53 for Route53 exports, s3cmd for S3 backups)

##### Relationships and interactions
- User invokes a Bash script → script parses arguments, calls AWS CLI and/or jq → AWS CLI issues HTTPS requests to AWS service endpoints → AWS services process requests and return JSON responses → script uses jq to parse and output results.
- CI/CD pipeline (Travis CI) pulls code from GitHub → runs linting/tests (e.g., equality_test.sh) → validates scripts.

##### Architectural patterns and principles
- Layered architecture:
- Presentation layer = Bash scripts (UI)
- Logic layer = calls to AWS CLI + jq processing
- Service layer = AWS APIs
- Modularity: each script handles a single concern or AWS service function.
- Idempotence and repeatability: scripts are safe to run multiple times, designed for automation.
- Extensibility: new scripts or service modules can be added without affecting existing ones.

##### Details to capture
- Scripts into logical service-based modules.
- Prerequisites on the developer machine (Python, AWS CLI, jq).
- GitHub repo and CI pipeline: code pushed → Travis CI tests → status reported on GitHub.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Environment
    subgraph "Developer Environment"
        direction TB
        DEV["Developer Machine\n(POSIX Shell)"]:::userEnv
        AWSCLI["AWS CLI"]:::cli
        JQ["jq"]:::cli
        DEV --> AWSCLI
        DEV --> JQ
    end

    %% Repository & CI/CD
    subgraph "Repository & CI/CD"
        direction TB
        GITHUB["GitHub Repo"]:::ci
        TRAVIS["Travis CI"]:::ci
        EQUAL["equality_test.sh"]:::ci
        GITHUB --> TRAVIS
        TRAVIS --> EQUAL
    end

    %% CLI Abstraction
    subgraph "CLI Abstraction Layer"
        direction TB
        AWSCLI
        JQ
    end

    %% Script Modules
    subgraph "Script Modules" 
        direction TB
        subgraph "CloudFront Module" 
            CF1["cloudfront-inprogress-status.sh"]:::modules
            CF2["cloudfront-invalidation-status.sh"]:::modules
        end
        subgraph "CloudWatch Module"
            CW1["cloudwatch-create-alarms-statuscheckfailed.sh"]:::modules
            CW2["cloudwatch-create-alarms-unhealthyhost.sh"]:::modules
            CW3["cloudwatch-create-alarms.sh"]:::modules
        end
        subgraph "EC2 Module"
            EC1["ec2-ami-encrypted-ebs-boot-volume.sh"]:::modules
            EC2_2["ec2-associate-elastic-ip.sh"]:::modules
            EC3["ec2-classic-import-network-acl.sh"]:::modules
        end
        subgraph "S3 Module"
            S31["s3-buckets-file-size-s3cmd.sh"]:::modules
            S32["s3-buckets-local-backup.sh"]:::modules
            S33["s3-buckets-security-audit.sh"]:::modules
        end
        subgraph "VPC Module"
            VPC1["vpc-eni-monitor.sh"]:::modules
        end
        subgraph "WAF Module"
            WAF1["waf-export-ip-sets.sh"]:::modules
        end
        subgraph "IAM Module"
            IAM1["iam-create-s3-users.sh"]:::modules
        end
        subgraph "Route53 Module"
            R53_1["route53-export-zones.sh"]:::modules
        end
        subgraph "Elastic Beanstalk Module"
            EB1["elastic-beanstalk-set-hostname-within-instance.sh"]:::modules
        end
        subgraph "Other Tools Module"
            OT1["convert-iplist-cidr-json-array.sh"]:::modules
        end
    end

    %% AWS Services
    subgraph "AWS Service Endpoints"
        direction TB
        S3["S3 API"]:::awsService
        EC2["EC2 API"]:::awsService
        CF["CloudFront API"]:::awsService
        CW["CloudWatch API"]:::awsService
        VPC["VPC API"]:::awsService
        WAF["WAF API"]:::awsService
        IAM["IAM API"]:::awsService
        R53["Route53 API"]:::awsService
        EB["Elastic Beanstalk API"]:::awsService
    end

    %% External Dependencies
    subgraph "Optional External Tools"
        direction TB
        CLI53["cli53"]:::external
        S3CMD["s3cmd"]:::external
        TERRAFORM["Terraform"]:::external
    end

    %% Interactions
    DEV -->|"invoke script"| CF1
    DEV -->|"invoke script"| CW1
    CF1 -->|"uses"| AWSCLI
    CW1 -->|"uses"| AWSCLI
    S31 -->|"uses"| AWSCLI
    S31 -->|"uses"| JQ
    AWSCLI -->|"calls"| CF
    AWSCLI -->|"calls"| CW
    AWSCLI -->|"calls"| EC2
    AWSCLI -->|"calls"| S3
    AWSCLI -->|"calls"| VPC
    AWSCLI -->|"calls"| WAF
    AWSCLI -->|"calls"| IAM
    AWSCLI -->|"calls"| R53
    AWSCLI -->|"calls"| EB

    %% CI/CD Flow
    DEV -->|"push code"| GITHUB
    GITHUB -->|"trigger"| TRAVIS
    TRAVIS -->|"run tests"| EQUAL
    TRAVIS -->|"lint scripts"| CF1

    %% Optional integrations
    S31 -.->|"backup"| S3CMD
    R53_1 -.->|"export"| CLI53
    OT1 -.->|"redact"| TERRAFORM

    %% Click Events
    click CF1 "https://github.com/swoodford/aws/blob/master/cloudfront-inprogress-status.sh"
    click CF2 "https://github.com/swoodford/aws/blob/master/cloudfront-invalidation-status.sh"
    click CW1 "https://github.com/swoodford/aws/blob/master/cloudwatch-create-alarms-statuscheckfailed.sh"
    click CW2 "https://github.com/swoodford/aws/blob/master/cloudwatch-create-alarms-unhealthyhost.sh"
    click CW3 "https://github.com/swoodford/aws/blob/master/cloudwatch-create-alarms.sh"
    click EC1 "https://github.com/swoodford/aws/blob/master/ec2-ami-encrypted-ebs-boot-volume.sh"
    click EC2_2 "https://github.com/swoodford/aws/blob/master/ec2-associate-elastic-ip.sh"
    click EC3 "https://github.com/swoodford/aws/blob/master/ec2-classic-import-network-acl.sh"
    click S31 "https://github.com/swoodford/aws/blob/master/s3-buckets-file-size-s3cmd.sh"
    click S32 "https://github.com/swoodford/aws/blob/master/s3-buckets-local-backup.sh"
    click S33 "https://github.com/swoodford/aws/blob/master/s3-buckets-security-audit.sh"
    click VPC1 "https://github.com/swoodford/aws/blob/master/vpc-eni-monitor.sh"
    click WAF1 "https://github.com/swoodford/aws/blob/master/waf-export-ip-sets.sh"
    click IAM1 "https://github.com/swoodford/aws/blob/master/iam-create-s3-users.sh"
    click R53_1 "https://github.com/swoodford/aws/blob/master/route53-export-zones.sh"
    click EB1 "https://github.com/swoodford/aws/blob/master/elastic-beanstalk-set-hostname-within-instance.sh"
    click OT1 "https://github.com/swoodford/aws/blob/master/convert-iplist-cidr-json-array.sh"
    click EQUAL "https://github.com/swoodford/aws/blob/master/.travis.yml"

    %% Styles
    classDef userEnv fill:#FFF2CC,stroke:#333,stroke-width:1px
    classDef cli fill:#D5F5E3,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef modules fill:#D6EAF8,stroke:#333,stroke-width:1px
    classDef awsService fill:#FAD7A0,stroke:#333,stroke-width:1px
    classDef external fill:#E5E8E8,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef ci fill:#F5CBA7,stroke:#333,stroke-width:1px
```
