# darkoperator/posh-ssh architecture

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

- Interactive diagram: https://gitdiagram.com/darkoperator/posh-ssh
- Repository: https://github.com/darkoperator/posh-ssh

## Overview

##### Project type and purpose
- This is an open-source PowerShell module (“Posh-SSH”) that wraps a custom build of the SSH.NET library to provide SSH, SCP and SFTP cmdlets in PowerShell.
- It targets PowerShell 5.1 and 7.x on Windows, and via .NET Standard also runs on Linux and Mac.
- It is organized as a reusable .NET Standard library (PoshSSH.Core) plus a PowerShell module (.psm1, help files, format definitions, documentation).

##### File-structure overview and architectural insights
- Top-level directories:
– Posh-SSH/ (PowerShell module contents: .psd1 manifest, .psm1 implementation, XML format files, help files, en-US help folder)
– Source/PoshSSH/PoshSSH.Core (C# .NET Standard library housing core SSH logic)
– Source/PoshSSH/PoshSSH (C# sources defining PowerShell cmdlet classes, session objects, stores)
– docs/ (markdown documentation for each cmdlet)
– tests/ (Pester or PowerShell test scripts for core cmdlets)
- Key configuration files:
– Posh-SSH.psd1 (module manifest)
– Posh-SSH.psm1 (module entry point, exports functions)
– packages.config (SSH.NET dependency)
– launchSettings.json (development debug settings for Core library)
- Architectural patterns:
– Separation of concerns: PowerShell-specific plumbing in the module, core SSH and file-transfer logic in the .NET Standard library.
– Strategy/Factory for different “Stores” (JsonStore, MemoryStore, OpenSSHStore) implementing IStore.
– Cmdlet classes map one-to-one with user-facing commands (Get-SSHSession, New-SFTPSession, etc.).

##### Main components and their relationships
- PowerShell Host (CLI or script)
→ invokes exported Cmdlets in Posh-SSH.psm1
- Posh-SSH PowerShell module
→ loads PoshSSH.Core assembly
→ cmdlet classes instantiate SessionObject, ConnectionInfoGenerator, OperationProgressHelper
→ use IStore implementations to read/write known-hosts or session credentials
- PoshSSH.Core (.NET Standard)
→ wraps SSH.NET library calls (Renci.SshNet) for SSH session establishment, file operations, port forwarding
→ exposes high-level methods (Connect, DownloadFile, UploadDirectory, InvokeCommand, ForwardPort)
- External dependency:
→ SSH.NET library (Renci.SshNet.dll) as the low-level SSH protocol engine
- Data flow:
PowerShell cmdlet call → Core API → SSH.NET → Remote SSH server
- Persistence flows:
Core uses IStore to load or save known-hosts in JSON, OpenSSH format or in-memory.

##### Architectural patterns and design principles
- Layered design: Separation between shell-specific layer and core networking logic.
- Dependency inversion: Cmdlets depend on interfaces (IStore) and abstract core services.
- Single responsibility: Each cmdlet focuses on one SSH/SFTP/SCP/port-forward operation.
- Extensibility: New stores or session types can be added by implementing IStore or by adding new cmdlet classes.

##### Detailed capture
- Module manifest loading step and format file usage for output formatting
- Call out test harness as a side‐component invoking PowerShell against module for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% PowerShell Layer
    subgraph "PowerShell Layer" 
        direction TB
        PSHost["PowerShell Host (CLI/Script)"]:::powershell
        subgraph "Posh-SSH Module" 
            direction TB
            Manifest["Posh-SSH.psd1"]:::powershell
            PSM1["Posh-SSH.psm1"]:::powershell
            Formats["Format Files (*.ps1xml)"]:::powershell
            HelpFiles["Help Files (en-US/*.xml)"]:::powershell
            AddIdentity["Add-SshIdentity.ps1"]:::powershell
        end
        PSHost -->|"invokes cmdlets"| Manifest
        Manifest --> PSM1
    end

    %% Core Layer
    subgraph "Core Library Layer" 
        direction TB
        subgraph "PoshSSH.Core Library" 
            direction TB
            CoreProj["PoshSSH.Core.csproj"]:::core
            GetHostKey["GetSSHHostKey.cs"]:::core
            LaunchSettings["launchSettings.json"]:::core
        end
        subgraph "PoshSSH Cmdlet Implementation" 
            direction TB
            CmdletProj["PoshSSH.csproj"]:::core
            SessionObj["SessionObject.cs"]:::core
            ConnInfoGen["ConnectionInfoGenerator.cs"]:::core
            OpProgHelper["OperationProgressHelper.cs"]:::core
            subgraph "IStore Implementations" 
                direction TB
                IStore["IStore.cs"]:::core
                JSONStore["JsonStore.cs"]:::core
                MemStore["MemoryStore.cs"]:::core
                OpenSSHStore["OpenSSHStore.cs"]:::core
            end
        end
        PSM1 -->|"loads assembly"| CoreProj
        PSM1 -->|"loads cmdlet library"| CmdletProj
        CmdletProj --> SessionObj
        CmdletProj --> ConnInfoGen
        CmdletProj --> OpProgHelper
        CmdletProj --> IStore
        IStore --> JSONStore
        IStore --> MemStore
        IStore --> OpenSSHStore
        CoreProj --> GetHostKey
        CoreProj --> LaunchSettings
    end

    %% External Dependencies
    subgraph "External Dependencies" 
        direction TB
        SSHNet["Renci.SshNet.dll"]:::external
        Packages["packages.config"]:::external
    end
    CoreProj -->|"uses"| SSHNet
    CmdletProj -->|"references"| Packages

    %% Persistence
    subgraph "Local Persistence" 
        direction TB
        KnownHosts["known_hosts JSON/SSH"]:::storage
    end
    JSONStore --> KnownHosts
    OpenSSHStore --> KnownHosts

    %% Network Layer
    Remote["Remote SSH Server"]:::remote
    SSHNet -->|"network communication"| Remote

    %% Documentation & Tests
    subgraph "Supporting Components" 
        direction TB
        Docs["Documentation (docs/*.md)"]:::docs
        Tests["Test Suite (tests/*.ps1)"]:::docs
    end
    Tests --> PSHost
    Docs --> Manifest

    %% Click Events
    click Manifest "https://github.com/darkoperator/posh-ssh/blob/master/Posh-SSH/Posh-SSH.psd1"
    click PSM1 "https://github.com/darkoperator/posh-ssh/blob/master/Posh-SSH/Posh-SSH.psm1"
    click Formats "https://github.com/darkoperator/posh-ssh/blob/master/Posh-SSH/Format/*.ps1xml"
    click HelpFiles "https://github.com/darkoperator/posh-ssh/blob/master/Posh-SSH/en-US/*.xml"
    click AddIdentity "https://github.com/darkoperator/posh-ssh/blob/master/Posh-SSH/Add-SshIdentity.ps1"
    click CoreProj "https://github.com/darkoperator/posh-ssh/blob/master/Source/PoshSSH/PoshSSH.Core/PoshSSH.Core.csproj"
    click GetHostKey "https://github.com/darkoperator/posh-ssh/blob/master/Source/PoshSSH/PoshSSH.Core/GetSSHHostKey.cs"
    click LaunchSettings "https://github.com/darkoperator/posh-ssh/blob/master/Source/PoshSSH/PoshSSH.Core/Properties/launchSettings.json"
    click SessionObj "https://github.com/darkoperator/posh-ssh/blob/master/Source/PoshSSH/PoshSSH/SessionObject.cs"
    click ConnInfoGen "https://github.com/darkoperator/posh-ssh/blob/master/Source/PoshSSH/PoshSSH/ConnectionInfoGenerator.cs"
    click OpProgHelper "https://github.com/darkoperator/posh-ssh/blob/master/Source/PoshSSH/PoshSSH/OperationProgressHelper.cs"
    click IStore "https://github.com/darkoperator/posh-ssh/blob/master/Source/PoshSSH/PoshSSH/Stores/IStore.cs"
    click JSONStore "https://github.com/darkoperator/posh-ssh/blob/master/Source/PoshSSH/PoshSSH/Stores/JsonStore.cs"
    click MemStore "https://github.com/darkoperator/posh-ssh/blob/master/Source/PoshSSH/PoshSSH/Stores/MemoryStore.cs"
    click OpenSSHStore "https://github.com/darkoperator/posh-ssh/blob/master/Source/PoshSSH/PoshSSH/Stores/OpenSSHStore.cs"
    click Packages "https://github.com/darkoperator/posh-ssh/blob/master/Source/PoshSSH/PoshSSH/packages.config"

    %% Styles
    classDef powershell fill:#cce5ff,stroke:#4da3ff,color:#000;
    classDef core fill:#d4edda,stroke:#3c763d,color:#000;
    classDef external fill:#ffe5b4,stroke:#ff9800,color:#000;
    classDef remote fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef storage fill:#f0f0f0,stroke:#9e9e9e,color:#000;
    classDef docs fill:#f8d7da,stroke:#c82333,color:#000;
```
