# microsoft/powerbi-powershell architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/powerbi-powershell
- Repository: https://github.com/microsoft/powerbi-powershell

## Overview

##### Project type and purpose
- This is a CLI/library project: a suite of PowerShell modules (`MicrosoftPowerBIMgmt.*`) implemented in C#/.NET Standard, published to the PowerShell Gallery.
- Purpose: provide PowerShell cmdlets that authenticate to and call the Power BI REST API for Admin, Capacities, Data, Profile, Reports, and Workspaces operations.

##### File structure
- Top-level “src” folder with:
- Common libraries:
– `Commands.Common` (base cmdlet abstractions, logging, configuration)
– `Common.Abstractions` (interfaces for auth, storage, logging, cmdlets)
– `Common.Api` (HTTP clients for each API surface: Workspaces, Datasets, Reports, etc.)
– `Common.Authentication` (implementations: DeviceCode, ServicePrincipal, Windows)
– `Common.Client` (PowerShell-specific cmdlet hosting and client factory)
– `Common.Dependencies` (NuGet-shipped dependencies)
- Modules (under `Modules/*/Commands.*`): Admin, Capacities, Data, Profile, Reports, Workspaces — each produces a separate PowerShell module.
- Build and packaging: `build`, `scripts`, `Directory.Build.*`, GitHub workflows, `examples`.

##### Core components
a. PowerShell Host
– Users issue cmdlets (e.g. `Get-PowerBIWorkspace`)
b. Module Layer
– Each module references:
- `Commands.Common` for base cmdlet behavior
- `Common.Client` for cmdlet‐level wiring
- `Common.Api` for API operations
- `Common.Authentication` to obtain tokens
c. Common Libraries
– Commands.Common
– Common.Abstractions
– Common.Client
d. HTTP/Network
– HttpClient
e. External Services
– Azure AD (token endpoint)
– Power BI REST API endpoints
f. Build & Packaging Tooling (side-panel)
– Scripts (Build.ps1, Test.ps1, PublishModules.ps1)
– GitHub Actions (CI/CD workflows)

##### Architectural patterns and principles
- Layered architecture: Host → Modules → Common libraries → External services
- Dependency Injection via factory interfaces in `Common.Abstractions`
- Single Responsibility: separate cmdlet implementation from HTTP/API code and from authentication
- Extensibility: new modules can reuse common libraries

