# pspete/pspas architecture

> Architecture diagram of the GitHub repository pspete/pspas, 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/pspete/pspas
- Repository: https://github.com/pspete/pspas

## Overview

##### Project Type & Purpose
- This is an open-source PowerShell module (“psPAS”) that wraps the CyberArk PVWA REST API, exposing all API capabilities (up to v14.0) as PowerShell cmdlets.
- It provides authentication (multiple flows), account management, safe and policy operations, PSM session control, PTA rules, etc., for automation in PowerShell.

##### File Structure Analysis
- Top-level:
- psPAS/ – the PowerShell module code:
– psPAS.psd1 & psPAS.psm1 (module manifest & entry)
– Functions/ (public cmdlet implementations, organized by domain: Authentication, Accounts, Safes…)
– Private/ (internal helpers: HTTP calls, JSON processing, version checks)
– xml/ (PowerShell formatting & type definitions)
– en-US/ (help XML)
- Tests/ – a large suite of Pester-style .ps1 tests, one per cmdlet
- build/ – build & deployment scripts (test, package, deploy to PSGallery & GitHub)
- docs/ – Jekyll website source for documentation
- CI/CD & deployment:
– appveyor.yml invokes build/test scripts
– build/deploy-github.ps1 publishes docs to GitHub Pages
– build/deploy-psgallery.ps1 pushes module to PowerShell Gallery

##### Key Components
a. User & Host:
– PowerShell Console/Script invokes psPAS cmdlets
b. psPAS Module Layers:
1) Public Cmdlets (Functions/)
2) Private Helpers (Private/) – HTTP/REST wrapper, parameter conversion, version checks
3) Type & Format Definitions (xml/)
c. External Systems:
– CyberArk PVWA REST API (HTTPS endpoints)
– CI/CD Services: AppVeyor, GitHub Actions (build/test)
– PowerShell Gallery (module publishing)
– GitHub Pages (docs hosting via Jekyll)
d. Testing:
– Tests/ – Pester tests invoking Public Cmdlets against a mock or real API during CI
e. Documentation Pipeline:
– docs/ site source → Jekyll build → GitHub Pages

##### Relationships & Data Flows
- PowerShell Console → loads psPAS.psm1 → exposes Public Cmdlets
- Public Cmdlets → call Private Helpers → execute Invoke-PASRestMethod → send HTTPS request → CyberArk PVWA
- PVWA → returns JSON → Private Helpers parse JSON → convert to PSObjects → returned to user
- Tests invoke Public Cmdlets → validate behavior (mock or live API)
- CI (AppVeyor) triggers build.ps1 → runs tests → on success deploys artifacts:
- Module → PowerShell Gallery
- docs/ → GitHub Pages

##### Architectural Patterns & Principles
- Modular design: commands organized by functional domain
- Separation of concerns: Public interface (cmdlets) vs Private utilities vs type/format definitions
- Declarative manifest (psd1/psm1) to manage module loading
- CI/CD pipelines automated via scripts
- Static site generation for docs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% PowerShell Runtime Flow (Blue)
    subgraph "PowerShell Runtime"
        direction TB
        PSHost("PowerShell Host"):::external
        PSD1("psPAS.psd1"):::module
        PSM1("psPAS.psm1"):::module
        subgraph "psPAS Module"
            direction TB
            PSD1 --> PSM1
            subgraph "Public Cmdlets (Functions/)"
                direction TB
                Auth("Authentication"):::public
                Accounts("Accounts"):::public
                Safes("Safes & SafeMembers"):::public
                Policy("Policy ACLs"):::public
                Monitoring("PSM Sessions & Monitoring"):::public
                EventSec("Event Security (PTA Rules)"):::public
                Others("Other Domains"):::public
            end
            subgraph "Private Helpers (Private/)"
                direction TB
                Helpers("Invoke-PASRestMethod & Utilities"):::private
            end
            Types("Type & Format XML"):::xml
        end
        PSHost -->|"loads module"| PSM1
        PSM1 -->|"exposes cmdlets"| Auth
        Auth -->|"calls REST wrapper"| Helpers
        Accounts --> Helpers
        Safes --> Helpers
        Policy --> Helpers
        Monitoring --> Helpers
        EventSec --> Helpers
        Others --> Helpers
        Helpers -->|"HTTPS request"| API
        API("CyberArk PVWA REST API"):::api
        API -->|"JSON response"| Helpers
        Helpers -->|"PSObjects"| Auth
    end

    %% CI/CD Pipeline (Green)
    subgraph "CI/CD Pipeline"
        direction TB
        AppVeyor("AppVeyor (CI)"):::ci
        build("build/build.ps1 & test.ps1"):::ci
        Tests("Tests Suite"):::tests
        AppVeyor -->|"triggers build"| build
        build -->|"runs tests"| Tests
        build -->|"deploy module"| PSGallery("PowerShell Gallery"):::service
        build -->|"deploy docs"| GHPages("GitHub Pages"):::service
    end

    %% Documentation Pipeline (Gray)
    subgraph "Documentation Pipeline"
        direction TB
        DocsSrc("docs/ Jekyll Source"):::docs
        Jekyll("Jekyll Build"):::docs
        DocsSrc --> Jekyll
        Jekyll --> GHPages
    end

    %% Click Events
    click PSD1 "https://github.com/pspete/pspas/blob/master/psPAS/psPAS.psd1"
    click PSM1 "https://github.com/pspete/pspas/blob/master/psPAS/psPAS.psm1"
    click Auth "https://github.com/pspete/pspas/tree/master/psPAS/Functions/Authentication/"
    click Accounts "https://github.com/pspete/pspas/tree/master/psPAS/Functions/Accounts/"
    click Safes "https://github.com/pspete/pspas/tree/master/psPAS/Functions/Safes/"
    click Helpers "https://github.com/pspete/pspas/blob/master/psPAS/Private/Invoke-PASRestMethod.ps1"
    click Types "https://github.com/pspete/pspas/tree/master/psPAS/xml/"
    click Tests "https://github.com/pspete/pspas/tree/master/Tests/"
    click build "https://github.com/pspete/pspas/blob/master/build/build.ps1"
    click AppVeyor "https://github.com/pspete/pspas/blob/master/appveyor.yml"
    click DocsSrc "https://github.com/pspete/pspas/tree/master/docs/"

    %% Styles
    classDef external fill:#D0E6FF,stroke:#0074D9,stroke-width:1px
    classDef module fill:#CCE5FF,stroke:#005BB5,stroke-width:1px
    classDef public fill:#B3D7FF,stroke:#00529B,stroke-width:1px
    classDef private fill:#DFF0D8,stroke:#3C763D,stroke-width:1px
    classDef xml fill:#FCF8E3,stroke:#8A6D3B,stroke-width:1px
    classDef api fill:#E0FFFF,stroke:#20B2AA,stroke-dasharray:5 5
    classDef ci fill:#DFF2BF,stroke:#4F8A10,stroke-width:1px
    classDef tests fill:#FEEFB3,stroke:#9F6000,stroke-width:1px
    classDef service fill:#F2F2F2,stroke:#919191,stroke-width:1px
    classDef docs fill:#EEEEEE,stroke:#AAAAAA,stroke-width:1px
```
