# sathishkst82/sathish-az-_trrafom-demo architecture

> Architecture diagram of the GitHub repository sathishkst82/sathish-az-_trrafom-demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sathishkst82/sathish-az-_trrafom-demo
- Repository: https://github.com/sathishkst82/sathish-az-_trrafom-demo

## Overview

1. **What this repo is**
   - This is a Terraform-based Azure platform repository, not an application repo.
   - It provisions three Azure environments — `dev`, `uat`, and `prod` — using reusable Terraform modules and GitHub Actions-driven delivery.

2. **Top-level architecture boundary**
   - The repository has two main layers:
     - **Reusable modules** in `modules/` for network, VM, storage, and governance.
     - **Environment stacks** in `environments/dev`, `environments/uat`, and `environments/prod` that compose those modules into deployable environments.
   - The root also contains shared provider/version config and CI/CD workflows.

3. **Environment stacks as deployment units**
   - Each environment directory is a separate Terraform root module with its own backend, provider config, variables, and outputs.
   - These stacks are the actual deployment boundary for Azure state: each environment has its own remote state key and its own resource group, network, compute, storage, and policy assignment footprint.

4. **Shared infrastructure modules**
   - `modules/vnet` creates the segmented network core: VNET, multiple subnets, NSGs, route tables, and private DNS/VNET link wiring.
   - `modules/vm` provisions Windows compute with private access patterns and managed identity.
   - `modules/storage` provisions hardened storage accounts and containers, with private endpoint/private access support.
   - `modules/governance` creates Azure Policy definitions, initiatives, and assignments.

5. **Primary data/infrastructure flow**
   - The central flow is: environment stack → resource group → platform modules → Azure resources.
   - Network is the first dependency because VM and storage modules attach into the environment VNET and subnets.
   - Governance is then assigned at the environment resource group level so policy applies across the environment’s resources.

6. **Network and segmentation model**
   - The architecture is private-first and segmented by subnet function.
   - Each environment uses a non-overlapping `/16` CIDR, with subnet boundaries reserved for management, application, data, private endpoint, and future expansion.
   - This layout is intended to support predictable routing, hub/spoke readiness, and private endpoint patterns.

7. **Security and governance boundary**
   - Azure Policy is the governance layer, with custom policies for required tags, allowed regions, and denying public IPs.
   - Policies are grouped into a baseline initiative and assigned per environment.
   - DEV and UAT are configured for softer adoption, while PROD is enforced more strictly.
   - Security controls are also embedded in the platform modules: no public IPs by default, private storage access, TLS/HTTPS protections, and managed identity on VMs.

8. **Identity and deployment authentication**
   - The repo uses GitHub OIDC federation to Azure; there are no long-lived Azure client secrets in the repo.
   - GitHub Environments supply Azure client/tenant/subscription context and sensitive inputs like the Windows admin password.
   - This makes GitHub Actions the deployment control plane and Azure the target runtime.

9. **CI/CD orchestration**
   - The key workflow is `.github/workflows/iac-dispatch.yml`, which acts as the entrypoint and dispatches to reusable Terraform workflows.
   - The pipeline stages are:
     - validation: fmt, init, validate, terraform-docs checks, TFLint
     - plan: includes Wiz IaC scanning and plan artifact creation
     - apply: reuses the saved plan for deterministic deployment
     - destroy-plan / destroy-apply: separate reviewable destroy lifecycle
   - PROD apply/destroy is gated by GitHub Environment approval.

10. **State and backend architecture**
    - Every environment uses the AzureRM backend, but backend settings are injected at runtime by the workflow.
    - State is therefore externalized to a dedicated Azure storage backend and separated per environment via backend keying.
    - This creates a hard boundary between local code and persisted infrastructure state.

11. **Testing and quality gates**
    - The `tests/` directory contains Terratest-based validation for at least the VNET module using fixtures.
    - The repo also enforces static and policy checks with TFLint, terraform-docs validation, policy JSON checks, and IaC scanning.
    - This makes the module boundary testable independently from full environment deployments.

