# aws/lza-universal-configuration architecture

> Architecture diagram of the GitHub repository aws/lza-universal-configuration, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws/lza-universal-configuration
- Repository: https://github.com/aws/lza-universal-configuration

## Overview

This repository is not an application runtime; it is a configuration and documentation package for deploying AWS Landing Zone Accelerator (LZA) Universal Configuration. The architectural boundary is “source configuration in Git” on one side, and “generated LZA deployment inputs that provision AWS organization and network guardrails” on the other.

1. Core purpose
- The repo defines a standardized multi-account AWS foundation.
- It is organized as reusable configuration modules plus operational guidance.
- The resulting artifacts are intended to be consumed by LZA, which then orchestrates AWS service provisioning and policy enforcement.

2. Top-level structure
- `docs/` contains the architecture, onboarding, governance, security, networking, logging, and operations guidance.
- `modules/` contains the actual deployable configuration inputs.
- `replacements/` contains region-specific substitution files.
- `scripts/` contains Node.js tooling used to transform/package configuration for release and deployment.
- `.gitlab-ci.yml` indicates CI/CD automation around packaging or validation.

3. Base governance and organization subsystem
- `modules/base/default/` is the foundation layer.
- It includes organization-wide definitions such as:
  - account structure (`accounts-config.yaml`, `organization-config.yaml`)
  - global and security settings (`global-config.yaml`, `security-config.yaml`)
  - IAM settings and sample policies
  - tagging policies
  - service control policies and resource control policies
  - replacement configuration and VPC endpoint policies
- This layer represents the control-plane boundary for the AWS Organization and account governance.

4. Security and compliance controls
- The base module also bundles security-related implementation assets:
  - declarative policies
  - SCP/RCP guardrails
  - IAM policy examples
  - backup plans
  - event bus policies
  - dynamic log partitioning filters
- These are not application security features; they are preventive and detective controls applied at the organization/account layer.

5. Operational automation artifacts
- The base module contains SSM documents and remediation roles for operational fixes and guardrail enforcement:
  - attaching IAM instance profiles
  - enabling ELB logging
- This suggests the repo supports not just initial provisioning, but ongoing drift correction and operational remediation.

6. Networking subsystem
- `modules/network/` holds the network architecture patterns.
- Two distinct patterns are provided:
  - `hub-and-spoke/`
  - `shared-vpc/`
- Each includes a `network-config.yaml` and firewall rule definitions.
- This cleanly separates organization/governance from network topology, allowing alternate network models without changing the base controls.

7. Regional specialization
- `replacements/replacements-for-aws-govcloud-us.yaml` indicates that some settings are parameterized or substituted for specific AWS partitions/regions.
- This shows the repo is designed for portability across environments while keeping a common baseline.

8. Documentation as an architectural layer
- The `docs/` tree is structured to match the solution’s major domains:
  - overview
  - getting started
  - management/governance
  - security/identity/compliance
  - networking
  - logging/monitoring
  - operations
  - region/industry guidance
- The docs are effectively the design contract for how the configuration modules should be interpreted and operated.

9. Tooling and transformation pipeline
- `scripts/config-replacer.js`, `scripts/release-package.js`, and related Node.js package files indicate a preprocessing/release stage.
- These scripts likely handle configuration substitution, packaging, and release artifact assembly before LZA consumption.
- This is a build-time concern, not a runtime service.

10. CI/CD boundary
- `.gitlab-ci.yml` shows the repo is meant to be validated and packaged through GitLab CI.
- The pipeline sits between source config and deployment-ready artifacts, supporting repeatable multi-environment delivery.

11. External platform dependencies that shape the architecture
- The repo is built around AWS Landing Zone Accelerator and commonly integrates with AWS Control Tower.
- The config content explicitly targets AWS services such as CloudTrail, Security Hub, GuardDuty, KMS, Network Firewall, CloudWatch, S3, Kinesis, Firehose, and others.
- These services are central because the configuration modules encode their baseline usage and guardrails.

12. Data flow from source to deployed environment
- Engineers edit YAML/JSON/ASL-style artifacts in `modules/` and `replacements/`.
- Scripts and CI process the inputs into deployable configuration packages.
- LZA consumes those packages to create or update AWS Organizations, accounts, security controls, logging, and network infrastructure.
- The deployed environment then generates operational telemetry and compliance posture that the docs assume operators will manage.

13. Architectural takeaway
- The repository is a layered configuration system:
  - governance baseline at the core
  - optional network topology modules beside it
  - region-specific replacements for portability
  - scripts/CI for packaging
  - docs for operational and architectural intent
