# paulpalayur/wpmexport architecture

> Architecture diagram of the GitHub repository paulpalayur/wpmexport, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paulpalayur/wpmexport
- Repository: https://github.com/paulpalayur/wpmexport

## Overview

##### What this project is (type + purpose)
This repo is a **PowerShell-based export utility** (“wpmexport”) that runs as a **local script/CLI**. Its purpose is to **export a user’s personal WPM objects** (notably **Secured Items** and **Web Apps**) by authenticating against an **Identity tenant** (including shared services tenants and federated users), calling the relevant remote APIs, and writing results to a local **`export.csv`**.

From the tree and README, the architecture is not a multi-service app; it’s a **script orchestrator + an authentication module + remote SaaS APIs + local file output**.

##### How to read the file structure (what maps to “components”)

- **`Export-WPM.ps1`**
- The main entrypoint (orchestrator). Prompts for:
- Identity Tenant Id
- Identity User Name
- subdomain
- Then likely:
- acquires tokens via the Identity Authentication module
- calls WPM/Identity endpoints to list/export objects
- transforms results
- writes `export.csv`

- **`Identity Authentication/IdentityAuth.psm1`**
- A reusable **PowerShell module** (component) responsible for:
- authentication flows
- token acquisition/refresh
- handling federated/shared-services nuances

- **`Identity Authentication/IdentityRefresh.ps1`** and **`IdentityRefresh_5.1.ps1`**
- Ancillary scripts for refreshing tokens / compatibility (notably Windows PowerShell 5.1 vs newer PowerShell).
- These should appear as either:
- “supporting utilities” called by the module, or
- “alternate execution paths” depending on runtime version.

- **`Identity Authentication/README.md`**

- **Repo `README.md`**
- Defines external behavior: exports secured items + web apps (owned and some shared without creds) and outputs `export.csv`.

##### PowerShell Runtime
- Optionally split:
- PowerShell 7+ (pwsh)
- Windows PowerShell 5.1 (because there’s a `*_5.1.ps1` refresh script)
##### Token refresh helpers
- `IdentityRefresh.ps1`
- `IdentityRefresh_5.1.ps1`
##### CSV Writer / Local File System
- Output: `export.csv` in script directory

##### Identity Service (Tenant)
- **Federation/IdP** as a sub-component if the IdentityAuth README indicates a federated flow (e.g., SAML redirect/ADFS/Azure AD)
##### WPM Service APIs
- Secured Items API
- Web Apps API (owned)
- Web Apps API (shared-by-admin without credentials)
- Even if they’re the same host, splitting by resource makes the flows explicit.

##### User → Export-WPM.ps1
- Inputs: Tenant Id, Username, Subdomain
##### Export-WPM.ps1 → IdentityAuth.psm1
- “Authenticate / Acquire Access Token”
##### Identity Service → IdentityAuth.psm1
- Returns: access token / refresh token / session info
##### Export-WPM.ps1 → WPM APIs
- Uses token to call:
- “List Secured Items (owned)”
- “List Web Apps (owned)”
- “List Web Apps (shared, no credentials)”
##### WPM APIs → Export-WPM.ps1
- Returns: JSON payloads / objects
##### Export-WPM.ps1 → CSV Writer / File System
- Transforms objects → `export.csv`

- **Export-WPM.ps1 → IdentityAuth.psm1 → IdentityRefresh*.ps1 → Identity Service**
- “Refresh token” or “re-auth”
- Use a conditional note:
- “If running on Windows PowerShell 5.1, use IdentityRefresh_5.1.ps1; else IdentityRefresh.ps1”

##### Architectural patterns / design principles to highlight
Even though it’s “just a script”, it still has clear architecture:

- **Orchestrator + Module separation**
- `Export-WPM.ps1` is the workflow coordinator.
- `IdentityAuth.psm1` encapsulates auth complexity (federated/shared services support).
- **Externalized configuration via prompts**
- Tenant Id, username, subdomain are runtime-provided inputs.
- **API-integration tool**
- Main complexity is in **auth + API calls + data transformation**.
- **Compatibility branching**
- Separate refresh logic for PowerShell 5.1 indicates runtime-dependent behavior; call this out explicitly.

##### Components and labels
- `export.csv` (artifact/output)

