# aws-samples/aws-account-vending-machine architecture

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

- Interactive diagram: https://gitdiagram.com/aws-samples/aws-account-vending-machine
- Repository: https://github.com/aws-samples/aws-account-vending-machine

## Overview

##### Project Type & Purpose
- This is an AWS infrastructure-automation solution (Account Vending Machine) built on AWS Service Catalog, CloudFormation, AWS Lambda, and AWS Organizations APIs.
- It streamlines on-demand creation and bootstrapping of new AWS accounts (Commercial and GovCloud) with a defined security and service-catalog baseline.

##### File Structure & README
- Top‐level directories:
- **govcloud/** – CloudFormation templates and Lambda zips for AWS GovCloud account vending.
- **resources/** – Commercial-side templates, Lambda code (AccountCreationLambda.py + dependencies), CloudFormation YAMLs, and images.
- Key artifacts:
- **AccountCreationLambda.zip** & `AccountCreationLambdaSetup-cfn.yaml` – Lambda for account creation.
- **accountbuilder.yml**, **Accountbaseline.yml** – Service Catalog product and baseline templates.

##### Main Components
a. **End User / Admin (via AWS Console or Service Catalog API)**
b. **AWS Service Catalog** – Defines the “Account Vending Machine” product.
c. **Amazon S3** – Stores CloudFormation templates and Lambda deployment packages.
d. **CloudFormation (Master Account)**
- Stack to deploy the Service Catalog product and set up IAM roles.
e. **AccountCreation Lambda (Master)**
- Orchestrates account creation, OU creation, role assumption, baseline deployment.
f. **AWS Organizations** – CreateAccount API, OU hierarchy management.
g. **IAM** – OrganizationAccountAccessRole in new account; IAM user/group for Service Catalog access.
h. **CloudFormation (New Account)** – Deploy baseline resources (delete default VPCs, create Service Catalog portfolio & products).
i. **Vended AWS Accounts** – Commercial and GovCloud variants.

##### Relationships & Data Flow
1. End-user launches AVM product in Service Catalog → triggers CloudFormation stack.
2. CloudFormation stack in Master Account deploys:
- Service Catalog product definition (accountbuilder.yml)
- IAM roles & permissions
- AccountCreation Lambda function (zipped from S3)
3. Service Catalog “LAUNCH PRODUCT” → invokes AccountCreation Lambda.
4. Lambda calls AWS Organizations: CreateAccount → returns new account ID.
5. Lambda (if specified) CreateOrganizationalUnit & MoveAccount under OU.
6. Lambda assumes OrganizationAccountAccessRole in new account.
7. Within new account, Lambda (via assumed role) triggers CloudFormation templates stored in S3:
– Accountbaseline.yml (delete default VPCs, set up Service Catalog portfolio/products)
8. Lambda creates IAM user, group, attaches permissions, adds to Service Catalog products.
9. Lambda returns provisioning outputs (AccountID, LoginURL) to Service Catalog.

*GovCloud flow is identical, just using templates under govcloud/govcloud-side-setup and commercial-side-setup.*

##### Architectural Patterns & Principles
- **Serverless Orchestration**: Lambda for orchestration, CloudFormation for infra provisioning.
- **Infrastructure as Code**: Templates version-controlled in repo, stored in S3.
- **Least Privilege**: Newly created IAM user has minimal permissions to use Service Catalog only.
- **Multi-Tenant Partitioning**: Accounts and OUs ensure separation.
- **Extensibility**: Separate pipelines for Commercial vs GovCloud.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Legend
    subgraph "Legend"
        direction TB
        A1["AWS Service"]:::awsservice
        C1["Custom Code"]:::custom
        E1["External/User"]:::external
    end

    %% Top-level Entities
    EU["End User / Admin\n(AWS Console or API)"]:::external

    %% Service Catalog Layer
    SC["AWS Service Catalog\nAccount Vending Product"]:::awsservice

    %% Master Account Components
    subgraph "Master Account" 
        direction TB
        CFNSetup["CloudFormation Stack\n(Lambda Setup)"]:::awsservice
        SCProdCom["Service Catalog Product\n(Commercial)"]:::awsservice
        SCProdGovRepo["Service Catalog Product\n(Commercial Repo Variant)"]:::awsservice
        SCProdGov["Service Catalog Product\n(GovCloud)"]:::awsservice
        LambdaCom["AccountCreation Lambda"]:::custom
    end

    %% S3 Repository
    S3["Amazon S3 Bucket\n(Templates & Lambda zips)"]:::awsservice

    %% AWS Organizations & IAM
    ORG["AWS Organizations\n(CreateAccount, OU)"]:::awsservice
    IAM["IAM\n(OrgAccessRole)"]:::awsservice

    %% New Accounts Cluster
    subgraph "Vended Accounts" 
        direction TB
        style VendedAccounts fill:none,stroke-width:0
        subgraph "Commercial Account" 
            direction TB
            NACOM["New Account\nBaseline Deployment"]:::custom
        end
        subgraph "GovCloud Account" 
            direction TB
            NAGOV["New Account\nBaseline Deployment"]:::custom
        end
    end

    %% Flows
    EU -->|"Launch AVM Product"| SC
    SC -->|"Launch Product"| CFNSetup
    CFNSetup -->|"Deploy Product Definition\n& Lambda"| SCProdCom
    CFNSetup --> SCProdGov
    CFNSetup --> SCProdGovRepo
    CFNSetup --> LambdaCom
    SCProdCom --> S3
    SCProdGov --> S3
    SCProdGovRepo --> S3
    LambdaCom -->|"Fetch code & templates"| S3
    SC -->|"Invoke Lambda"| LambdaCom
    LambdaCom -->|"CreateAccount()"| ORG
    LambdaCom -->|"CreateOrganizationalUnit() / MoveAccount()"| ORG
    LambdaCom -->|"AssumeRole()"| IAM
    LambdaCom -->|"Deploy Baseline Stack"| NACOM
    LambdaCom -->|"Deploy Baseline Stack"| NAGOV

    %% Click Events for component mappings
    click SCProdCom "https://github.com/aws-samples/aws-account-vending-machine/blob/master/resources/accountbuilder.yml"
    click SCProdGov "https://github.com/aws-samples/aws-account-vending-machine/blob/master/govcloud/govcloud-side-setup/govcloud-account-avm-product.yaml"
    click SCProdGovRepo "https://github.com/aws-samples/aws-account-vending-machine/blob/master/govcloud/commercial-side-setup/commercial-account-avm-product.yaml"
    click CFNSetup "https://github.com/aws-samples/aws-account-vending-machine/blob/master/resources/AccountCreationLambdaSetup-cfn.yaml"
    click LambdaCom "https://github.com/aws-samples/aws-account-vending-machine/blob/master/resources/AccountCreationLambda.zip"
    click LambdaCom "https://github.com/aws-samples/aws-account-vending-machine/blob/master/resources/AccountCreationLambdaCode/AccountCreationLambda.py"
    click NACOM "https://github.com/aws-samples/aws-account-vending-machine/blob/master/resources/Accountbaseline.yml"
    click NAGOV "https://github.com/aws-samples/aws-account-vending-machine/blob/master/govcloud/govcloud-side-setup/Accountbaseline.yml"
    click NACOM "https://github.com/aws-samples/aws-account-vending-machine/blob/master/govcloud/commercial-side-setup/CommercialAccountSetup.yaml"
    click NAGOV "https://github.com/aws-samples/aws-account-vending-machine/blob/master/govcloud/govcloud-side-setup/GovCloudAccountSetup.yaml"

    %% Styles
    classDef awsservice fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef custom fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
    classDef external fill:#fff9c4,stroke:#fbc02d,color:#f57f17
    class Legend,A1,C1,E1 external
    class A1 awsservice
    class C1 custom
    class E1 external
```
