# windvalley/gossh architecture

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

- Interactive diagram: https://gitdiagram.com/windvalley/gossh
- Repository: https://github.com/windvalley/gossh

## Overview

GoSSH is a CLI for operating on SSH host fleets. Users select hosts and a task—run a command or script, push files, or fetch files—and receive task output; inventory expansion, authentication, and SSH execution support that workflow. Separate branches cover configuration generation and vault encryption/decryption. The task coordinator and batch SSH client are the internal execution layers. Some command and configuration implementations are unsampled, so their relationships are included only where the README documents capabilities or source-index references support them.

Main entry points: [`internal/pkg/sshtask/sshtask.go`](https://github.com/windvalley/gossh/blob/main/internal/pkg/sshtask/sshtask.go) (Task coordinator), [`cmd/gossh/main.go`](https://github.com/windvalley/gossh/blob/main/cmd/gossh/main.go) (CLI entry), [`internal/pkg/configflags`](https://github.com/windvalley/gossh/tree/main/internal/pkg/configflags) (Config and flags), [`internal/cmd/command.go`](https://github.com/windvalley/gossh/blob/main/internal/cmd/command.go) (Run command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and tasks"]
  node_entry["CLI entry<br/>[main.go]"]
  node_command["Run command<br/>[command.go]"]
  node_script["Run script<br/>[script.go]"]
  node_push["Push files<br/>[push.go]"]
  node_fetch["Fetch files<br/>[fetch.go]"]
  node_configcmd["Generate config<br/>[config.go]"]
end

subgraph group_execution["SSH execution"]
  node_task["Task coordinator<br/>[sshtask.go]"]
  node_batch["Batch SSH client<br/>[batchssh.go]"]
end

subgraph group_support["Host and configuration"]
  node_inventory["Host inventory<br/>[inventory.go]"]
  node_flags["Config and flags"]
  node_logging["Task output"]
end

subgraph group_vault["Vault security"]
  node_vaultcmd["Vault commands<br/>[vault.go]"]
  node_vaultfiles["File encryption<br/>[encrypt_file.go]"]
  node_vaultcrypto["AES wrapper<br/>[aes.go]"]
  node_aes["AES implementation<br/>[aes.go]"]
end

node_operator(("Operator"))
node_remote(("SSH hosts"))

node_operator -->|"invokes"| node_entry
node_entry -.->|"dispatches"| node_command
node_entry -.->|"dispatches"| node_script
node_entry -.->|"dispatches"| node_push
node_entry -.->|"dispatches"| node_fetch
node_entry -.->|"dispatches"| node_configcmd
node_entry -->|"dispatches"| node_vaultcmd
node_command -->|"starts task"| node_task
node_script -->|"starts task"| node_task
node_push -->|"starts task"| node_task
node_fetch -.->|"starts task"| node_task
node_command -->|"validates settings"| node_flags
node_script -->|"validates settings"| node_flags
node_push -->|"validates settings"| node_flags
node_task -->|"reads settings"| node_flags
node_task -->|"resolves hosts"| node_inventory
node_task -->|"configures client"| node_batch
node_task -->|"logs task"| node_logging
node_batch -->|"runs SSH tasks"| node_remote
node_operator -->|"requests vault task"| node_vaultcmd
node_vaultcmd -.->|"provides file encryption"| node_vaultfiles
node_vaultfiles -->|"encodes content"| node_vaultcrypto
node_vaultcrypto -->|"encrypts data"| node_aes

click node_entry "https://github.com/windvalley/gossh/blob/main/cmd/gossh/main.go"
click node_command "https://github.com/windvalley/gossh/blob/main/internal/cmd/command.go"
click node_script "https://github.com/windvalley/gossh/blob/main/internal/cmd/script.go"
click node_push "https://github.com/windvalley/gossh/blob/main/internal/cmd/push.go"
click node_fetch "https://github.com/windvalley/gossh/blob/main/internal/cmd/fetch.go"
click node_configcmd "https://github.com/windvalley/gossh/blob/main/internal/cmd/config.go"
click node_task "https://github.com/windvalley/gossh/blob/main/internal/pkg/sshtask/sshtask.go"
click node_batch "https://github.com/windvalley/gossh/blob/main/pkg/batchssh/batchssh.go"
click node_inventory "https://github.com/windvalley/gossh/blob/main/pkg/inventory/inventory.go"
click node_flags "https://github.com/windvalley/gossh/tree/main/internal/pkg/configflags"
click node_logging "https://github.com/windvalley/gossh/tree/main/pkg/log"
click node_vaultcmd "https://github.com/windvalley/gossh/blob/main/internal/cmd/vault/vault.go"
click node_vaultfiles "https://github.com/windvalley/gossh/blob/main/internal/cmd/vault/encrypt_file.go"
click node_vaultcrypto "https://github.com/windvalley/gossh/blob/main/internal/pkg/aes/aes.go"
click node_aes "https://github.com/windvalley/gossh/blob/main/pkg/aes/aes.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_command,node_script,node_push,node_fetch,node_configcmd toneBlue
class node_task,node_batch toneAmber
class node_inventory,node_flags,node_logging toneMint
class node_vaultcmd,node_vaultfiles,node_vaultcrypto,node_aes toneRose
class node_operator,node_remote toneIndigo
```

## Components

### CLI and tasks

- [CLI entry](https://github.com/windvalley/gossh/blob/main/cmd/gossh/main.go): `cmd/gossh/main.go`
- [Run command](https://github.com/windvalley/gossh/blob/main/internal/cmd/command.go): `internal/cmd/command.go`
- [Run script](https://github.com/windvalley/gossh/blob/main/internal/cmd/script.go): `internal/cmd/script.go`
- [Push files](https://github.com/windvalley/gossh/blob/main/internal/cmd/push.go): `internal/cmd/push.go`
- [Fetch files](https://github.com/windvalley/gossh/blob/main/internal/cmd/fetch.go): `internal/cmd/fetch.go`
- [Generate config](https://github.com/windvalley/gossh/blob/main/internal/cmd/config.go): `internal/cmd/config.go`

### SSH execution

- [Task coordinator](https://github.com/windvalley/gossh/blob/main/internal/pkg/sshtask/sshtask.go): `internal/pkg/sshtask/sshtask.go`
- [Batch SSH client](https://github.com/windvalley/gossh/blob/main/pkg/batchssh/batchssh.go): `pkg/batchssh/batchssh.go`

### Host and configuration

- [Host inventory](https://github.com/windvalley/gossh/blob/main/pkg/inventory/inventory.go): `pkg/inventory/inventory.go`
- [Config and flags](https://github.com/windvalley/gossh/tree/main/internal/pkg/configflags): `internal/pkg/configflags`
- [Task output](https://github.com/windvalley/gossh/tree/main/pkg/log): `pkg/log`

### Vault security

- [Vault commands](https://github.com/windvalley/gossh/blob/main/internal/cmd/vault/vault.go): `internal/cmd/vault/vault.go`
- [File encryption](https://github.com/windvalley/gossh/blob/main/internal/cmd/vault/encrypt_file.go): `internal/cmd/vault/encrypt_file.go`
- [AES wrapper](https://github.com/windvalley/gossh/blob/main/internal/pkg/aes/aes.go): `internal/pkg/aes/aes.go`
- [AES implementation](https://github.com/windvalley/gossh/blob/main/pkg/aes/aes.go): `pkg/aes/aes.go`

### Other components

- **Operator**
- **SSH hosts**

## Connections

- Operator → CLI entry: invokes
- CLI entry → Run command: dispatches
- CLI entry → Run script: dispatches
- CLI entry → Push files: dispatches
- CLI entry → Fetch files: dispatches
- CLI entry → Generate config: dispatches
- CLI entry → Vault commands: dispatches
- Run command → Task coordinator: starts task (evidence: `internal/cmd/command.go`)
- Run script → Task coordinator: starts task (evidence: `internal/cmd/script.go`)
- Push files → Task coordinator: starts task (evidence: `internal/cmd/push.go`)
- Fetch files → Task coordinator: starts task
- Run command → Config and flags: validates settings (evidence: `internal/cmd/command.go`)
- Run script → Config and flags: validates settings (evidence: `internal/cmd/script.go`)
- Push files → Config and flags: validates settings (evidence: `internal/cmd/push.go`)
- Task coordinator → Config and flags: reads settings (evidence: `internal/pkg/sshtask/sshtask.go`)
- Task coordinator → Host inventory: resolves hosts (evidence: `internal/pkg/sshtask/sshtask.go`)
- Task coordinator → Batch SSH client: configures client (evidence: `internal/pkg/sshtask/sshtask.go`)
- Task coordinator → Task output: logs task (evidence: `internal/pkg/sshtask/sshtask.go`)
- Batch SSH client → SSH hosts: runs SSH tasks (evidence: `pkg/batchssh/batchssh.go`)
- Operator → Vault commands: requests vault task
- Vault commands → File encryption: provides file encryption
- File encryption → AES wrapper: encodes content (evidence: `internal/cmd/vault/encrypt_file.go`)
- AES wrapper → AES implementation: encrypts data (evidence: `internal/pkg/aes/aes.go`)
