# steph409/tf-azure-monitor-baseline-alerts architecture

> Architecture diagram of the GitHub repository steph409/tf-azure-monitor-baseline-alerts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/steph409/tf-azure-monitor-baseline-alerts
- Repository: https://github.com/steph409/tf-azure-monitor-baseline-alerts

## Overview

##### Project type and purpose
- This is an Infrastructure-as-Code (IaC) Terraform module targeting Azure.
- Its purpose is to deploy Azure Monitor baseline alerts across an Enterprise-Scale Landing Zone hierarchy using Azure Policy definitions and assignments.

##### File structure
A. Top-level
- terraform.tf, variables.tf, policy_definitions.tf, policy_assignment_*.tf – root Terraform configuration that orchestrates modules
- .github/scripts – automation scripts (PowerShell) for updating library definitions
- examples/ – opinionated usage scenarios illustrating default and parameterized deployments
B. lib/
- archetype_definitions/ – JSON templates for high-level “initiative” (policy set) definitions per management group archetype (root, platform, identity, etc.)
- policy_definitions/ – low-level JSON policy definitions for individual alerts
- policy_set_definitions/ – JSON combining multiple policy definitions into initiatives
- policy_assignments/ – JSON wrappers for assigning initiatives to management groups
C. module/
- policy_definition/ – Terraform module that reads JSON in lib/policy_definitions and policy_set_definitions to create Azure PolicyDefinition and PolicySetDefinition resources
- policy_assignment/ – Terraform module that reads JSON in lib/archetype_definitions and policy_assignments to assign initiatives to specific Management Groups
D. examples/
- default, default_with_all_parameters, default_with_dashboards, only_platform_subscription – sample root module invocations showing how to configure variables and parameters for different scopes

##### README for architectural insights
- Describes a hierarchy of Azure Management Groups: root → landing-zones; root-platform → {identity, connectivity, management}
- Indicates which initiatives (policy sets) get assigned to which management group
- Points to cleanup patterns, versioning, and parameter overrides

##### Main components
A. Developer / CI Environment
- Local Dev Machine or Azure DevOps / GitHub Actions runner
- Terraform CLI and PowerShell script (.github/scripts)
B. Code Repository (GitHub)
- Terraform root configuration, modules, lib JSON artifacts, examples
C. Terraform Modules
1. policy_definition module
2. policy_assignment module
D. Library of JSON definitions (lib/)
- policy_definitions, policy_set_definitions, archetype_definitions, policy_assignments
E. Azure Control Plane
- Azure Resource Manager (ARM) API
- Azure Policy Service
- Azure Management Groups hierarchy
F. Optional: Example Workflows
- example/ directories illustrating terraform init/plan/apply usage
- Parameter overrides via variables.tf or .tfvars

##### Relationships and interactions
1. Developer/CI pushes code → triggers GitHub Actions / CI pipeline
2. CI runner clones repo and executes Terraform init, plan, apply
3. Terraform root config invokes the policy_definition and policy_assignment modules
4. Modules load JSON artifacts from lib/ and call ARM API to:
a. Create PolicyDefinition and PolicySetDefinition resources
b. Assign those policy sets to specific Management Groups
5. Azure Policy Service stores definitions and enforces alerts on monitored resources

##### Architectural patterns & design principles
- Layered modularization: root config delegates to small purpose-built modules
- Separation of concerns: JSON artifacts decoupled from Terraform logic
- Reusability: examples show how to parameterize and reuse modules across subscriptions
- Declarative infrastructure: Terraform HCL drives all Azure changes

##### Technologies, frameworks & libraries
- Terraform (HCL)
- Azure Policy & Management Groups
- JSON for policy definitions
- PowerShell for library updates
- GitHub Actions / Azure DevOps for CI

##### Diagramming recommendations
- Code push → CI runner → Terraform execution
- Terraform modules → ARM API calls → Policy Service → Management Groups
- Green for code artifacts (repo, modules, JSON)
- Orange for CI pipeline
- Blue for Azure cloud services

