# gerenios/aadinternals architecture

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

- Interactive diagram: https://gitdiagram.com/gerenios/aadinternals
- Repository: https://github.com/gerenios/aadinternals

## Overview

##### Project type and purpose
- AADInternals is an open-source PowerShell module/CLI toolkit for administering Azure AD and Office 365.
- It wraps dozens of discrete “features” (ADFS, MFA, GraphAPI, AzureManagementAPI, Teams, SPO, etc.) into a single module.

##### File structure
- Top-level files:
- AADInternals.psd1 (module manifest)
- AADInternals.psm1 (module entry point)
- config.json (global configuration)
- any_sts.pfx (certificate for service-to-service auth)
- LICENSE.md, README.md
- Feature scripts: each feature has two files:
- FeatureName.ps1 — the public cmdlet definitions / entry functions
- FeatureName_utils.ps1 — shared helper functions (HTTP calls, data parsing)
- No frontend; it lives entirely as a PS module loaded into a PowerShell host.

##### README for additional insights
- Confirms installation via Install-Module.
- Purpose statement: “administering Azure AD and Office 365.”

##### Main components
a. PowerShell Host / User CLI
b. AADInternals Module Layer
– Module manifest (psd1) & entry script (psm1)
– Feature scripts (e.g., GraphAPI.ps1, MFA.ps1, Teams.ps1)
– Utility scripts (e.g., GraphAPI_utils.ps1, MFA_utils.ps1)
– config.json and any_sts.pfx for authentication settings
c. External Services
– Azure AD endpoints (OAuth2, token service)
– Microsoft Graph API & AAD Graph API
– Azure Resource Manager APIs
– Office 365 service endpoints (Teams, SharePoint Online, Exchange)
– On-premises components if used (ADFS, DCaaS, HybridHealth)
d. SDK / Library Dependencies
– Microsoft.Identity.Client (used internally by utils to acquire tokens)
– .NET assemblies (IdentityModel.Abstractions) loaded by PowerShell

##### Relationships and interactions
- User enters a cmdlet in PowerShell → PowerShell Host loads AADInternals module → the cmdlet’s .ps1 file invokes functions in its corresponding utils file → utils handle authentication (read config.json, load any_sts.pfx) → utils call underlying SDK or directly invoke REST endpoints → external service (Azure AD/ Graph/Office365) responds → utils parse response and return .NET objects or PSObjects back to the cmdlet → cmdlet formats output for the user.
- All feature scripts share common logic (CommonUtils.ps1) for logging, error handling, HTTP wrappers.

##### Architectural patterns and principles
- Layered: Presentation (CLI), Module Entry, Feature Commands, Shared Utilities, External Services.
- Plugin-style: each feature is self-contained in its own pair of .ps1 files, making it easy to add new features.
- Configuration-driven: config.json + certificate control how authentication is performed.
- DRY utilities: common HTTP, token management, and XML/JSON parsing live in “_utils” files.

## Diagram (Mermaid)

