# quantumsheep/sshs architecture
> Architecture diagram of the GitHub repository quantumsheep/sshs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/quantumsheep/sshs
- Repository: https://github.com/quantumsheep/sshs
## Overview
1. **Repository shape**
- This is a single-binary **Rust** project (`Cargo.toml`, `src/main.rs`) that builds a **terminal user interface for SSH host selection and connection**.
- The runtime is local only: it reads the user’s SSH config, shows an interactive host picker, and then hands off to the system `ssh` client.
2. **Top-level control flow**
- `main.rs` is the orchestration point.
- The app likely follows a pipeline of: **load SSH config → parse into host records → make records searchable → render UI → launch SSH for the chosen host**.
3. **SSH config ingestion boundary**
- The `src/ssh_config/` module is the parsing subsystem.
- It is split into:
- `parser.rs` for reading OpenSSH-style config syntax,
- `host.rs` / `host_entry.rs` for the domain model of hosts and their entries,
- `parser_error.rs` for parse failures,
- `mod.rs` as the module boundary.
- Input comes from `~/.ssh/config` by default, with support for an alternate config path per the README.
4. **Data model produced by parsing**
- The parser turns the config file into a set of host definitions that can be displayed and matched in the UI.
- The important architectural boundary is that the rest of the app consumes **parsed host metadata**, not raw config text.
5. **Search/indexing layer**
- `searchable.rs` suggests an abstraction for filtering or ranking hosts by user input.
- This sits between parsed host data and the UI, enabling interactive narrowing of the host list as the user types.
6. **Terminal UI subsystem**
- `ui.rs` contains the interactive terminal interface.
- Its job is to display the host list, accept keyboard input, apply search/filter logic, and return the selected host.
- This is the main user-facing loop of the application.
7. **SSH execution subsystem**
- `ssh.rs` is the execution boundary to the outside world.
- Once a host is selected, this layer is responsible for invoking the external `ssh` executable with the right target details.
- The README makes clear that the system `ssh` binary must already be installed and accessible in `PATH`.
8. **Key external dependencies and boundaries**
- **Filesystem:** reads SSH config from local disk.
- **Terminal:** all interaction happens in a TUI, so the app owns the terminal while running.
- **Process execution:** delegates actual connection handling to `ssh`, rather than reimplementing SSH.
9. **Error handling**
- Parse-time failures are isolated in `parser_error.rs`, which suggests clean separation between config syntax issues and UI/runtime issues.
- A likely user-visible failure mode is missing or invalid SSH config; the README explicitly documents this.
10. **Testing and release infrastructure**
- `test/` indicates there are repository-level tests or fixtures for config parsing or behavior.
- `.github/workflows/push.yml` and `release.yml` show CI for validation and release automation.
- This is a packaged CLI app, distributed through package managers and GitHub releases rather than through a server deployment.
11. **Architecture diagram hint**
- The central flow to diagram is: **SSH config file → parser → host model → searchable list → TUI → `ssh` subprocess**.
- Everything else is supporting structure around that loop.
Main entry points: [`src/ssh_config/parser.rs`](https://github.com/quantumsheep/sshs/blob/master/src/ssh_config/parser.rs) (Parser), [`src/ui.rs`](https://github.com/quantumsheep/sshs/blob/master/src/ui.rs) (Terminal UI), [`src/main.rs`](https://github.com/quantumsheep/sshs/blob/master/src/main.rs) (Main), [`src/ssh_config/host.rs`](https://github.com/quantumsheep/sshs/blob/master/src/ssh_config/host.rs) (Host model)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_grp_core["Core app"]
node_main["Main
entrypoint
[main.rs]"]
node_searchable["Searchable
filtering
[searchable.rs]"]
node_ui["Terminal UI
tui
[ui.rs]"]
node_ssh_exec["SSH runner
process exec
[ssh.rs]"]
node_system_ssh["System ssh
external binary"]
node_terminal(("Terminal
user boundary"))
node_filesystem[("Filesystem
external boundary")]
end
subgraph group_grp_config["SSH config"]
node_ssh_mod["SSH config mod
module boundary
[mod.rs]"]
node_parser["Parser
[parser.rs]"]
node_host["Host model
domain model
[host.rs]"]
node_host_entry["Host entry
domain record
[host_entry.rs]"]
node_parser_error["Parse error
error model
[parser_error.rs]"]
node_ssh_config_file["SSH config file
filesystem input"]
end
subgraph group_grp_ops["Ops"]
node_github_actions["GitHub Actions
ci/release
[workflows]"]
node_push_workflow["Push workflow
ci job
[push.yml]"]
node_release_workflow["Release workflow
release job
[release.yml]"]
end
node_main -->|"load config"| node_ssh_mod
node_ssh_mod -->|"parse"| node_parser
node_parser -->|"build hosts"| node_host
node_parser -->|"emit entries"| node_host_entry
node_parser -->|"fail with"| node_parser_error
node_ssh_config_file -->|"input"| node_parser
node_filesystem -->|"stores"| node_ssh_config_file
node_host -->|"index"| node_searchable
node_searchable -->|"filter list"| node_ui
node_ui -->|"render/input"| node_terminal
node_ui -->|"select host"| node_host
node_main -->|"run picker"| node_ui
node_main -->|"launch ssh"| node_ssh_exec
node_ssh_exec -->|"exec"| node_system_ssh
node_system_ssh -->|"connects via"| node_terminal
node_github_actions -->|"includes"| node_push_workflow
node_github_actions -->|"includes"| node_release_workflow
click node_main "https://github.com/quantumsheep/sshs/blob/master/src/main.rs"
click node_searchable "https://github.com/quantumsheep/sshs/blob/master/src/searchable.rs"
click node_ui "https://github.com/quantumsheep/sshs/blob/master/src/ui.rs"
click node_ssh_exec "https://github.com/quantumsheep/sshs/blob/master/src/ssh.rs"
click node_ssh_mod "https://github.com/quantumsheep/sshs/blob/master/src/ssh_config/mod.rs"
click node_parser "https://github.com/quantumsheep/sshs/blob/master/src/ssh_config/parser.rs"
click node_host "https://github.com/quantumsheep/sshs/blob/master/src/ssh_config/host.rs"
click node_host_entry "https://github.com/quantumsheep/sshs/blob/master/src/ssh_config/host_entry.rs"
click node_parser_error "https://github.com/quantumsheep/sshs/blob/master/src/ssh_config/parser_error.rs"
click node_github_actions "https://github.com/quantumsheep/sshs/blob/master/.github/workflows"
click node_push_workflow "https://github.com/quantumsheep/sshs/blob/master/.github/workflows/push.yml"
click node_release_workflow "https://github.com/quantumsheep/sshs/blob/master/.github/workflows/release.yml"
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_main,node_searchable,node_ui,node_ssh_exec,node_system_ssh,node_terminal,node_filesystem toneBlue
class node_ssh_mod,node_parser,node_host,node_host_entry,node_parser_error,node_ssh_config_file toneAmber
class node_github_actions,node_push_workflow,node_release_workflow toneMint
```
## Components
### Core app
Runtime flow from entrypoint through parsing, search, UI, and SSH handoff.
- [Main](https://github.com/quantumsheep/sshs/blob/master/src/main.rs): entrypoint · Orchestrates config loading, search, UI, and execution. · `src/main.rs`
- [Searchable](https://github.com/quantumsheep/sshs/blob/master/src/searchable.rs): filtering · Makes host records searchable for interactive narrowing. · `src/searchable.rs`
- [Terminal UI](https://github.com/quantumsheep/sshs/blob/master/src/ui.rs): tui · Interactive host picker and input loop. · `src/ui.rs`
- [SSH runner](https://github.com/quantumsheep/sshs/blob/master/src/ssh.rs): process exec · Launches the system ssh client for the selected host. · `src/ssh.rs`
- **System ssh**: external binary · Installed ssh executable invoked after selection.
- **Terminal**: user boundary · Interactive terminal session owned by the TUI.
- **Filesystem**: external boundary · Local disk source for SSH config and fixtures.
### SSH config
Parsing and modeling OpenSSH-style host configuration.
- [SSH config mod](https://github.com/quantumsheep/sshs/blob/master/src/ssh_config/mod.rs): module boundary · Module boundary for SSH config parsing and host modeling. · `src/ssh_config/mod.rs`
- [Parser](https://github.com/quantumsheep/sshs/blob/master/src/ssh_config/parser.rs): config parser · Reads OpenSSH-style config syntax into host data. · `src/ssh_config/parser.rs`
- [Host model](https://github.com/quantumsheep/sshs/blob/master/src/ssh_config/host.rs): domain model · Represents parsed SSH host definitions. · `src/ssh_config/host.rs`
- [Host entry](https://github.com/quantumsheep/sshs/blob/master/src/ssh_config/host_entry.rs): domain record · Captures individual host entry fields and options. · `src/ssh_config/host_entry.rs`
- [Parse error](https://github.com/quantumsheep/sshs/blob/master/src/ssh_config/parser_error.rs): error model · Represents SSH config parsing failures. · `src/ssh_config/parser_error.rs`
- **SSH config file**: filesystem input · Local ~/.ssh/config or alternate config path.
### Ops
CI and release automation around the CLI binary.
- [GitHub Actions](https://github.com/quantumsheep/sshs/blob/master/.github/workflows): ci/release · Workflow automation for validation and releases. · `.github/workflows`
- [Push workflow](https://github.com/quantumsheep/sshs/blob/master/.github/workflows/push.yml): ci job · Validation pipeline on repository changes. · `.github/workflows/push.yml`
- [Release workflow](https://github.com/quantumsheep/sshs/blob/master/.github/workflows/release.yml): release job · Automates packaging and publishing releases. · `.github/workflows/release.yml`
## Connections
- Main → SSH config mod: load config · Main starts by reading SSH configuration through the config module.
- SSH config mod → Parser: parse · Module boundary delegates syntax parsing to the parser.
- Parser → Host model: build hosts · Parser produces host definitions consumed by the rest of the app.
- Parser → Host entry: emit entries · Parser populates individual host entry records.
- Parser → Parse error: fail with · Syntax and read failures are reported as parse errors.
- SSH config file → Parser: input · Parser reads the user SSH config from disk.
- Filesystem → SSH config file: stores · The config file lives on local filesystem.
- Host model → Searchable: index · Parsed host data is transformed into searchable records.
- Searchable → Terminal UI: filter list · UI uses search abstraction to narrow hosts as the user types.
- Terminal UI → Terminal: render/input · Terminal UI owns display and keyboard interaction.
- Terminal UI → Host model: select host · UI returns the chosen host record to the caller.
- Main → Terminal UI: run picker · Main launches the interactive selection loop.
- Main → SSH runner: launch ssh · Main hands the selected host to the SSH execution layer.
- SSH runner → System ssh: exec · Execution layer invokes the external ssh binary.
- System ssh → Terminal: connects via · SSH session takes over the user terminal after launch.
- GitHub Actions → Push workflow: includes · CI validation workflow is defined under GitHub Actions.
- GitHub Actions → Release workflow: includes · Release automation workflow is defined under GitHub Actions.