# aws-solutions/aws-control-tower-customizations architecture

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

- Interactive diagram: https://gitdiagram.com/aws-solutions/aws-control-tower-customizations
- Repository: https://github.com/aws-solutions/aws-control-tower-customizations

## Overview

Based on our analysis of the file tree and the README, this solution is an AWS backend customization tool that augments AWS Control Tower. Its purpose is to allow customers to add custom CloudFormation templates, service control policies (SCPs), and resource control policies (RCPs) to their AWS Control Tower landing zone. The repository contains deployment scripts and CloudFormation templates for distributing the solution and Python source code that implements the core logic, AWS service integrations, and Lambda handlers.

##### Main Components
- Deployment Layer:
- CloudFormation Templates and Scripts: Represented by files under the “deployment” folder (e.g., custom-control-tower-initiation.template, build scripts, and policy templates). These components package and initiate the solution.
- Distribution and S3: The build-s3-dist.sh script produces a distributable that is uploaded to S3 buckets following specific naming patterns.

- Core Backend Services:
- Lambda Handlers: The “source/src/cfct/lambda_handlers” directory includes handlers such as “lifecycle_event_handler”, “config_deployer”, and “state_machine_router” that respond to AWS Control Tower lifecycle events.
- AWS Services Integration: The “source/src/cfct/aws/services” folder contains modules for interacting with various AWS APIs (e.g., CloudFormation, CodePipeline, EC2, KMS, Organizations, S3, SCP, SSM, etc.). These modules encapsulate service-specific logic.
- Utility and Helper Modules: Modules under “source/src/cfct/utils” (e.g., logger, parameter manipulation, retry decorator) support the core functions.
- Manifest & Validation: The “manifest” and “validation” folders in the source present the logic to parse, merge, and validate CloudFormation parameters and policies.
- Metrics Collection: The “metrics” component is designed to gather operational data, as described in the README.

- Build and Integration Automation:
- CodeBuild Scripts: Located in “source/codebuild_scripts”, these scripts assist with tasks such as merging templates, updating baseline parameters, and running unit tests.
- Unit Testing: There is an explicit shell script in “deployment” for running unit tests, ensuring code quality before deployment.

##### Relationships and Interactions
- How these events are picked up by the Lambda functions (lifecycle_event_handler, state_machine_router) deployed as part of the solution.
- Interactions from the Lambda functions to the various AWS service integration modules (for CloudFormation, CodePipeline, etc.) which, in turn, call AWS APIs and manage deployments.
- Demonstrate how the manifest and validation modules process and merge configuration parameters and templates to drive these deployments.
- CodeBuild stage that builds the distribution package and uploads the artifacts (CloudFormation templates and zipped source code) to the appropriate S3 buckets.
- Finally, include a metrics collection component that sends anonymized usage data to support operational insights.

##### Architectural Patterns
- Modular Design: Emphasize the separation among AWS service wrappers, Lambda handlers, utilities, and validation modules.
- Event-Driven Architecture: Illustrate how lifecycle events from AWS Control Tower initiate the flow, managed by serverless functions.
- Infrastructure as Code (IaC): Highlight the use of CloudFormation templates to deploy and manage the customized environment.

