# bahamas10/sshp architecture

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

- Interactive diagram: https://gitdiagram.com/bahamas10/sshp
- Repository: https://github.com/bahamas10/sshp

## Overview

`sshp` is a parallel SSH executor: it reads hosts from a file or stdin, starts a bounded number of child commands, and presents their output in line, host-grouped, or output-joined mode. Its main runtime is concentrated in `src/sshp.c`; `src/fdwatcher.c` provides the epoll/kqueue readiness abstraction used to collect child output. The graph follows the documented workflow and sampled call relationships; individual option parsing and output-formatting details are not fully shown in the excerpts.

Main entry points: [`src/sshp.c`](https://github.com/bahamas10/sshp/blob/main/src/sshp.c) (Output event loop), [`src/fdwatcher.h`](https://github.com/bahamas10/sshp/blob/main/src/fdwatcher.h) (FD watcher API), [`src/fdwatcher.c`](https://github.com/bahamas10/sshp/blob/main/src/fdwatcher.c) (Event backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input and control"]
  node_sshp["CLI and orchestration<br/>[sshp.c]"]
  node_host_list["Host list<br/>[sshp.c]"]
end

subgraph group_execution["Process execution"]
  node_scheduler["Job scheduler<br/>[sshp.c]"]
  node_launcher["Child launcher<br/>[sshp.c]"]
end

subgraph group_collection["Event collection"]
  node_child_pipes["Child output pipes<br/>[sshp.c]"]
  node_watcher_api["FD watcher API<br/>[fdwatcher.h]"]
  node_watcher_impl["Event backend<br/>[fdwatcher.c]"]
  node_event_loop["Output event loop<br/>[sshp.c]"]
end

subgraph group_presentation["Output and status"]
  node_line_mode["Line mode<br/>[sshp.c]"]
  node_group_mode["Group mode<br/>[sshp.c]"]
  node_join_mode["Join mode<br/>[sshp.c]"]
  node_process_status["Exit status<br/>[sshp.c]"]
  node_status_report["Runtime status<br/>[sshp.c]"]
end

node_user(("User"))
node_host_source["Host input"]
node_command["SSH or command"]
node_terminal(("Terminal output"))
node_signal_source(("Signal sender"))

node_user -->|"invokes"| node_sshp
node_host_source -->|"provides hosts"| node_sshp
node_sshp -->|"parses hosts"| node_host_list
node_sshp -->|"runs jobs"| node_scheduler
node_scheduler -->|"selects hosts"| node_host_list
node_scheduler -->|"starts jobs"| node_launcher
node_launcher -->|"executes"| node_command
node_command -->|"writes output"| node_child_pipes
node_sshp -->|"registers pipes"| node_watcher_api
node_watcher_api -->|"uses backend"| node_watcher_impl
node_watcher_impl -->|"returns events"| node_event_loop
node_event_loop -->|"reads output"| node_child_pipes
node_event_loop -->|"formats lines"| node_line_mode
node_event_loop -->|"streams by host"| node_group_mode
node_event_loop -->|"groups output"| node_join_mode
node_line_mode -->|"writes output"| node_terminal
node_group_mode -->|"writes output"| node_terminal
node_join_mode -->|"writes output"| node_terminal
node_event_loop -->|"reaps children"| node_process_status
node_process_status -->|"sets exit code"| node_sshp
node_signal_source -->|"sends SIGUSR1"| node_status_report
node_status_report -->|"prints status"| node_terminal

click node_sshp "https://github.com/bahamas10/sshp/blob/main/src/sshp.c"
click node_host_list "https://github.com/bahamas10/sshp/blob/main/src/sshp.c"
click node_scheduler "https://github.com/bahamas10/sshp/blob/main/src/sshp.c"
click node_launcher "https://github.com/bahamas10/sshp/blob/main/src/sshp.c"
click node_child_pipes "https://github.com/bahamas10/sshp/blob/main/src/sshp.c"
click node_watcher_api "https://github.com/bahamas10/sshp/blob/main/src/fdwatcher.h"
click node_watcher_impl "https://github.com/bahamas10/sshp/blob/main/src/fdwatcher.c"
click node_event_loop "https://github.com/bahamas10/sshp/blob/main/src/sshp.c"
click node_line_mode "https://github.com/bahamas10/sshp/blob/main/src/sshp.c"
click node_group_mode "https://github.com/bahamas10/sshp/blob/main/src/sshp.c"
click node_join_mode "https://github.com/bahamas10/sshp/blob/main/src/sshp.c"
click node_process_status "https://github.com/bahamas10/sshp/blob/main/src/sshp.c"
click node_status_report "https://github.com/bahamas10/sshp/blob/main/src/sshp.c"

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_sshp,node_host_list,node_user toneBlue
class node_scheduler,node_launcher toneAmber
class node_child_pipes,node_watcher_api,node_watcher_impl,node_event_loop toneMint
class node_line_mode,node_group_mode,node_join_mode,node_process_status,node_status_report toneRose
class node_host_source,node_command,node_terminal,node_signal_source toneIndigo
```

## Components

### Input and control

- [CLI and orchestration](https://github.com/bahamas10/sshp/blob/main/src/sshp.c): `src/sshp.c`
- [Host list](https://github.com/bahamas10/sshp/blob/main/src/sshp.c): `src/sshp.c`

### Process execution

- [Job scheduler](https://github.com/bahamas10/sshp/blob/main/src/sshp.c): `src/sshp.c`
- [Child launcher](https://github.com/bahamas10/sshp/blob/main/src/sshp.c): `src/sshp.c`

### Event collection

- [Child output pipes](https://github.com/bahamas10/sshp/blob/main/src/sshp.c): `src/sshp.c`
- [FD watcher API](https://github.com/bahamas10/sshp/blob/main/src/fdwatcher.h): `src/fdwatcher.h`
- [Event backend](https://github.com/bahamas10/sshp/blob/main/src/fdwatcher.c): `src/fdwatcher.c`
- [Output event loop](https://github.com/bahamas10/sshp/blob/main/src/sshp.c): `src/sshp.c`

### Output and status

- [Line mode](https://github.com/bahamas10/sshp/blob/main/src/sshp.c): `src/sshp.c`
- [Group mode](https://github.com/bahamas10/sshp/blob/main/src/sshp.c): `src/sshp.c`
- [Join mode](https://github.com/bahamas10/sshp/blob/main/src/sshp.c): `src/sshp.c`
- [Exit status](https://github.com/bahamas10/sshp/blob/main/src/sshp.c): `src/sshp.c`
- [Runtime status](https://github.com/bahamas10/sshp/blob/main/src/sshp.c): `src/sshp.c`

### Other components

- **User**
- **Host input**
- **SSH or command**
- **Terminal output**
- **Signal sender**

## Connections

- User → CLI and orchestration: invokes
- Host input → CLI and orchestration: provides hosts
- CLI and orchestration → Host list: parses hosts
- CLI and orchestration → Job scheduler: runs jobs
- Job scheduler → Host list: selects hosts
- Job scheduler → Child launcher: starts jobs
- Child launcher → SSH or command: executes
- SSH or command → Child output pipes: writes output
- CLI and orchestration → FD watcher API: registers pipes
- FD watcher API → Event backend: uses backend
- Event backend → Output event loop: returns events
- Output event loop → Child output pipes: reads output
- Output event loop → Line mode: formats lines
- Output event loop → Group mode: streams by host
- Output event loop → Join mode: groups output
- Line mode → Terminal output: writes output
- Group mode → Terminal output: writes output
- Join mode → Terminal output: writes output
- Output event loop → Exit status: reaps children
- Exit status → CLI and orchestration: sets exit code
- Signal sender → Runtime status: sends SIGUSR1
- Runtime status → Terminal output: prints status