# startautomating/psdevops architecture

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

- Interactive diagram: https://gitdiagram.com/startautomating/psdevops
- Repository: https://github.com/startautomating/psdevops

## Overview

##### Project type and purpose
- PSDevOps is an open-source PowerShell module designed to simplify DevOps automation.
- It provides pipeline-aware cmdlets to wrap the Azure DevOps and GitHub REST APIs, custom formatting/type extensions, generation of CI/CD pipelines (Azure DevOps & GitHub), and publishing to the PowerShell Gallery.

##### File structure
- Top level: core module manifest (PSDevOps.psd1/psm1), helper scripts (PSDevOps.*.ps1), tests, CI definitions (azure-pipelines.yml, action.yml), documentation, and assets.
- Directories:
- Ado – pipeline “parts” (jobs, stages, steps, triggers) for Azure DevOps pipeline generation
- GitHub – analogous parts for GitHub Actions/Workflows
- Formatting – custom .format.ps1 scripts to control PowerShell table/list views
- Types – Extended Type System PS1/XML files to decorate returned objects
- Functions – functional implementation split by area: AzureDevOps, Git, GitHub, plus shared utilities (Convert-BuildStep, Expand-BuildStep, etc.)
- Parts – building-block scripts/metadata for pipeline-as-code
- docs – CLI reference and change logs
- CI/CD:
- .github/workflows and Ado/Workflows house pipelines for testing, linting (PSScriptAnalyzer, ScriptCop), cross-platform Pester tests, and publishing artifacts.

##### Extract architecture insights from README
- Core layers:
a. REST wrappers (Invoke-ADORestAPI, Invoke-GitHubRESTAPI)
b. Cmdlet layer (Get-ADO*, New-ADOPipeline, Connect-GitHub, New-GitHubAction, etc.)
c. Formatting & type extensions to augment API output
d. Pipeline-as-code engine (New-ADOPipeline, New-GitHubWorkflow) using “parts”
- Extensibility: modules can drop their own ADO/GitHub parts under an \ADO or \GitHub folder to override default parts.

##### Main components and interactions
a. User/PowerShell Host
- Imports PSDevOps module
- Invokes cmdlets
b. PSDevOps Module
- Function Layer (Functions folder)
- REST Adapter Layer (Invoke-ADORestAPI & Invoke-GitHubRESTAPI)
- Formatting/Types Layer (Formatting & Types folders)
- Pipeline-As-Code Engine (Parts, Ado, GitHub folders)
c. External Services
- Azure DevOps REST API
- GitHub REST API
- PowerShell Gallery (publishing module)
d. CI/CD Infrastructure
- Azure Pipelines (azure-pipelines.yml, Ado workflows)
- GitHub Actions (action.yml, .github/workflows)
e. Documentation Site
- docs folder → site generator (e.g., Jekyll) → GitHub Pages or similar

- Cmdlets → REST Adapter → External APIs
- Cmdlets → Formatting/Types → PowerShell Output
- New-ADOPipeline/New-GitHubWorkflow → Pipeline “parts” → CI definitions
- CI definitions → run linters/tests → publish to PowerShell Gallery
- docs folder → site generator → published documentation

##### Architectural patterns & design principles
- Layered architecture: separation of cmdlet logic, REST transport, formatting, and code-gen engine.
- Plugin/override mechanism: module–specific \ADO or \GitHub parts override core.
- Pipeline-aware functions: heavy use of PowerShell object pipeline & ShouldProcess pattern.
- CI/CD as code: all pipelines defined declaratively in the repo.