##### Relevant Technologies
- Python (version 3.6+): For the core backend.
- AWS Lambda: For serverless event handlers.
- AWS SDK (boto3): For interacting with AWS services.
- CloudFormation: For resource provisioning.
- CodeBuild and Shell Scripts: For building and packaging the solution.
- Amazon S3: For storing the distribution artifacts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% AWS Control Tower Event
    E["AWS Control Tower Event"]:::runtime

    %% Core Backend Services - Lambda Handlers
    subgraph "Core Backend Services - Lambda Handlers"
        L1["Lambda Lifecycle Handler"]:::runtime
        L2["Lambda Config Deployer"]:::runtime
        L3["Lambda State Machine Router"]:::runtime
    end

    %% Core Backend Services - AWS Service Integrations
    subgraph "Core Backend Services - AWS Service Integrations"
        S1["CloudFormation Integration"]:::runtime
        S2["CodePipeline Integration"]:::runtime
        S3["EC2 Integration"]:::runtime
        S4["KMS Integration"]:::runtime
        S5["Organizations Integration"]:::runtime
        S6["RCP Integration"]:::runtime
        S7["S3 Integration"]:::runtime
        S8["SCP Integration"]:::runtime
        S9["SSM Integration"]:::runtime
        S10["State Machine Integration"]:::runtime
        S11["STS Integration"]:::runtime
    end

    %% Utility & Helper Modules
    U1["Utilities & Helpers"]:::support

    %% Manifest & Validation
    subgraph "Manifest & Validation"
        M1["Manifest Processing"]:::support
        M2["Validation Logic"]:::support
    end

    %% Metrics Collection
    MET["Solution Metrics Collection"]:::support

    %% Deployment Layer
    subgraph "Deployment Layer"
        D1["CF Template: custom-control-tower-initiation.template"]:::deployment
        D2["Build Script: build-s3-dist.sh"]:::deployment
        D3["Unit Test Script: run-unit-tests.sh"]:::deployment
        D4["Custom Control Tower Config"]:::deployment
        D5["S3 Distribution Bucket"]:::deployment
    end

    %% Build & Integration Automation
    subgraph "Build & Integration Automation"
        B1["CodeBuild Scripts"]:::deployment
    end

    %% Connections
    E -->|"triggers"| L1
    E -->|"triggers"| L3

    L1 -->|"calls"| S1
    L2 -->|"deploysVia"| S2
    L3 -->|"routesTo"| S10

    L2 -->|"processes"| M1
    M1 -->|"validatedBy"| M2

    L1 -->|"uses"| U1

    S1 -->|"sendsMetrics"| MET

    B1 -->|"mergesTemplates"| D4
    D2 -->|"uploadsTo"| D5

    %% Click Events
    click D1 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/deployment/custom-control-tower-initiation.template"
    click D2 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/deployment/build-s3-dist.sh"
    click D3 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/deployment/run-unit-tests.sh"
    click D4 "https://github.com/aws-solutions/aws-control-tower-customizations/tree/main/deployment/custom_control_tower_configuration"
    click L1 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/source/src/cfct/lambda_handlers/lifecycle_event_handler.py"
    click L2 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/source/src/cfct/lambda_handlers/config_deployer.py"
    click L3 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/source/src/cfct/lambda_handlers/state_machine_router.py"
    click S1 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/source/src/cfct/aws/services/cloudformation.py"
    click S2 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/source/src/cfct/aws/services/code_pipeline.py"
    click S3 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/source/src/cfct/aws/services/ec2.py"
    click S4 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/source/src/cfct/aws/services/kms.py"
    click S5 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/source/src/cfct/aws/services/organizations.py"
    click S6 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/source/src/cfct/aws/services/rcp.py"
    click S7 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/source/src/cfct/aws/services/s3.py"
    click S8 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/source/src/cfct/aws/services/scp.py"
    click S9 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/source/src/cfct/aws/services/ssm.py"
    click S10 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/source/src/cfct/aws/services/state_machine.py"
    click S11 "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/source/src/cfct/aws/services/sts.py"
    click U1 "https://github.com/aws-solutions/aws-control-tower-customizations/tree/main/source/src/cfct/utils"
    click M1 "https://github.com/aws-solutions/aws-control-tower-customizations/tree/main/source/src/cfct/manifest"
    click M2 "https://github.com/aws-solutions/aws-control-tower-customizations/tree/main/source/src/cfct/validation"
    click MET "https://github.com/aws-solutions/aws-control-tower-customizations/blob/main/source/src/cfct/metrics/solution_metrics.py"
    click B1 "https://github.com/aws-solutions/aws-control-tower-customizations/tree/main/source/codebuild_scripts"

    %% Styles
    classDef deployment fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef runtime fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef support fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
