Repository anatomy¶

This section is a guided tour of the customer landing-zone repository: every folder, every file, and what each one is for.

The repository is generated from nrit-alz-customer-template. This section documents that template as it ships, because that is exactly what a new customer receives. A deployed repository differs from it only in the placeholder values you set during onboarding and in the units you add afterwards.

Where this fits¶

The Setup section tells you what to do. This section tells you what you are looking at. If you are standing up a new customer, start with Setup. If you are reading an existing repository and want to know why a file exists, start here.

The four repositories¶

Only one of these ends up in customer hands.

Repository	Role	Customer sees it
`nrit-alz-customer-template`	The template every customer repository is generated from.	Yes, as their own repo.
`nrit-tf-pr-ops`	The PR-ops engine. Consumed as a reusable workflow.	No.
`nrit-terragrunt-catalog`	Source history of the custom Azure Policy library. The library is vendored into the repository; the catalog is not referenced at run time.	No.
`nrit-alz-bootstrap`	Creates the backend, identities, runner, and the repository itself.	No.

The generated repository holds no engine code. Two small caller workflows reference the engine at a pinned version. What arrives from outside the repository is covered by the bootstrap reference.

The whole repository at a glance¶

<customer>-alz-live/
├── README.md, ONBOARDING.md, CHANGELOG.md, LICENSE
├── mise.toml, .editorconfig, .gitignore
├── projects.yml               # what the engine discovers, and the gate hooks
├── .github/
│   ├── workflows/             # two callers: terraform-pr-ops.yml, drift.yml
│   ├── CODEOWNERS
│   └── pull_request_template.md
├── policy/governance.rego     # the active conftest policy
├── examples/policy/tags.rego  # a reference policy, not active
├── docs/                      # in-repo docs, shipped to the customer
└── live/                      # everything deployable
    ├── root.hcl               # backend, providers, shared locals
    ├── tenant.hcl             # tenant id and the MG the hierarchy is built under
    ├── _foundation/           # tenant-wide governance, deployed first
    ├── platform/              # connectivity, identity, management, security
    ├── landingzones/          # corp, online, local
    ├── sandbox/
    └── decommissioned/

Two rules explain most of the layout. Everything deployable lives under live/, the Gruntwork infrastructure-live convention, and repository meta stays at the root. Inside live/, folder names are management group IDs, so the tree mirrors the Cloud Adoption Framework hierarchy.

How to read this section¶

Page	Covers
The repository root	The root files, the conftest policy, and the in-repo docs.
Workflows and discovery config	The two caller workflows and `projects.yml`.
The live tree	The naming convention, what a unit is, and how discovery works.
The root contract	`root.hcl`, `tenant.hcl`, and the scope files.
The foundation units	The three units that build the tenant governance.
The vendored policy library	The custom ALZ library under `lib/`.

Turning the placeholder folders into real units is day-2 work, covered in Growing the tree.

The template ships resource-free

The three _foundation units are wired but carry placeholder values, and every management group folder under platform/ and landingzones/ is a README only. A freshly generated repository generates and validates before a single Azure resource exists.

Next: The repository root.