##### Relevant technologies/frameworks
- .NET Standard (class libraries compiled to DLLs)
- PowerShell SDK (PSModule manifests `.psd1`, formatting `.ps1xml`)
- HttpClient & JSON serialization
- PowerShell Gallery publishing (NuGet.config, `.nuspec`, scripts)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% PowerShell Host
    subgraph "PowerShell Host"
        PSH["PowerShell Console / PowerShell Core"]:::host
    end

    %% Modules Layer
    subgraph "Modules"
        Admin["Admin Module"]:::module
        Capacities["Capacities Module"]:::module
        Data["Data Module"]:::module
        Profile["Profile Module"]:::module
        Reports["Reports Module"]:::module
        Workspaces["Workspaces Module"]:::module
    end

    %% Common Libraries
    subgraph "Common Libraries"
        CC["Commands.Common"]:::common
        CA["Common.Abstractions"]:::common
        Api["Common.Api"]:::common
        Auth["Common.Authentication"]:::common
        Client["Common.Client"]:::common
    end

    %% HTTP/Network Layer
    subgraph "HTTP/Network Layer"
        ApiClient["PowerBIApiClient"]:::network
        Handler["PowerBIHttpClientHandler"]:::network
        HttpClient["HttpClient"]:::network
    end

    %% External Services
    subgraph "External Services"
        AAD["Azure AD Token Endpoint"]:::external
        PowerBI["Power BI REST API"]:::external
    end

    %% Build & Packaging Tooling
    subgraph "Build & Packaging Tooling"
        Scripts["Build & Publish Scripts"]:::tooling
        CI["GitHub Actions Workflows"]:::tooling
        Examples["Examples / Samples"]:::tooling
    end

    %% Relationships
    PSH -->|"Invoke Cmdlet"| Admin
    PSH -->|"Invoke Cmdlet"| Capacities
    PSH -->|"Invoke Cmdlet"| Data
    PSH -->|"Invoke Cmdlet"| Profile
    PSH -->|"Invoke Cmdlet"| Reports
    PSH -->|"Invoke Cmdlet"| Workspaces

    Admin -->|"uses"| CC
    Admin -->|"uses"| Client
    Admin -->|"uses"| Api
    Admin -->|"uses"| Auth

    Capacities -->|"uses"| CC
    Capacities -->|"uses"| Client
    Capacities -->|"uses"| Api
    Capacities -->|"uses"| Auth

    Data -->|"uses"| CC
    Data -->|"uses"| Client
    Data -->|"uses"| Api
    Data -->|"uses"| Auth

    Profile -->|"uses"| CC
    Profile -->|"uses"| Client
    Profile -->|"uses"| Api
    Profile -->|"uses"| Auth

    Reports -->|"uses"| CC
    Reports -->|"uses"| Client
    Reports -->|"uses"| Api
    Reports -->|"uses"| Auth

    Workspaces -->|"uses"| CC
    Workspaces -->|"uses"| Client
    Workspaces -->|"uses"| Api
    Workspaces -->|"uses"| Auth

    CC -->|"depends on"| CA
    Api -->|"implements clients"| CA

    Api -->|"calls"| ApiClient
    ApiClient -->|"HTTP calls via"| HttpClient
    HttpClient -->|"handler"| Handler
    HttpClient -->|"sends request to"| PowerBI

    Auth -->|"Acquire Token"| AAD

    PowerBI -->|"returns JSON"| Api
    Api -->|"deserialize"| Admin
    Api -->|"deserialize"| Capacities
    Api -->|"deserialize"| Data
    Api -->|"deserialize"| Profile
    Api -->|"deserialize"| Reports
    Api -->|"deserialize"| Workspaces
    Admin -->|"returns PSObject"| PSH
    Capacities -->|"returns PSObject"| PSH
    Data -->|"returns PSObject"| PSH
    Profile -->|"returns PSObject"| PSH
    Reports -->|"returns PSObject"| PSH
    Workspaces -->|"returns PSObject"| PSH

    Scripts -->|"build & publish"| Modules
    CI -->|"CI/CD pipeline"| Modules
    Examples -->|"sample usage"| PSH

    %% Click Events
    click Admin "https://github.com/microsoft/powerbi-powershell/blob/master/src/Modules/Admin/Commands.Admin"
    click Capacities "https://github.com/microsoft/powerbi-powershell/blob/master/src/Modules/Capacities/Commands.Capacities"
    click Data "https://github.com/microsoft/powerbi-powershell/blob/master/src/Modules/Data/Commands.Data"
    click Profile "https://github.com/microsoft/powerbi-powershell/blob/master/src/Modules/Profile/Commands.Profile"
    click Reports "https://github.com/microsoft/powerbi-powershell/blob/master/src/Modules/Reports/Commands.Reports"
    click Workspaces "https://github.com/microsoft/powerbi-powershell/blob/master/src/Modules/Workspaces/Commands.Workspaces"
    click CC "https://github.com/microsoft/powerbi-powershell/blob/master/src/Common/Commands.Common"
    click CA "https://github.com/microsoft/powerbi-powershell/blob/master/src/Common/Common.Abstractions"
    click Api "https://github.com/microsoft/powerbi-powershell/blob/master/src/Common/Common.Api"
    click Auth "https://github.com/microsoft/powerbi-powershell/blob/master/src/Common/Common.Authentication"
    click Client "https://github.com/microsoft/powerbi-powershell/blob/master/src/Common/Common.Client"
    click ApiClient "https://github.com/microsoft/powerbi-powershell/blob/master/src/Common/Common.Api/PowerBIApiClient.cs"
    click Handler "https://github.com/microsoft/powerbi-powershell/blob/master/src/Common/Common.Client/PowerBIHttpClientHandler.cs"
    click Scripts "https://github.com/microsoft/powerbi-powershell/blob/master/scripts/Build.ps1"
    click CI "https://github.com/microsoft/powerbi-powershell/blob/master/.github/workflows/codeql.yml"
    click Examples "https://github.com/microsoft/powerbi-powershell/tree/master/examples/"

    %% Styles
    classDef module fill:#8ecae6,stroke:#023047,color:#023047
    classDef common fill:#a8dadc,stroke:#457b9d,color:#1d3557
    classDef network fill:#ffb703,stroke:#fb8500,color:#5f370e
    classDef external fill:#ffd166,stroke:#f4a261,color:#9c4221
    classDef tooling fill:#adb5bd,stroke:#6c757d,color:#343a40
    classDef host fill:#bde0fe,stroke:#219ebc,color:#023047
```