```mermaid
graph TB
    %% User and Host
    User["User"]:::external
    PSHost["PowerShell Host"]:::external

    User -->|invokes cmdlet| PSHost

    %% Module Layer
    subgraph "AADInternals Module" 
        direction TB
        AADInternalsPSD1["AADInternals.psd1"]:::module
        AADInternalsPSM1["AADInternals.psm1"]:::module
        ConfigJSON["config.json"]:::config
        CertStore["any_sts.pfx"]:::config
        ConfigPS["Configuration.ps1"]:::module

        subgraph "Feature Layer"
            direction TB
            ADFS["ADFS.ps1"]:::module
            AccessToken["AccessToken.ps1"]:::module
            GraphAPI["GraphAPI.ps1"]:::module
            MSGraphAPI["MSGraphAPI.ps1"]:::module
            MFA["MFA.ps1"]:::module
            Teams["Teams.ps1"]:::module
            SPO["SPO.ps1"]:::module
            OneDrive["OneDrive.ps1"]:::module
            OutlookAPI["OutlookAPI.ps1"]:::module
            DCaaS["DCaaS.ps1"]:::module
            HybridHealth["HybridHealthServices.ps1"]:::module
            AzureMgmt["AzureManagementAPI.ps1"]:::module
        end

        subgraph "Utils Layer"
            direction TB
            CommonUtils["CommonUtils.ps1"]:::util
            AccessTokenUtils["AccessToken_utils.ps1"]:::util
            GraphAPIUtils["GraphAPI_utils.ps1"]:::util
            MSGraphAPIUtils["MSGraphAPI_utils.ps1"]:::util
            MFAUtils["MFA_utils.ps1"]:::util
            TeamsUtils["Teams_utils.ps1"]:::util
            SPOUtils["SPO_utils.ps1"]:::util
            OneDriveUtils["OneDrive_utils.ps1"]:::util
            OutlookAPIUtils["OutlookAPI_utils.ps1"]:::util
            DCaaSUtils["DCaaS_utils.ps1"]:::util
            HybridHealthUtils["HybridHealthServices_utils.ps1"]:::util
            AzureMgmtUtils["AzureManagementAPI_utils.ps1"]:::util
        end

        PSHost --> AADInternalsPSM1
        AADInternalsPSM1 --> AADInternalsPSD1
        AADInternalsPSM1 --> ConfigJSON
        AADInternalsPSM1 --> CertStore
        AADInternalsPSM1 --> ConfigPS

        %% Feature execution flow
        AADInternalsPSM1 -->|loads feature| ADFS
        AADInternalsPSM1 --> AccessToken
        AADInternalsPSM1 --> GraphAPI
        AADInternalsPSM1 --> MSGraphAPI
        AADInternalsPSM1 --> MFA
        AADInternalsPSM1 --> Teams
        AADInternalsPSM1 --> SPO
        AADInternalsPSM1 --> OneDrive
        AADInternalsPSM1 --> OutlookAPI
        AADInternalsPSM1 --> DCaaS
        AADInternalsPSM1 --> HybridHealth
        AADInternalsPSM1 --> AzureMgmt

        %% Feature to utils
        ADFS --> CommonUtils
        AccessToken --> AccessTokenUtils
        GraphAPI --> GraphAPIUtils
        MSGraphAPI --> MSGraphAPIUtils
        MFA --> MFAUtils
        Teams --> TeamsUtils
        SPO --> SPOUtils
        OneDrive --> OneDriveUtils
        OutlookAPI --> OutlookAPIUtils
        DCaaS --> DCaaSUtils
        HybridHealth --> HybridHealthUtils
        AzureMgmt --> AzureMgmtUtils

        %% Utils to config and cert
        CommonUtils --> ConfigJSON
        CommonUtils --> CertStore

        %% Utils to SDK
        CommonUtils --> SDK_MIClient
        CommonUtils --> SDK_MIMod
        AccessTokenUtils --> SDK_MIClient
        GraphAPIUtils --> SDK_MIClient

    end

    %% SDK / .NET Assemblies
    subgraph "SDK / .NET Assemblies"
        direction TB
        SDK_MIClient["Microsoft.Identity.Client.xml"]:::sdk
        SDK_MIMod["Microsoft.IdentityModel.Abstractions.xml"]:::sdk
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AzureAD["Azure AD OAuth2 / Token Service"]:::external
        MSGraph["Microsoft Graph API"]:::external
        AADGraph["AAD Graph API"]:::external
        ARM["Azure Resource Manager API"]:::external
        TeamsAPI["Teams Service"]:::external
        SPOAPI["SharePoint Online"]:::external
        ExchangeAPI["Exchange Online"]:::external
        ADFSOnPrem["ADFS / On-Prem AD"]:::external
        DCaaSOnPrem["DCaaS / Hybrid Health"]:::external
    end

    %% Data flow to external
    CommonUtils -->|authenticate & call| AzureAD
    CommonUtils -->|REST call| MSGraph
    GraphAPIUtils -->|REST call| AADGraph
    AzureMgmtUtils -->|REST call| ARM
    TeamsUtils -->|REST call| TeamsAPI
    SPOUtils -->|REST call| SPOAPI
    OneDriveUtils -->|REST call| SPOAPI
    OutlookAPIUtils -->|REST call| ExchangeAPI
    ADFSUtils---|calls| ADFSOnPrem
    DCaaSUtils -->|REST call| DCaaSOnPrem
    HybridHealthUtils -->|REST call| DCaaSOnPrem

    %% Responses back to user
    AzureAD --> CommonUtils
    MSGraph --> GraphAPIUtils
    AADGraph --> GraphAPIUtils
    ARM --> AzureMgmtUtils
    TeamsAPI --> TeamsUtils
    SPOAPI --> SPOUtils
    ExchangeAPI --> OutlookAPIUtils
    ADFSOnPrem --> CommonUtils
    DCaaSOnPrem --> CommonUtils

    CommonUtils -->|return data| AADInternalsPSM1
    AADInternalsPSM1 -->|formats output| PSHost
    PSHost -->|displays result| User

    %% Documentation
    README["README.md"]:::doc
    LICENSE["LICENSE.md"]:::doc
    AADInternalsPSD1 --> README
    AADInternalsPSD1 --> LICENSE

    %% Click Events
    click AADInternalsPSD1 "https://github.com/gerenios/aadinternals/blob/master/AADInternals.psd1"
    click AADInternalsPSM1 "https://github.com/gerenios/aadinternals/blob/master/AADInternals.psm1"
    click ADFS "https://github.com/gerenios/aadinternals/blob/master/ADFS.ps1"
    click AccessToken "https://github.com/gerenios/aadinternals/blob/master/AccessToken.ps1"
    click AccessTokenUtils "https://github.com/gerenios/aadinternals/blob/master/AccessToken_utils.ps1"
    click GraphAPI "https://github.com/gerenios/aadinternals/blob/master/GraphAPI.ps1"
    click GraphAPIUtils "https://github.com/gerenios/aadinternals/blob/master/GraphAPI_utils.ps1"
    click MSGraphAPI "https://github.com/gerenios/aadinternals/blob/master/MSGraphAPI.ps1"
    click MSGraphAPIUtils "https://github.com/gerenios/aadinternals/blob/master/MSGraphAPI_utils.ps1"
    click MFA "https://github.com/gerenios/aadinternals/blob/master/MFA.ps1"
    click MFAUtils "https://github.com/gerenios/aadinternals/blob/master/MFA_utils.ps1"
    click Teams "https://github.com/gerenios/aadinternals/blob/master/Teams.ps1"
    click TeamsUtils "https://github.com/gerenios/aadinternals/blob/master/Teams_utils.ps1"
    click SPO "https://github.com/gerenios/aadinternals/blob/master/SPO.ps1"
    click SPOUtils "https://github.com/gerenios/aadinternals/blob/master/SPO_utils.ps1"
    click OneDrive "https://github.com/gerenios/aadinternals/blob/master/OneDrive.ps1"
    click OneDriveUtils "https://github.com/gerenios/aadinternals/blob/master/OneDrive_utils.ps1"
    click OutlookAPI "https://github.com/gerenios/aadinternals/blob/master/OutlookAPI.ps1"
    click OutlookAPIUtils "https://github.com/gerenios/aadinternals/blob/master/OutlookAPI_utils.ps1"
    click DCaaS "https://github.com/gerenios/aadinternals/blob/master/DCaaS.ps1"
    click DCaaSUtils "https://github.com/gerenios/aadinternals/blob/master/DCaaS_utils.ps1"
    click HybridHealth "https://github.com/gerenios/aadinternals/blob/master/HybridHealthServices.ps1"
    click HybridHealthUtils "https://github.com/gerenios/aadinternals/blob/master/HybridHealthServices_utils.ps1"
    click AzureMgmt "https://github.com/gerenios/aadinternals/blob/master/AzureManagementAPI.ps1"
    click AzureMgmtUtils "https://github.com/gerenios/aadinternals/blob/master/AzureManagementAPI_utils.ps1"
    click CommonUtils "https://github.com/gerenios/aadinternals/blob/master/CommonUtils.ps1"
    click ConfigJSON "https://github.com/gerenios/aadinternals/blob/master/config.json"
    click CertStore "https://github.com/gerenios/aadinternals/blob/master/any_sts.pfx"
    click ConfigPS "https://github.com/gerenios/aadinternals/blob/master/Configuration.ps1"
    click SDK_MIClient "https://github.com/gerenios/aadinternals/blob/master/Microsoft.Identity.Client.xml"
    click SDK_MIMod "https://github.com/gerenios/aadinternals/blob/master/Microsoft.IdentityModel.Abstractions.xml"
    click README "https://github.com/gerenios/aadinternals/blob/master/README.md"
    click LICENSE "https://github.com/gerenios/aadinternals/blob/master/LICENSE.md"

    %% Styles
    classDef module fill:#D0E6FF,stroke:#0366d6
    classDef util fill:#E6FDE6,stroke:#2c662d
    classDef config fill:#F0F0F0,stroke:#888888
    classDef external fill:#E6FFEA,stroke:#28A745
    classDef sdk fill:#FFE6CC,stroke:#CC8A00
    classDef doc fill:#FFF5CC,stroke:#CCCC00
```