12. **Operational documentation and design intent**
    - The `docs/` folder contains architecture, network, OIDC, environment setup, and governance guidance.
    - The architecture documentation is not decorative; it reflects the implementation layout and helps explain intended subnetting, policy posture, and deployment workflow.
    - The overall design is enterprise platform infrastructure: reusable, environment-scoped, private-by-default, and governed at the Azure control plane.

Main entry points: [`environments/dev/main.tf`](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/environments/dev/main.tf) (Dev stack), [`environments/uat/main.tf`](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/environments/uat/main.tf) (UAT stack), [`environments/prod/main.tf`](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/environments/prod/main.tf) (Prod stack), [`modules/governance/main.tf`](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/modules/governance/main.tf) (Governance module)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Root"]
  node_root_config["Root config<br/>terraform root<br/>[providers.tf]"]
  node_root_versions["Versions<br/>terraform constraints<br/>[versions.tf]"]
end

subgraph group_envs["Environments"]
  node_dev_stack["Dev stack<br/>env root<br/>[main.tf]"]
  node_uat_stack["UAT stack<br/>env root<br/>[main.tf]"]
  node_prod_stack["Prod stack<br/>env root<br/>[main.tf]"]
end

subgraph group_mods["Modules"]
  node_vnet_mod["VNet module<br/>network module<br/>[main.tf]"]
  node_vm_mod["VM module<br/>compute module<br/>[main.tf]"]
  node_storage_mod[("Storage module<br/>[main.tf]")]
  node_gov_mod["Governance module<br/>policy module<br/>[main.tf]"]
end

subgraph group_gov["Governance"]
  node_tags_policy["Tags policy<br/>policy json"]
  node_regions_policy["Regions policy<br/>policy json"]
  node_deny_ip_policy["Deny IP policy<br/>policy json"]
end

subgraph group_cicd["CI/CD"]
  node_iac_dispatch["Dispatch<br/>workflow entrypoint<br/>[iac-dispatch.yml]"]
  node_tf_validate["Validate<br/>workflow stage"]
  node_tf_plan["Plan<br/>workflow stage<br/>[terraform-plan.yml]"]
  node_tf_apply["Apply<br/>workflow stage"]
  node_tf_destroy["Destroy<br/>workflow stage"]
end

subgraph group_docs["Docs & Tests"]
  node_vnet_test["VNet tests<br/>terratest<br/>[vnet_test.go]"]
  node_network_docs["Network docs<br/>architecture doc"]
  node_oidc_docs["OIDC docs<br/>setup doc<br/>[oidc-setup.md]"]
end

node_root_config -->|"shared provider"| node_dev_stack
node_root_config -->|"shared provider"| node_uat_stack
node_root_config -->|"shared provider"| node_prod_stack
node_root_versions -->|"constraints"| node_dev_stack
node_root_versions -->|"constraints"| node_uat_stack
node_root_versions -->|"constraints"| node_prod_stack
node_dev_stack -->|"uses"| node_vnet_mod
node_dev_stack -->|"uses"| node_vm_mod
node_dev_stack -->|"uses"| node_storage_mod
node_dev_stack -->|"assigns"| node_gov_mod
node_uat_stack -->|"uses"| node_vnet_mod
node_uat_stack -->|"uses"| node_vm_mod
node_uat_stack -->|"uses"| node_storage_mod
node_uat_stack -->|"assigns"| node_gov_mod
node_prod_stack -->|"uses"| node_vnet_mod
node_prod_stack -->|"uses"| node_vm_mod
node_prod_stack -->|"uses"| node_storage_mod
node_prod_stack -->|"assigns"| node_gov_mod
node_gov_mod -->|"loads"| node_tags_policy
node_gov_mod -->|"loads"| node_regions_policy
node_gov_mod -->|"loads"| node_deny_ip_policy
node_iac_dispatch -->|"dispatches"| node_tf_validate
node_iac_dispatch -->|"dispatches"| node_tf_plan
node_iac_dispatch -->|"dispatches"| node_tf_apply
node_iac_dispatch -->|"dispatches"| node_tf_destroy
node_tf_plan -->|"saves plan"| node_tf_apply
node_vnet_test -->|"tests"| node_vnet_mod
node_network_docs -.->|"describes"| node_vnet_mod
node_oidc_docs -.->|"describes"| node_iac_dispatch

