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 core, private. Consumed as a reusable workflow through the public `tf-pr-ops` entrypoint.	No.
`nrit-alz-bootstrap`	Creates the backend, identities, runner, and the repository itself.	No.

The generated repository holds no engine code. Four 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
├── AGENTS.md, CLAUDE.md         # instructions for AI coding agents
├── .mcp.json, .claude/          # MCP servers and vendored agent skills
├── mise.toml, .editorconfig, .gitignore
├── .pre-commit-config.yaml    # commit hooks; .tflint.hcl and .checkov.yaml configure them
├── projects.yml               # discovery, the gate_ignore list, and the gate hooks
├── .github/
│   ├── workflows/             # the four engine callers
│   ├── scripts/               # the repository-invariants check the hooks run
│   ├── CODEOWNERS
│   └── pull_request_template.md
├── policy/                    # the conftest gate; nothing active by default
│   └── tags.rego.example      #   a starter policy, drop .example to activate
└── 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 and the conftest policy.
Workflows and discovery config	The four caller workflows, the pre-commit gate, 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.