# aws-samples/aws-service-control-policies-deployment architecture

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

- Interactive diagram: https://gitdiagram.com/aws-samples/aws-service-control-policies-deployment
- Repository: https://github.com/aws-samples/aws-service-control-policies-deployment

## Overview

##### Main components
- AWS Accounts: Three accounts are involved:
- Org management account: Contains the SetupOrgManagementStack.
- Builder account: Hosts the CodeCommit repository for the SCPs and the SetupBuilderAccountStack.
- Test account: Contains the CodeCommit repository for the acceptance tests and the SetupMemberAccountStack.
- CDK Application: Contains stacks under the “lib/” directory:
- SetupOrgManagementStack
- SetupBuilderAccountStack
- SetupMemberAccountStack
- Custom resources and utility scripts (e.g., custom_resources folder with Python script for creating/attaching SCPs)
- Code Repository Structure for Policies:
- Repos-for-code-commit/policies: Holds metadata and JSON files that define the SCPs for different Organizational Units (e.g., production, sandbox, tools).
- Acceptance Tests:
- Repos-for-code-commit/tests: Contains behave acceptance tests (features, steps, buildspec, etc.) that verify if the SCPs are correctly applied using the policy simulator.
- CI/CD Components (Implicit in Deployment Process):
- AWS CodePipeline/CodeBuild triggered by commits to the policies and tests repositories.
- AWS CLI commands and environment configuration for deployment.
- Deployment and Execution Flow:
- The builder account’s repository stores SCPs.
- The metadata file in the SCP repository details which OUs get what policies.
- A code pipeline uses the metadata to deliver changes.
- Acceptance tests in the test account verify the policy simulator responses.

- Top-level directories like “bin”, “lib”, “repos-for-code-commit”, and “test” indicate separation of concerns:
- “bin” and “lib” host CDK deployment scripts and CloudFormation stack definitions.
- “repos-for-code-commit” is split into “policies” and “tests”, each with its own README and infrastructure.
- The presence of infrastructure-as-code files (cdk.json, tsconfig.json) and a mix of languages (TypeScript and Python) indicate that the solution integrates multiple AWS services and languages.
- The tests directory under “repos-for-code-commit/tests” shows an organized approach for acceptance testing using behave.

b. Under each account, illustrate the relevant components:
- Org Management Account: Show the SetupOrgManagementStack which provides a role (orgManagementAssumableRoleArn) for subsequent operations.
c. Interactions between these components:
d. Architectural patterns or design principles:
- Separation of concerns: Different accounts and repositories for policies vs. tests.
- Declarative infrastructure deployment using CDK (CloudFormation stacks).
- Use of metadata (in JSON) to drive the deployment of SCPs declaratively.
- AWS CDK, AWS CloudFormation, AWS CodeCommit, AWS CodeBuild.
- Languages/Frameworks: TypeScript for CDK stacks, Python for custom resources and test steps, and Behave for acceptance tests.
- The integration with AWS CLI and external tools like jq and git-remote-codecommit, if needed.

##### Instructing the principal software engineer
- Use clear labels for each main AWS account and its primary components.
- Labels with the specific stack names (e.g., SetupOrgManagementStack, SetupBuilderAccountStack, SetupMemberAccountStack) and mark the corresponding AWS accounts.
- Interactions between the CodeCommit repositories and the deployment triggers (such as how code pushes trigger the pipelines).
- Use of acceptance tests via the policy simulator that confirms if SCPs are working as expected.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Dev["Developer/Engineer"]:::developerStyle

    %% Org Management Account
    subgraph "Org Management Account"
        ORGStack["SetupOrgManagementStack"]:::orgStack
    end

    %% Builder Account
    subgraph "Builder Account"
        BuilderRepo["CodeCommit Repository (SCP Definitions)"]:::builderRepo
        MetaFile["Metadata File for Policy Deployment"]:::metaFile
        CDKEntry["CDK Deployment Entry (aws-service-control-policies-deployment)"]:::cdkEntry
        BuilderStack["SetupBuilderAccountStack"]:::builderStack
        CustomRes["Custom Resources for creating/attaching SCPs"]:::customRes
    end

    %% Test Account
    subgraph "Test Account"
        TestRepo["CodeCommit Repository (Acceptance Tests)"]:::testRepoStyle
        TestStack["SetupMemberAccountStack"]:::testStackStyle
        PolicySim["Policy Simulator (Acceptance Tests Execution)"]:::policySimStyle
    end

    %% Interactions and Data Flows
    Dev -->|"pushes-code"| BuilderRepo
    Dev -->|"pushes-code"| TestRepo

    BuilderRepo -->|"contains"| MetaFile
    BuilderRepo -->|"triggers"| CDKEntry
    MetaFile -->|"drives"| CDKEntry
    CDKEntry -->|"deploys"| BuilderStack
    CDKEntry -->|"invokes"| CustomRes
    CustomRes -->|"applies-SCPs"| ORGStack
    CDKEntry -->|"triggers-tests"| PolicySim
    TestRepo -->|"provides-tests"| TestStack
    TestStack -->|"sets-up-env"| PolicySim

    %% Click Events
    click ORGStack "https://github.com/aws-samples/aws-service-control-policies-deployment/blob/main/lib/setup-org-management-stack.ts"
    click BuilderStack "https://github.com/aws-samples/aws-service-control-policies-deployment/blob/main/lib/setup-builder-account-stack.ts"
    click TestStack "https://github.com/aws-samples/aws-service-control-policies-deployment/blob/main/lib/setup-member-account-stack.ts"
    click CustomRes "https://github.com/aws-samples/aws-service-control-policies-deployment/blob/main/lib/custom_resources/create_and_attach_scp.py"
    click BuilderRepo "https://github.com/aws-samples/aws-service-control-policies-deployment/tree/main/repos-for-code-commit/policies"
    click MetaFile "https://github.com/aws-samples/aws-service-control-policies-deployment/blob/main/repos-for-code-commit/policies/scp/metadata.json"
    click TestRepo "https://github.com/aws-samples/aws-service-control-policies-deployment/tree/main/repos-for-code-commit/tests"
    click CDKEntry "https://github.com/aws-samples/aws-service-control-policies-deployment/blob/main/bin/aws-service-control-policies-deployment.ts"

    %% Styles
    classDef developerStyle fill:#FFEBCC,stroke:#E67E22,stroke-width:2px;
    classDef orgStack fill:#FDEDEC,stroke:#E74C3C,stroke-width:2px;
    classDef builderRepo fill:#E8F8F5,stroke:#3498DB,stroke-width:2px;
    classDef metaFile fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef cdkEntry fill:#EBF5FB,stroke:#2E86C1,stroke-width:2px;
    classDef builderStack fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef customRes fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef testRepoStyle fill:#FEF9E7,stroke:#F39C12,stroke-width:2px;
    classDef testStackStyle fill:#D4EFDF,stroke:#27AE60,stroke-width:2px;
    classDef policySimStyle fill:#D6EAF8,stroke:#2980B9,stroke-width:2px;
```
