# pnp/script-samples architecture

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

- Interactive diagram: https://gitdiagram.com/pnp/script-samples
- Repository: https://github.com/pnp/script-samples

## Overview

##### Project type and purpose
- This is a sample-script monorepo and documentation site for “PnP Script Samples.”
- It hosts 300+ PowerShell/CLI/Graph SDK script examples, generates static docs via DocFX, and deploys them (e.g., to GitHub Pages or another static-hosting endpoint).

##### File structure
Top-level:
- .devcontainer/  – VS Code dev container Dockerfile & scripts
- .github/workflows/ – CI/CD pipeline definitions
- docfx/ – DocFX config, templates, assets, scripts for static site generation
- scripts/ – Hundreds of sample subfolders; each contains PowerShell/JSON/assets and its own README
- README.md, LICENSE, .gitignore, .tours (onboarding tours), New-Sample.ps1

Key patterns:
- “scripts/…” – Each scenario is an independent component (PowerShell module + sample JSON + docs)
- “docfx/…” – Static site generator orchestrator (metadata, content, templates, build scripts)
- CI/CD via GitHub Actions: triggers docfx-generate and deploy workflows
- Devcontainer sets up local dev sandbox with Docker + VS Code for editing, testing DocFX builds

##### README for additional insights
- Purpose is to showcase real-world PnP/PowerShell/CLI samples
- Primary UX is the static website at https://pnp.github.io/script-samples
- Contributions process described; site supports filtering/navigation

a. Main components
1. Developer Local Environment
– VS Code + Devcontainer (Docker).
– Edits “scripts/” and “docfx/” content.
2. Version Control & CI/CD
– GitHub repo.
– Workflows (.github/workflows/docfx-generate.yml, takeaction.yml).
3. Static Site Generator
– DocFX engine (docfx.exe invoked by build.ps1).
– Uses docfx.json, templates, markdown includes, assets to produce docs.
4. Artifact Storage & Hosting
– Built static site files (HTML/CSS/JS) reside in docfx/_site or commit to gh-pages.
– Hosted on GitHub Pages or Azure Static Web Apps (via workflow).
5. End Users
– Browser requests static content; sees navigation, script details, samples.

b. Relationships & interactions
– Dev → Push to GitHub → triggers CI workflows
– CI: fetch repo → run DocFX build → produce static assets → deploy to hosting
– Browser ← HTTP GET ← Hosted site → static assets served
– Scripts folder feeds into DocFX pipeline as content modules

c. Architectural patterns & design principles
– Monorepo: all scripts + docs in one repo
– Static site generator pattern (content + templates → build → static output)
– CI/CD pipeline as code in GitHub Actions
– Devcontainer for reproducible local environment

d. Relevant technologies
– PowerShell scripts (samples)
– DocFX (static site generator)
– GitHub Actions
– Docker (devcontainer)
– Markdown, JSON assets, HTML/CSS templates

##### Elements
- Blue for developer/local
- Orange for CI/CD
- Green for static generator
- Gray for hosting
- Purple for user/client
- Rectangles for processes (DocFX build, Docker container)
- Clouds for hosting/web

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Environment
    subgraph "Developer Environment"
        DevEnv["VS Code + Devcontainer"]:::developer
    end
    click DevEnv "https://github.com/pnp/script-samples/tree/main/.devcontainer/"

    %% Source Repository
    subgraph "Source Repository"
        RepoScripts["Scripts Library\n(scripts/)"]:::developer
        click RepoScripts "https://github.com/pnp/script-samples/tree/main/scripts/"
        RepoWorkflows1["GitHub Actions\n(docfx-generate.yml)"]:::ci
        click RepoWorkflows1 "https://github.com/pnp/script-samples/blob/main/.github/workflows/docfx-generate.yml"
        RepoWorkflows2["GitHub Actions\n(takeaction.yml)"]:::ci
        click RepoWorkflows2 "https://github.com/pnp/script-samples/blob/main/.github/workflows/takeaction.yml"
        DocfxConfig["docfx.json"]:::gen
        click DocfxConfig "https://github.com/pnp/script-samples/blob/main/docfx/docfx.json"
        BuildPS["build.ps1"]:::gen
        click BuildPS "https://github.com/pnp/script-samples/blob/main/docfx/build.ps1"
        LocalBuild["docfx-build-local.ps1"]:::gen
        click LocalBuild "https://github.com/pnp/script-samples/blob/main/docfx/docfx-build-local.ps1"
        Templates["Templates"]:::gen
        click Templates "https://github.com/pnp/script-samples/tree/main/docfx/templates/"
        Assets["Assets"]:::gen
        click Assets "https://github.com/pnp/script-samples/tree/main/docfx/assets/"
        Plugins["Plugins"]:::gen
        click Plugins "https://github.com/pnp/script-samples/tree/main/docfx/plugins/"
        HelpJson["Get-HelpJson.ps1"]:::gen
        click HelpJson "https://github.com/pnp/script-samples/blob/main/docfx/Get-HelpJson.ps1"
        SamplesJson["generate-samplesJson.ps1"]:::gen
        click SamplesJson "https://github.com/pnp/script-samples/blob/main/docfx/generate-samplesJson.ps1"
        ScriptsDownload["get-scriptsfordownload.ps1"]:::gen
        click ScriptsDownload "https://github.com/pnp/script-samples/blob/main/docfx/get-scriptsfordownload.ps1"
        Toc["toc.yml"]:::gen
        click Toc "https://github.com/pnp/script-samples/blob/main/docfx/toc.yml"
        Includes["Includes & Markdown"]:::gen
        click Includes "https://github.com/pnp/script-samples/tree/main/docfx/includes/"
        NewSample["New-Sample.ps1"]:::developer
        click NewSample "https://github.com/pnp/script-samples/blob/main/New-Sample.ps1"
        Tours["Onboarding Tours"]:::developer
        click Tours "https://github.com/pnp/script-samples/tree/main/.tours/"
    end

    %% CI/CD
    subgraph "CI/CD Pipeline" 
        CI["GitHub Actions Runner"]:::ci
    end

    %% Static Site Generator
    subgraph "Static Site Generator"
        DocFX["DocFX Engine"]:::gen
        Artifacts["Static Site Artifacts\n(docfx/_site)"]:::host
    end

    %% Hosting
    subgraph "Hosting"
        Pages["GitHub Pages / Azure Static"]:::host
    end

    %% End Users
    subgraph "End Users"
        Browser["Web Browser"]:::user
    end

    %% Flow
    DevEnv -->|"edit & commit"| RepoScripts
    DevEnv --> RepoWorkflows1
    DevEnv --> RepoWorkflows2
    RepoScripts -->|content| DocFX
    DocfxConfig --> DocFX
    BuildPS --> DocFX
    LocalBuild --> DocFX
    Templates --> DocFX
    Assets --> DocFX
    Plugins --> DocFX
    HelpJson --> DocFX
    SamplesJson --> DocFX
    ScriptsDownload --> DocFX
    Toc --> DocFX
    Includes --> DocFX
    NewSample --> RepoScripts
    Tours --> Includes

    RepoWorkflows1 -->|on push| CI
    RepoWorkflows2 --> CI
    CI -->|run build| DocFX
    DocFX -->|generate| Artifacts
    Artifacts -->|deploy| Pages
    Browser -->|HTTP GET| Pages

    %% Styles
    classDef developer fill:#ccf,stroke:#888;
    classDef ci fill:#f96,stroke:#f60;
    classDef gen fill:#9f6,stroke:#484;
    classDef host fill:#ccc,stroke:#666;
    classDef user fill:#c9f,stroke:#84c;
```