##### Detail while avoiding over-complexity
- Major Terraform modules and JSON libraries as separate nodes

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer/CI Environment
    subgraph "Developer / CI Environment"
        D1["Local Dev or CI Runner"]:::ci
        PS["PowerShell Scripts"]:::code
    end

    %% Code Repository
    subgraph "Code Repository"
        subgraph "Terraform Root Config"
            TF1["terraform.tf"]:::code
            TF2["variables.tf"]:::code
            TF3["policy_definitions.tf"]:::code
            TF4["policy_assignment_connectivity.tf"]:::code
            TF5["policy_assignment_identity.tf"]:::code
            TF6["policy_assignment_landingzones.tf"]:::code
            TF7["policy_assignment_management.tf"]:::code
            TF8["policy_assignment_root.tf"]:::code
        end
        subgraph "Examples"
            EX1["examples/default"]:::code
            EX2["examples/default_with_all_parameters"]:::code
            EX3["examples/default_with_dashboards"]:::code
            EX4["examples/only_platform_subscription"]:::code
        end
    end

    %% JSON Library
    subgraph "JSON Library" 
        JL1["Archetype Definitions"]:::code
        JL2["Policy Definitions"]:::code
        JL3["Policy Set Definitions"]:::code
        JL4["Policy Assignments"]:::code
    end

    %% Terraform Modules
    subgraph "Terraform Modules"
        TM1["policy_definition module"]:::code
        TM2["policy_assignment module"]:::code
        TM3["shared module"]:::code
    end

    %% Azure Control Plane
    subgraph "Azure Control Plane"
        ARM["Azure Resource Manager API"]:::azure
        PSvc["Azure Policy Service"]:::azure
        MG["Management Groups Hierarchy"]:::azure
    end

    %% Connections
    D1 -->|"push code"| TF1
    D1 --> PS
    PS --> TF1
    TF1 -->|"triggers CI"| D1
    TF1 -->|"uses modules"| TM1
    TF1 -->|"uses modules"| TM2
    TF1 -->|"uses modules"| TM3
    TM1 -->|"reads JSON"| JL2
    TM1 -->|"reads JSON"| JL3
    TM2 -->|"reads JSON"| JL1
    TM2 -->|"reads JSON"| JL4
    TM1 -->|"calls ARM API: Create PolicyDefinition/Set"| ARM
    TM2 -->|"calls ARM API: Assign Policies"| ARM
    ARM -->|"stores definitions"| PSvc
    PSvc -->|"enforces alerts on"| MG

    %% Click Events
    click PS "https://github.com/steph409/tf-azure-monitor-baseline-alerts/tree/main/.github/scripts/"
    click PS "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/.github/scripts/Invoke-LibraryUpdatePolicyDefinitions.ps1"
    click TF1 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/terraform.tf"
    click TF2 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/variables.tf"
    click TF3 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/policy_definitions.tf"
    click TF4 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/policy_assignment_connectivity.tf"
    click TF5 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/policy_assignment_identity.tf"
    click TF6 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/policy_assignment_landingzones.tf"
    click TF7 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/policy_assignment_management.tf"
    click TF8 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/policy_assignment_root.tf"
    click EX1 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/tree/main/examples/default/"
    click EX2 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/tree/main/examples/default_with_all_parameters/"
    click EX3 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/tree/main/examples/default_with_dashboards/"
    click EX4 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/tree/main/examples/only_platform_subscription/"
    click JL1 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/tree/main/lib/archetype_definitions/"
    click JL2 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/tree/main/lib/policy_definitions/"
    click JL3 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/tree/main/lib/policy_set_definitions/"
    click JL4 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/tree/main/lib/policy_assignments/"
    click TM1 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/module/policy_definition/main.tf"
    click TM1 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/module/policy_definition/variables.tf"
    click TM2 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/module/policy_assignment/main.tf"
    click TM2 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/module/policy_assignment/variables.tf"
    click TM3 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/module/main.tf"
    click TM3 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/module/terraform.tf"
    click TM3 "https://github.com/steph409/tf-azure-monitor-baseline-alerts/blob/main/module/variables.tf"

    %% Styles
    classDef code fill:#a5d6a7,stroke:#388e3c,color:#000
    classDef ci fill:#ffcc80,stroke:#ef6c00,color:#000
    classDef azure fill:#81d4fa,stroke:#1565c0,color:#000
```