##### Trust boundaries / zones (important here)
- “Local workstation (user-controlled)” vs “Cloud tenant/services”
This makes the security posture clear: tokens cross the boundary; CSV stays local.

##### Minimal “component inventory” checklist (don’t miss these)
- [ ] Entry point: `Export-WPM.ps1`
- [ ] Auth module: `IdentityAuth.psm1`
- [ ] Refresh scripts, including the 5.1 variant
- [ ] Identity tenant endpoints (and optional federated IdP)
- [ ] WPM APIs split by exported object type
- [ ] Output artifact: `export.csv`
- [ ] Runtime environment: PowerShell (note 5.1 compatibility path)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1: Context/Container (Vertical)
  %% =========================
  subgraph D1["Diagram 1: Context / Container (C4-style)"]
    direction TB

    U["User / Operator"]:::person

    subgraph WS["Local Workstation (User-controlled)"]
      direction TB

      PS["PowerShell Runtime"]:::runtime
      PS51["Windows PowerShell 5.1"]:::runtime
      PS7["PowerShell 7+ (pwsh)"]:::runtime

      DOCROOT["Project README (Usage)"]:::doc

      ORCH["Export-WPM.ps1 (Orchestrator / CLI)"]:::local
      AUTH["IdentityAuth.psm1 (Identity Authentication Module)"]:::local

      subgraph REF["Token Refresh Helpers"]
        direction TB
        REFNEW["IdentityRefresh.ps1 (Refresh helper)"]:::local
        REF51["IdentityRefresh_5.1.ps1 (5.1 refresh helper)"]:::local
      end

      FS["Local File System"]:::storage
      CSV["export.csv (Output)"]:::artifact
    end

    subgraph CLOUD["Cloud Services (Tenant / SaaS)"]
      direction TB

      ID["Identity Service (Tenant)"]:::external
      IDP["Federated IdP (Optional)"]:::external

      subgraph WPM["WPM Cloud Service APIs"]
        direction TB
        WPMSEC["Secured Items API (owned)"]:::external
        WPMOWN["Web Apps API (owned)"]:::external
        WPMSH["Web Apps API (shared by admins, no credentials)"]:::external
      end
    end

    %% Primary flow
    U -->|"inputs:TenantId+Username+Subdomain"| ORCH
    ORCH -.->|"loads/imports"| AUTH
    ORCH -->|"authenticate/acquireToken"| AUTH
    AUTH -->|"auth:OAuth/SAML(federated)|tenantId+subdomain"| ID
    ID -->|"returns:accessToken/refreshToken"| AUTH
    AUTH -->|"returns:accessToken"| ORCH

    ORCH -->|"GET:listSecuredItems(bearer)"| WPMSEC
    ORCH -->|"GET:listWebAppsOwned(bearer)"| WPMOWN
    ORCH -->|"GET:listWebAppsSharedNoCreds(bearer)"| WPMSH

    WPMSEC -->|"JSON objects"| ORCH
    WPMOWN -->|"JSON objects"| ORCH
    WPMSH -->|"JSON objects"| ORCH

    ORCH -->|"transform->CSV"| FS
    FS -->|"write"| CSV

    %% Token refresh path (high level)
    ORCH -->|"ifTokenExpired:refreshOrReauth"| AUTH
    AUTH -->|"invokeRefreshHelper"| REFNEW
    AUTH -->|"invokeRefreshHelper(PS5.1)"| REF51
    REFNEW -->|"refreshToken"| ID
    REF51 -->|"refreshToken"| ID

    %% Federation relationship
    ID -.->|"federationRedirect/validation(optional)"| IDP

    %% Notes
    N1["Note:Identity supports shared-services tenants + federated users"]:::note
    AUTH --- N1

    N2["Note:Compatibility branch: use IdentityRefresh_5.1.ps1 on Windows PowerShell 5.1; otherwise IdentityRefresh.ps1"]:::note
    REF --- N2

    %% Runtime association
    PS -->|"either"| PS51
    PS -->|"either"| PS7
    PS51 -->|"runs"| ORCH
    PS7 -->|"runs"| ORCH
    ORCH -->|"runsWithin"| PS
  end

  %% =========================
  %% Diagram 2: Sequence (Vertical)
  %% =========================
  subgraph D2["Diagram 2: Sequence (Auth + Export + Conditional Refresh)"]
    direction TB

    SUSER["User"]:::person
    SORCH["Export-WPM.ps1"]:::local
    SAUTH["IdentityAuth.psm1"]:::local
    SREFNEW["IdentityRefresh.ps1"]:::local
    SREF51["IdentityRefresh_5.1.ps1"]:::local
    SID["Identity Service"]:::external
    SWPM["WPM APIs (Secured Items + Web Apps)"]:::external
    SFS["Local File System"]:::storage
    SCSV["export.csv"]:::artifact

    SUSER -->|"enter:TenantId+Username+Subdomain"| SORCH
    SORCH -->|"authenticate() acquireToken"| SAUTH
    SAUTH -->|"requestTokens(tenantId,subdomain,username)"| SID
    SID -->|"accessToken(+refreshToken)"| SAUTH
    SAUTH -->|"accessToken"| SORCH

    D2ALT1{"tokenValid?"}:::decision
    SORCH --> D2ALT1

    D2ALT1 -->|"yes"| D2CALLS["callWpmApis()"]:::step
    D2CALLS -->|"GET securedItems/webApps(bearer)"| SWPM
    SWPM -->|"payloads(JSON)"| SORCH
    SORCH -->|"transformToCsv()"| SFS
    SFS -->|"write"| SCSV

    D2ALT1 -->|"no:expired"| D2REF{"runtimeIsPS5.1?"}:::decision

    D2REF -->|"no"| SREFNEW
    SAUTH -->|"invokeRefresh()"| SREFNEW
    SREFNEW -->|"refreshToken()"| SID
    SID -->|"newAccessToken"| SREFNEW
    SREFNEW -->|"newAccessToken"| SAUTH
    SAUTH -->|"newAccessToken"| SORCH
    SORCH -->|"retryCalls()"| SWPM
    SWPM -->|"payloads(JSON)"| SORCH
    SORCH -->|"writeCsv()"| SFS
    SFS -->|"write"| SCSV

    D2REF -->|"yes"| SREF51
    SAUTH -->|"invokeRefresh(PS5.1)"| SREF51
    SREF51 -->|"refreshToken()"| SID
    SID -->|"newAccessToken"| SREF51
    SREF51 -->|"newAccessToken"| SAUTH
    SAUTH -->|"newAccessToken"| SORCH
    SORCH -->|"retryCalls()"| SWPM
    SWPM -->|"payloads(JSON)"| SORCH
    SORCH -->|"writeCsv()"| SFS
    SFS -->|"write"| SCSV
  end

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click ORCH "https://github.com/paulpalayur/wpmexport/blob/main/Export-WPM.ps1"
  click AUTH "https://github.com/paulpalayur/wpmexport/blob/main/Identity Authentication/IdentityAuth.psm1"
  click REFNEW "https://github.com/paulpalayur/wpmexport/blob/main/Identity Authentication/IdentityRefresh.ps1"
  click REF51 "https://github.com/paulpalayur/wpmexport/blob/main/Identity Authentication/IdentityRefresh_5.1.ps1"
  click DOCROOT "https://github.com/paulpalayur/wpmexport/blob/main/README.md"
  click N1 "https://github.com/paulpalayur/wpmexport/blob/main/Identity Authentication/README.md"

  %% =========================
  %% Styles
  %% =========================
  classDef local fill:#2563EB,stroke:#0B2A6F,color:#FFFFFF,stroke-width:1px
  classDef external fill:#F59E0B,stroke:#8A4B00,color:#111827,stroke-width:1px
  classDef storage fill:#6B7280,stroke:#374151,color:#FFFFFF,stroke-width:1px
  classDef artifact fill:#9CA3AF,stroke:#374151,color:#111827,stroke-width:1px
  classDef runtime fill:#1D4ED8,stroke:#0B2A6F,color:#FFFFFF,stroke-width:1px
  classDef person fill:#10B981,stroke:#065F46,color:#06281F,stroke-width:1px
  classDef note fill:#FEF3C7,stroke:#D97706,color:#111827,stroke-width:1px
  classDef decision fill:#FDE68A,stroke:#B45309,color:#111827,stroke-width:1px
  classDef doc fill:#A78BFA,stroke:#5B21B6,color:#111827,stroke-width:1px
  classDef step fill:#38BDF8,stroke:#075985,color:#111827,stroke-width:1px
```
