# lcarli/landingzoneassessment-automate architecture

> Architecture diagram of the GitHub repository lcarli/landingzoneassessment-automate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lcarli/landingzoneassessment-automate
- Repository: https://github.com/lcarli/landingzoneassessment-automate

## Overview

##### Project Type and Purpose
- This is an open-source Azure Landing Zone Assessment Automation tool written in PowerShell.
- It automates evaluation of Azure Landing Zones, collects data via Azure Resource Graph and Microsoft Graph, applies checklist logic, and generates both JSON reports and an interactive web dashboard.

##### Major Components
a. Infrastructure as Code (ARM & Bicep)
- arm/main.json – Azure Resource Manager template for deploying prerequisites (e.g., Log Analytics workspace, storage account, web app).
- bicep/main.bicep – Bicep version of the same IaC.
b. Execution Scripts (scripts/)
- Initialize.ps1 – authentication, module installation, global context setup.
- Main.ps1 – orchestrator that loads config, exceptions, invokes assessment modules, and writes outputs.
- CreateWebSite.ps1 – provisions or updates the interactive dashboard site using Az.Websites.
- CompareChecklist.ps1 – utility for JSON checklist diff (optional).
c. Assessment Modules (functions/)
- Eight self-contained .ps1 files, one per design area (Billing, IAM, ResourceOrganization, Network, Governance, Security, DevOps, Management).
- Each module dot-sources shared utilities and returns standardized result objects.
d. Shared Libraries (shared/)
- SharedFunctions.ps1 – common helper routines (caching, resource queries).
- ErrorHandling.ps1 – centralized Write-ErrorLog implementation.
- Enums.ps1 – Status enum definitions for consistency.
- Configuration files (config.json, alz_checklist.en.json, exceptions.json)
e. Outputs and Artifacts
- reports/ – Generated JSON report(s) and error logs.
- logs/ – PowerShell transcript logs.
- web/ – Static/HTML dashboard content (index.html, styles.css).
f. Debug Utilities (Debug/)
- DebugFunctions.ps1 and scripts for deep troubleshooting.

##### External Dependencies and Services
- Azure Resource Graph API (for inventory queries)
- Microsoft Graph PowerShell modules (for Entra ID data)
- Azure PowerShell modules (Az.Accounts, Az.Resources, Az.Network, etc.)
- Azure Web App or Storage static website hosting (deployed via ARM/Bicep)