click node_root_config "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/providers.tf"
click node_root_versions "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/versions.tf"
click node_dev_stack "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/environments/dev/main.tf"
click node_uat_stack "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/environments/uat/main.tf"
click node_prod_stack "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/environments/prod/main.tf"
click node_vnet_mod "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/modules/vnet/main.tf"
click node_vm_mod "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/modules/vm/main.tf"
click node_storage_mod "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/modules/storage/main.tf"
click node_gov_mod "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/modules/governance/main.tf"
click node_tags_policy "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/governance/require-tags-policy.json"
click node_regions_policy "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/governance/allowed-regions-policy.json"
click node_deny_ip_policy "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/governance/deny-public-ip-policy.json"
click node_iac_dispatch "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/.github/workflows/iac-dispatch.yml"
click node_tf_validate "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/.github/workflows/terraform-validate.yml"
click node_tf_plan "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/.github/workflows/terraform-plan.yml"
click node_tf_apply "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/.github/workflows/terraform-apply.yml"
click node_tf_destroy "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/.github/workflows/terraform-destroy-plan.yml"
click node_vnet_test "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/tests/vnet_test.go"
click node_network_docs "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/docs/network-architecture.md"
click node_oidc_docs "https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/docs/oidc-setup.md"

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_root_config,node_root_versions toneBlue
class node_dev_stack,node_uat_stack,node_prod_stack toneAmber
class node_vnet_mod,node_vm_mod,node_storage_mod,node_gov_mod toneMint
class node_tags_policy,node_regions_policy,node_deny_ip_policy toneRose
class node_iac_dispatch,node_tf_validate,node_tf_plan,node_tf_apply,node_tf_destroy toneIndigo
class node_vnet_test,node_network_docs,node_oidc_docs toneTeal
```

## Components

### Root

Shared Terraform, providers, and repo entrypoints

- [Root config](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/providers.tf): terraform root · Shared Terraform provider and version configuration at repository root · `providers.tf`
- [Versions](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/versions.tf): terraform constraints · Common Terraform and provider version constraints · `versions.tf`

### Environments

Separate Terraform root modules for dev, uat, and prod

- [Dev stack](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/environments/dev/main.tf): env root · Terraform root module for the dev environment · `environments/dev/main.tf`
- [UAT stack](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/environments/uat/main.tf): env root · Terraform root module for the uat environment · `environments/uat/main.tf`
- [Prod stack](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/environments/prod/main.tf): env root · Terraform root module for the prod environment · `environments/prod/main.tf`

### Modules

Reusable platform modules

- [VNet module](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/modules/vnet/main.tf): network module · Creates segmented private networking, subnets, NSGs, routing, and DNS links · `modules/vnet/main.tf`
- [VM module](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/modules/vm/main.tf): compute module · Provisions Windows virtual machines with managed identity and private access patterns · `modules/vm/main.tf`
- [Storage module](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/modules/storage/main.tf): storage module · Creates hardened storage accounts and containers with private access support · `modules/storage/main.tf`
- [Governance module](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/modules/governance/main.tf): policy module · Creates policy definitions, initiatives, and assignments · `modules/governance/main.tf`

### Governance

Policy definitions used by the governance module

- [Tags policy](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/governance/require-tags-policy.json): policy json · Custom policy requiring resource tags · `governance/require-tags-policy.json`
- [Regions policy](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/governance/allowed-regions-policy.json): policy json · Custom policy restricting allowed Azure regions · `governance/allowed-regions-policy.json`
- [Deny IP policy](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/governance/deny-public-ip-policy.json): policy json · Custom policy denying public IP usage · `governance/deny-public-ip-policy.json`

### CI/CD

GitHub Actions workflows for validation, planning, and deployment

- [Dispatch](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/.github/workflows/iac-dispatch.yml): workflow entrypoint · Entry workflow that routes infrastructure actions into reusable Terraform workflows · `.github/workflows/iac-dispatch.yml`
- [Validate](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/.github/workflows/terraform-validate.yml): workflow stage · Runs fmt, init, validate, docs checks, and linting · `.github/workflows/terraform-validate.yml`
- [Plan](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/.github/workflows/terraform-plan.yml): workflow stage · Creates reviewed Terraform plans and runs IaC scanning · `.github/workflows/terraform-plan.yml`
- [Apply](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/.github/workflows/terraform-apply.yml): workflow stage · Applies saved plans for deterministic deployment · `.github/workflows/terraform-apply.yml`
- [Destroy](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/.github/workflows/terraform-destroy-plan.yml): workflow stage · Reviewable destroy planning and application flow · `.github/workflows/terraform-destroy-plan.yml`

### Docs & Tests

Architecture docs and module validation tests

- [VNet tests](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/tests/vnet_test.go): terratest · Terratest coverage for the VNet module using fixtures · `tests/vnet_test.go`
- [Network docs](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/docs/network-architecture.md): architecture doc · Architecture guidance for subnetting, private access, and segmentation · `docs/network-architecture.md`
- [OIDC docs](https://github.com/sathishkst82/sathish-az-_trrafom-demo/blob/main/docs/oidc-setup.md): setup doc · Documentation for GitHub OIDC federation to Azure · `docs/oidc-setup.md`

## Connections

- Root config → Dev stack: shared provider · Environment stacks inherit common provider configuration
- Root config → UAT stack: shared provider · Environment stacks inherit common provider configuration
- Root config → Prod stack: shared provider · Environment stacks inherit common provider configuration
- Versions → Dev stack: constraints · Version constraints apply to environment roots
- Versions → UAT stack: constraints · Version constraints apply to environment roots
- Versions → Prod stack: constraints · Version constraints apply to environment roots
- Dev stack → VNet module: uses · Dev composes the shared network module
- Dev stack → VM module: uses · Dev composes the shared compute module
- Dev stack → Storage module: uses · Dev composes the shared storage module
- Dev stack → Governance module: assigns · Dev assigns baseline governance to the environment
- UAT stack → VNet module: uses · UAT composes the shared network module
- UAT stack → VM module: uses · UAT composes the shared compute module
- UAT stack → Storage module: uses · UAT composes the shared storage module
- UAT stack → Governance module: assigns · UAT assigns baseline governance to the environment
- Prod stack → VNet module: uses · Prod composes the shared network module
- Prod stack → VM module: uses · Prod composes the shared compute module
- Prod stack → Storage module: uses · Prod composes the shared storage module
- Prod stack → Governance module: assigns · Prod assigns baseline governance to the environment
- Governance module → Tags policy: loads · Governance module consumes custom policy definitions
- Governance module → Regions policy: loads · Governance module consumes custom policy definitions
- Governance module → Deny IP policy: loads · Governance module consumes custom policy definitions
- Dispatch → Validate: dispatches · Workflow entrypoint sends runs to validation
- Dispatch → Plan: dispatches · Workflow entrypoint sends runs to planning
- Dispatch → Apply: dispatches · Workflow entrypoint sends runs to apply
- Dispatch → Destroy: dispatches · Workflow entrypoint sends runs to destroy lifecycle
- Plan → Apply: saves plan · Apply reuses the reviewed plan artifact
- VNet tests → VNet module: tests · Terratest validates the network module behavior
- Network docs → VNet module: describes · Docs explain the network architecture embodied by the module
- OIDC docs → Dispatch: describes · Docs explain GitHub OIDC-based deployment authentication