##### Don’t overthink—capture all logical components
- Break PSDevOps into as many meaningful pieces as possible: host, module layers, external APIs, CI, docs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["PowerShell Host\n(User)"]:::user

    %% PSDevOps Module
    subgraph "PSDevOps Module" 
        direction TB
        Manifest["Module Manifest"]:::internal
        subgraph "Function Layer" 
            direction TB
            FuncAzure["AzureDevOps Cmdlets"]:::internal
            FuncGit["Git Cmdlets"]:::internal
            FuncGitHub["GitHub Cmdlets"]:::internal
            SharedUtils["Shared Utilities"]:::internal
        end
        subgraph "REST Adapter Layer"
            direction TB
            ADORest["Invoke-ADORestAPI"]:::internal
            GHRest["Invoke-GitHubRESTAPI"]:::internal
        end
        subgraph "Formatting & Types Layer"
            direction TB
            Formatting["Formatting"]:::internal
            TypesLayer["Types"]:::internal
        end
        subgraph "Pipeline-As-Code Engine"
            direction TB
            Parts["Parts"]:::internal
            AdoParts["Ado Parts"]:::internal
            GHParts["GitHub Parts"]:::internal
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ADOApi["Azure DevOps REST API"]:::external
        GHApi["GitHub REST API"]:::external
        PSGallery["PowerShell Gallery"]:::external
    end

    %% CI/CD Infrastructure
    subgraph "CI/CD Infrastructure"
        direction TB
        AzurePipelines["Azure Pipelines"]:::ci
        GitHubActions["GitHub Actions"]:::ci
    end

    %% Documentation Pipeline
    subgraph "Documentation Pipeline"
        direction TB
        DocsSrc["docs Folder"]:::docs
        SiteGen["Site Generator"]:::docs
        PublishedDocs["Published Docs"]:::docs
    end

    %% Flows
    User -->|"Imports Module"| Manifest
    Manifest -->|"Loads Cmdlets"| FuncAzure
    Manifest --> FuncGit
    Manifest --> FuncGitHub
    Manifest --> SharedUtils

    FuncAzure -->|"calls"| ADORest
    FuncGitHub -->|"calls"| GHRest

    ADORest -->|"REST calls"| ADOApi
    GHRest -->|"REST calls"| GHApi

    FuncAzure -->|"outputs objects"| Formatting
    FuncGitHub --> Formatting
    FuncGit --> Formatting
    Formatting --> TypesLayer

    FuncAzure -->|"New-ADOPipeline"| AdoParts
    FuncGitHub -->|"New-GitHubWorkflow"| GHParts
    Parts --> AdoParts
    Parts --> GHParts

    AdoParts -->|"generates azure-pipelines.yml"| AzurePipelines
    GHParts -->|"generates action.yml & workflows"| GitHubActions

    AzurePipelines -->|"run tests & lint"| AzurePipelines
    GitHubActions -->|"run tests & lint"| GitHubActions

    AzurePipelines -->|"publish"| PSGallery
    GitHubActions -->|"publish"| PSGallery

    DocsSrc --> SiteGen
    SiteGen --> PublishedDocs

    %% Click Events
    click Manifest "https://github.com/startautomating/psdevops/blob/master/PSDevOps.psd1"
    click Manifest "https://github.com/startautomating/psdevops/blob/master/PSDevOps.psm1"
    click FuncAzure "https://github.com/startautomating/psdevops/tree/master/Functions/AzureDevOps/"
    click FuncGit "https://github.com/startautomating/psdevops/tree/master/Functions/Git/"
    click FuncGitHub "https://github.com/startautomating/psdevops/tree/master/Functions/GitHub/"
    click SharedUtils "https://github.com/startautomating/psdevops/blob/master/Functions/Convert-BuildStep.ps1"
    click SharedUtils "https://github.com/startautomating/psdevops/blob/master/Functions/Expand-BuildStep.ps1"
    click SharedUtils "https://github.com/startautomating/psdevops/blob/master/Functions/Get-BuildStep.ps1"
    click SharedUtils "https://github.com/startautomating/psdevops/blob/master/Functions/Import-BuildStep.ps1"
    click SharedUtils "https://github.com/startautomating/psdevops/blob/master/Functions/Get-PSDevOps.ps1"
    click ADORest "https://github.com/startautomating/psdevops/blob/master/Functions/AzureDevOps/Invoke-ADORestAPI.ps1"
    click GHRest "https://github.com/startautomating/psdevops/blob/master/Functions/GitHub/Invoke-GitHubRESTApi.ps1"
    click Formatting "https://github.com/startautomating/psdevops/tree/master/Formatting/"
    click TypesLayer "https://github.com/startautomating/psdevops/tree/master/Types/"
    click Parts "https://github.com/startautomating/psdevops/tree/master/Parts/"
    click AdoParts "https://github.com/startautomating/psdevops/tree/master/Ado/"
    click GHParts "https://github.com/startautomating/psdevops/tree/master/GitHub/"
    click AzurePipelines "https://github.com/startautomating/psdevops/blob/master/azure-pipelines.yml"
    click GitHubActions "https://github.com/startautomating/psdevops/blob/master/action.yml"
    click GitHubActions "https://github.com/startautomating/psdevops/blob/master/.github/workflows/TestAndPublish.yml"
    click GitHubActions "https://github.com/startautomating/psdevops/blob/master/.github/workflows/OnIssue.yml"
    click GitHubActions "https://github.com/startautomating/psdevops/blob/master/.github/workflows/TraceIssueClosed.yml"
    click GitHubActions "https://github.com/startautomating/psdevops/blob/master/.github/workflows/TraceIssueComment.yml"
    click GitHubActions "https://github.com/startautomating/psdevops/blob/master/.github/workflows/TraceIssueOpenedOrEdited.yml"
    click DocsSrc "https://github.com/startautomating/psdevops/tree/master/docs/"

    %% Styles
    classDef user fill:#ffffff,stroke:#000000,stroke-width:1px
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef ci fill:#FFA500,stroke:#333,stroke-width:1px
    classDef docs fill:#D8BFD8,stroke:#333,stroke-width:1px
```