- For an architecture diagram, the main boxes are “Source Config Repo,” “Transformation/Packaging,” “LZA Deployment,” and “AWS Landing Zone resources,” with the repo’s module boundaries split into governance and networking.

Main entry points: [`modules/base/default`](https://github.com/aws/lza-universal-configuration/tree/main/modules/base/default) (Base Config), [`modules/network`](https://github.com/aws/lza-universal-configuration/tree/main/modules/network) (Network Modules), [`docs`](https://github.com/aws/lza-universal-configuration/tree/main/docs) (Docs), [`.gitlab-ci.yml`](https://github.com/aws/lza-universal-configuration/blob/main/.gitlab-ci.yml) (GitLab CI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repo"]
  node_docs["Docs<br/>guidance"]
  node_base[("Base Config<br/>governance module")]
  node_accounts["Accounts<br/>org config"]
  node_global["Global Settings<br/>config<br/>[global-config.yaml]"]
  node_iam["IAM Config<br/>identity config<br/>[iam-config.yaml]"]
  node_policies{{"Guardrails<br/>policy set"}}
  node_ops["Ops Assets<br/>remediation"]
  node_network[("Network Modules")]
  node_hubspoke["Hub-Spoke<br/>network pattern"]
  node_sharedvpc["Shared VPC<br/>network pattern"]
  node_replacements["Replacements<br/>partition config"]
  node_scripts["Scripts<br/>packaging tools"]
  node_ci["GitLab CI<br/>pipeline<br/>[.gitlab-ci.yml]"]
end

subgraph group_external["External"]
  node_lza[("LZA Package<br/>deployment inputs")]
  node_awsorg[("AWS Org<br/>control plane")]
  node_awsnet[("AWS Network<br/>landing zone network")]
  node_awssec[("AWS Controls<br/>security posture")]
end

node_docs -->|"describes"| node_base
node_docs -->|"describes"| node_network
node_base -->|"contains"| node_accounts
node_base -->|"contains"| node_global
node_base -->|"contains"| node_iam
node_base -->|"contains"| node_policies
node_base -->|"contains"| node_ops
node_network -->|"has"| node_hubspoke
node_network -->|"has"| node_sharedvpc
node_replacements -->|"specializes"| node_base
node_scripts -->|"packages"| node_lza
node_ci -->|"runs"| node_scripts
node_ci -->|"produces"| node_lza
node_lza -->|"provisions"| node_awsorg
node_lza -->|"provisions"| node_awsnet
node_lza -->|"provisions"| node_awssec
node_policies -->|"feeds"| node_lza
node_hubspoke -->|"feeds"| node_lza
node_sharedvpc -->|"feeds"| node_lza
node_ops -->|"remediates"| node_awssec

click node_docs "https://github.com/aws/lza-universal-configuration/tree/main/docs"
click node_base "https://github.com/aws/lza-universal-configuration/tree/main/modules/base/default"
click node_accounts "https://github.com/aws/lza-universal-configuration/blob/main/modules/base/default/accounts-config.yaml"
click node_global "https://github.com/aws/lza-universal-configuration/blob/main/modules/base/default/global-config.yaml"
click node_iam "https://github.com/aws/lza-universal-configuration/blob/main/modules/base/default/iam-config.yaml"
click node_policies "https://github.com/aws/lza-universal-configuration/tree/main/modules/base/default/service-control-policies"
click node_ops "https://github.com/aws/lza-universal-configuration/tree/main/modules/base/default/ssm-documents"
click node_network "https://github.com/aws/lza-universal-configuration/tree/main/modules/network"
click node_hubspoke "https://github.com/aws/lza-universal-configuration/blob/main/modules/network/hub-and-spoke/network-config.yaml"
click node_sharedvpc "https://github.com/aws/lza-universal-configuration/blob/main/modules/network/shared-vpc/network-config.yaml"
click node_replacements "https://github.com/aws/lza-universal-configuration/blob/main/replacements/replacements-for-aws-govcloud-us.yaml"
click node_scripts "https://github.com/aws/lza-universal-configuration/tree/main/scripts"
click node_ci "https://github.com/aws/lza-universal-configuration/blob/main/.gitlab-ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_docs,node_base,node_accounts,node_global,node_iam,node_policies,node_ops,node_network,node_hubspoke,node_sharedvpc,node_replacements,node_scripts,node_ci toneBlue
class node_lza,node_awsorg,node_awsnet,node_awssec toneAmber
```

## Components

### Repo

Source configuration, packaging, and documentation in Git

- [Docs](https://github.com/aws/lza-universal-configuration/tree/main/docs): guidance · Architecture, onboarding, operations, and domain guidance · `docs`
- [Base Config](https://github.com/aws/lza-universal-configuration/tree/main/modules/base/default): governance module · Foundation layer for organization-wide settings and guardrails · `modules/base/default`
- [Accounts](https://github.com/aws/lza-universal-configuration/blob/main/modules/base/default/accounts-config.yaml): org config · Account and organization structure definitions · `modules/base/default/accounts-config.yaml`
- [Global Settings](https://github.com/aws/lza-universal-configuration/blob/main/modules/base/default/global-config.yaml): config · Global and security-wide configuration · `modules/base/default/global-config.yaml`
- [IAM Config](https://github.com/aws/lza-universal-configuration/blob/main/modules/base/default/iam-config.yaml): identity config · IAM settings and policy inputs · `modules/base/default/iam-config.yaml`
- [Guardrails](https://github.com/aws/lza-universal-configuration/tree/main/modules/base/default/service-control-policies): policy set · SCPs, RCPs, tagging, declarative, event bus, and endpoint policies · `modules/base/default/service-control-policies`
- [Ops Assets](https://github.com/aws/lza-universal-configuration/tree/main/modules/base/default/ssm-documents): remediation · SSM documents and remediation roles for drift correction · `modules/base/default/ssm-documents`
- [Network Modules](https://github.com/aws/lza-universal-configuration/tree/main/modules/network): network module · Alternative landing zone network topologies · `modules/network`
- [Hub-Spoke](https://github.com/aws/lza-universal-configuration/blob/main/modules/network/hub-and-spoke/network-config.yaml): network pattern · Centralized network pattern with firewall rules · `modules/network/hub-and-spoke/network-config.yaml`
- [Shared VPC](https://github.com/aws/lza-universal-configuration/blob/main/modules/network/shared-vpc/network-config.yaml): network pattern · Shared VPC network pattern with firewall rules · `modules/network/shared-vpc/network-config.yaml`
- [Replacements](https://github.com/aws/lza-universal-configuration/blob/main/replacements/replacements-for-aws-govcloud-us.yaml): partition config · Region and partition substitutions for portability · `replacements/replacements-for-aws-govcloud-us.yaml`
- [Scripts](https://github.com/aws/lza-universal-configuration/tree/main/scripts): packaging tools · Node.js tooling for substitution and release packaging · `scripts`
- [GitLab CI](https://github.com/aws/lza-universal-configuration/blob/main/.gitlab-ci.yml): pipeline · Validation and packaging automation · `.gitlab-ci.yml`

### External

Downstream deployment platform and AWS landing zone outputs

- **LZA Package**: deployment inputs · Generated configuration consumed by Landing Zone Accelerator
- **AWS Org**: control plane · AWS Organizations, accounts, and governance baseline
- **AWS Network**: landing zone network · Provisioned network topology and firewall controls
- **AWS Controls**: security posture · Provisioned security, logging, compliance, and remediation services

## Connections

- Docs → Base Config: describes · Documentation explains the governance and deployment modules
- Docs → Network Modules: describes · Documentation explains network patterns and operations
- Base Config → Accounts: contains · Base module includes organization and account structure
- Base Config → Global Settings: contains · Base module includes global configuration
- Base Config → IAM Config: contains · Base module includes IAM settings
- Base Config → Guardrails: contains · Base module bundles guardrail and policy inputs
- Base Config → Ops Assets: contains · Base module includes operational remediation assets
- Network Modules → Hub-Spoke: has · Network subsystem provides hub-and-spoke pattern
- Network Modules → Shared VPC: has · Network subsystem provides shared VPC pattern
- Replacements → Base Config: specializes · Partition-specific substitutions adjust base config
- Scripts → LZA Package: packages · Scripts transform configuration into deployable inputs
- GitLab CI → Scripts: runs · CI executes packaging and validation tooling
- GitLab CI → LZA Package: produces · Pipeline emits deployment-ready package artifacts
- LZA Package → AWS Org: provisions · LZA applies organization and account governance
- LZA Package → AWS Network: provisions · LZA applies selected network topology and firewall rules
- LZA Package → AWS Controls: provisions · LZA provisions security, logging, and remediation controls
- Guardrails → LZA Package: feeds · Guardrail policies are consumed during deployment
- Hub-Spoke → LZA Package: feeds · Hub-and-spoke network config is consumed during deployment
- Shared VPC → LZA Package: feeds · Shared VPC network config is consumed during deployment
- Ops Assets → AWS Controls: remediates · Operational assets support drift correction in the landing zone