##### Interactions and Data Flow
1. User runs Initialize.ps1 → authenticates to Azure and Microsoft Graph → populates `$global:AzData` and `$global:GraphData`.
2. Main.ps1 loads shared/config.json and alz_checklist.en.json, applies exceptions.json.
3. For each enabled design area, Main.ps1 calls the corresponding functions/*.ps1 module → collects results and raw evidence.
4. SharedFunctions cache and error handling utilities support all module executions.
5. After collecting all results, Main.ps1 writes a combined JSON report to reports/report.json and logs to logs/.
6. CreateWebSite.ps1 is invoked to push or update web/index.html and assets to Azure web hosting.
7. End users open the interactive dashboard in a browser to view charts, tables, and exception overrides.

##### Architectural Patterns and Principles
- Modular Design: Each design area is a self-contained PowerShell module.
- Shared Context Pattern: `$global:AzData` and `$global:GraphData` act as in-memory caches.
- Centralized Error Handling: All errors funnel through Write-ErrorLog in shared/ErrorHandling.ps1.
- Standardized Result Objects: Uniform result structure defined by Set-EvaluationResultObject and Status enum.
- Infrastructure-as-Code: ARM/Bicep templates for provisioning host environment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Deployment Layer
    subgraph "Deployment"
        direction TB
        ARM["arm/main.json"]:::iac
        BICEP["bicep/main.bicep"]:::iac
    end

    %% PowerShell Runtime
    subgraph "PowerShell Runtime"
        direction TB
        Init["Initialize.ps1"]:::script
        Main["Main.ps1"]:::script
        CreateWeb["CreateWebSite.ps1"]:::script
        Compare["CompareChecklist.ps1"]:::script

        subgraph "Assessment Modules"
            direction TB
            Billing["AzureBillingandMicrosoftEntraIDTenants.ps1"]:::module
            IAM["IdentityandAccessManagement.ps1"]:::module
            RO["ResourceOrganization.ps1"]:::module
            Net["NetworkTopologyandConnectivity.ps1"]:::module
            Gov["Governance.ps1"]:::module
            Sec["Security.ps1"]:::module
            DevOps["PlatformAutomationandDevOps.ps1"]:::module
            Mgmt["Management.ps1"]:::module
        end

        subgraph "Shared Libraries & Config"
            direction TB
            SharedFuncs["SharedFunctions.ps1"]:::shared
            ErrHandle["ErrorHandling.ps1"]:::shared
            Enums["Enums.ps1"]:::shared
            Checklist["alz_checklist.en.json"]:::shared
            Config["config.json"]:::shared
            Exceptions["exceptions.json"]:::shared
        end

        Debug["DebugFunctions.ps1"]:::shared
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ARG["Azure Resource Graph"]:::external
        MGraph["Microsoft Graph"]:::external
        AzPS["Azure PowerShell Modules"]:::external
        WebHost["Azure Web Hosting"]:::external
        Browser["Web Browser"]:::external
    end

    %% Outputs
    subgraph "Outputs & Artifacts"
        direction TB
        Reports["reports/"]:::output
        Logs["logs/"]:::output
        WebAssets["web/"]:::output
        Styles["web/styles.css"]:::output
    end

    %% Data Flows
    User(("User")):::external -->|runs| Init
    Init -->|authenticates| ARG
    Init -->|authenticates| MGraph
    Init --> Main

    Main -->|loads config| Config
    Main -->|loads checklist| Checklist
    Main -->|applies exceptions| Exceptions

    Main --> Billing
    Main --> IAM
    Main --> RO
    Main --> Net
    Main --> Gov
    Main --> Sec
    Main --> DevOps
    Main --> Mgmt

    Billing --> SharedFuncs
    IAM --> SharedFuncs
    RO --> SharedFuncs
    Net --> SharedFuncs
    Gov --> SharedFuncs
    Sec --> SharedFuncs
    DevOps --> SharedFuncs
    Mgmt --> SharedFuncs

    SharedFuncs --> ErrHandle
    Enums --> Main

    Main --> Reports
    Main --> Logs

    CreateWeb --> WebAssets
    CreateWeb --> WebHost
    WebHost --> Browser

    Compare -->|optional diff| Checklist

    Debug --> SharedFuncs

    ARM --> CreateWeb
    BICEP --> CreateWeb

    %% Click Events
    click ARM "https://github.com/lcarli/landingzoneassessment-automate/blob/main/arm/main.json"
    click BICEP "https://github.com/lcarli/landingzoneassessment-automate/blob/main/bicep/main.bicep"
    click Init "https://github.com/lcarli/landingzoneassessment-automate/blob/main/scripts/Initialize.ps1"
    click Main "https://github.com/lcarli/landingzoneassessment-automate/blob/main/scripts/Main.ps1"
    click CreateWeb "https://github.com/lcarli/landingzoneassessment-automate/blob/main/scripts/CreateWebSite.ps1"
    click Compare "https://github.com/lcarli/landingzoneassessment-automate/blob/main/scripts/CompareChecklist.ps1"
    click Billing "https://github.com/lcarli/landingzoneassessment-automate/blob/main/functions/AzureBillingandMicrosoftEntraIDTenants.ps1"
    click IAM "https://github.com/lcarli/landingzoneassessment-automate/blob/main/functions/IdentityandAccessManagement.ps1"
    click RO "https://github.com/lcarli/landingzoneassessment-automate/blob/main/functions/ResourceOrganization.ps1"
    click Net "https://github.com/lcarli/landingzoneassessment-automate/blob/main/functions/NetworkTopologyandConnectivity.ps1"
    click Gov "https://github.com/lcarli/landingzoneassessment-automate/blob/main/functions/Governance.ps1"
    click Sec "https://github.com/lcarli/landingzoneassessment-automate/blob/main/functions/Security.ps1"
    click DevOps "https://github.com/lcarli/landingzoneassessment-automate/blob/main/functions/PlatformAutomationandDevOps.ps1"
    click Mgmt "https://github.com/lcarli/landingzoneassessment-automate/blob/main/functions/Management.ps1"
    click SharedFuncs "https://github.com/lcarli/landingzoneassessment-automate/blob/main/shared/SharedFunctions.ps1"
    click ErrHandle "https://github.com/lcarli/landingzoneassessment-automate/blob/main/shared/ErrorHandling.ps1"
    click Enums "https://github.com/lcarli/landingzoneassessment-automate/blob/main/shared/Enums.ps1"
    click Checklist "https://github.com/lcarli/landingzoneassessment-automate/blob/main/shared/alz_checklist.en.json"
    click Config "https://github.com/lcarli/landingzoneassessment-automate/blob/main/shared/config.json"
    click Exceptions "https://github.com/lcarli/landingzoneassessment-automate/blob/main/shared/exceptions.json"
    click Debug "https://github.com/lcarli/landingzoneassessment-automate/blob/main/Debug/DebugFunctions.ps1"
    click WebAssets "https://github.com/lcarli/landingzoneassessment-automate/tree/main/web/"
    click Styles "https://github.com/lcarli/landingzoneassessment-automate/blob/main/web/styles.css"

    %% Styles
    classDef iac fill:#E5C494,stroke:#888,stroke-width:1px
    classDef script fill:#B3CDE3,stroke:#888,stroke-width:1px
    classDef module fill:#FBB4AE,stroke:#888,stroke-width:1px
    classDef shared fill:#CCEBC5,stroke:#888,stroke-width:1px
    classDef external fill:#DECBE4,stroke:#888,stroke-width:1px
    classDef output fill:#FFFFCC,stroke:#888,stroke-width:1px
```
