# 010228lxz/xzssh architecture

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

- Interactive diagram: https://gitdiagram.com/010228lxz/xzssh
- Repository: https://github.com/010228lxz/xzssh

## Overview

xzSSH is an interactive SSH configuration manager whose main workflow is to load a structured JSON configuration, validate and manage hosts, then generate OpenSSH configuration for real connections and related operations. The map includes documented search, import/sync, security, key, profile, history, tunnel, and transfer capabilities. Several command implementations are unsampled, so their documented roles are shown without inferring internal call chains; the CLI dispatcher and core parse/validate/generate layers have source support.

Main entry points: [`xzssh/cli/main.py`](https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/main.py) (CLI dispatcher), [`xzssh/parser/json_parser.py`](https://github.com/010228lxz/xzssh/blob/main/xzssh/parser/json_parser.py) (JSON parser), [`xzssh/model/types.py`](https://github.com/010228lxz/xzssh/blob/main/xzssh/model/types.py) (Config model), [`xzssh/sync/diff.py`](https://github.com/010228lxz/xzssh/blob/main/xzssh/sync/diff.py) (Drift comparison)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI Experience"]
  node_cli["CLI dispatcher<br/>[main.py]"]
  node_dashboard["Interactive dashboard<br/>[menu.py]"]
  node_hostcommands["Host management<br/>[add.py]"]
  node_search["Search and listing<br/>[search.py]"]
  node_profiles["Profiles and themes<br/>[profiles.py]"]
end

subgraph group_config["Configuration Lifecycle"]
  node_jsonparse["JSON parser<br/>[json_parser.py]"]
  node_opensshparse["OpenSSH importer<br/>[openssh_parser.py]"]
  node_model["Config model<br/>[types.py]"]
  node_validator["Config validation<br/>[validate.py]"]
  node_generator["OpenSSH generator<br/>[openssh.py]"]
  node_sync["Drift comparison<br/>[diff.py]"]
  node_configfile[("JSON source config")]
end

subgraph group_sshops["SSH Operations"]
  node_sshconfig["OpenSSH config"]
  node_connect["Connect and health checks<br/>[connect.py]"]
  node_forwarding["Tunnels and transfers<br/>[tunnels.py]"]
  node_keylife["Key lifecycle<br/>[key.py]"]
  node_history["Connection history<br/>[eventlog.py]"]
end

subgraph group_security["Security And Profiles"]
  node_crypto["Config encryption<br/>[envelope.py]"]
  node_platform["Paths and permissions<br/>[paths.py]"]
end

node_user(("SSH administrator"))
node_gpgage["GPG or age"]
node_ssh["OpenSSH tools"]

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches"| node_dashboard
node_cli -->|"dispatches"| node_hostcommands
node_cli -->|"dispatches"| node_search
node_cli -->|"dispatches"| node_connect
node_cli -->|"resolves profile"| node_profiles
node_cli -->|"dispatches"| node_forwarding
node_cli -->|"dispatches"| node_keylife
node_cli -->|"dispatches"| node_history
node_cli -->|"dispatches"| node_crypto
node_cli -->|"dispatches"| node_sync
node_hostcommands -->|"loads config"| node_jsonparse
node_search -->|"loads config"| node_jsonparse
node_connect -->|"loads config"| node_jsonparse
node_jsonparse -->|"reads and writes"| node_configfile
node_jsonparse -->|"decrypts envelope"| node_crypto
node_jsonparse -->|"builds model"| node_model
node_opensshparse -->|"reads for import"| node_sshconfig
node_opensshparse -->|"creates hosts"| node_model
node_hostcommands -->|"validates changes"| node_validator
node_validator -->|"checks fields"| node_model
node_validator -->|"checks paths"| node_platform
node_generator -->|"renders model"| node_model
node_generator -->|"writes config"| node_sshconfig
node_sync -->|"compares parsed hosts"| node_opensshparse
node_sync -->|"compares JSON hosts"| node_model
node_sync -->|"checks drift"| node_sshconfig
node_connect -->|"starts connections"| node_ssh
node_forwarding -->|"opens forwards"| node_ssh
node_forwarding -.->|"runs transfer tools"| node_ssh
node_keylife -.->|"invokes key tools"| node_ssh
node_history -->|"stores opt-in log"| node_configfile
node_crypto -.->|"encrypts or decrypts"| node_gpgage
node_crypto -->|"protects source file"| node_configfile
node_platform -->|"secures permissions"| node_configfile

click node_cli "https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/main.py"
click node_dashboard "https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/commands/menu.py"
click node_hostcommands "https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/commands/add.py"
click node_search "https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/commands/search.py"
click node_profiles "https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/profiles.py"
click node_jsonparse "https://github.com/010228lxz/xzssh/blob/main/xzssh/parser/json_parser.py"
click node_opensshparse "https://github.com/010228lxz/xzssh/blob/main/xzssh/parser/openssh_parser.py"
click node_model "https://github.com/010228lxz/xzssh/blob/main/xzssh/model/types.py"
click node_validator "https://github.com/010228lxz/xzssh/blob/main/xzssh/validator/validate.py"
click node_generator "https://github.com/010228lxz/xzssh/blob/main/xzssh/generator/openssh.py"
click node_sync "https://github.com/010228lxz/xzssh/blob/main/xzssh/sync/diff.py"
click node_connect "https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/commands/connect.py"
click node_forwarding "https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/tunnels.py"
click node_keylife "https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/commands/key.py"
click node_history "https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/eventlog.py"
click node_crypto "https://github.com/010228lxz/xzssh/blob/main/xzssh/crypto/envelope.py"
click node_platform "https://github.com/010228lxz/xzssh/blob/main/xzssh/platform/paths.py"

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_cli,node_dashboard,node_hostcommands,node_search,node_profiles toneBlue
class node_jsonparse,node_opensshparse,node_model,node_validator,node_generator,node_sync,node_configfile toneAmber
class node_sshconfig,node_connect,node_forwarding,node_keylife,node_history toneMint
class node_crypto,node_platform toneRose
class node_user,node_gpgage,node_ssh toneIndigo
```

## Components

### CLI Experience

- [CLI dispatcher](https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/main.py): `xzssh/cli/main.py`
- [Interactive dashboard](https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/commands/menu.py): `xzssh/cli/commands/menu.py`
- [Host management](https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/commands/add.py): `xzssh/cli/commands/add.py`
- [Search and listing](https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/commands/search.py): `xzssh/cli/commands/search.py`
- [Profiles and themes](https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/profiles.py): `xzssh/cli/profiles.py`

### Configuration Lifecycle

- [JSON parser](https://github.com/010228lxz/xzssh/blob/main/xzssh/parser/json_parser.py): `xzssh/parser/json_parser.py`
- [OpenSSH importer](https://github.com/010228lxz/xzssh/blob/main/xzssh/parser/openssh_parser.py): `xzssh/parser/openssh_parser.py`
- [Config model](https://github.com/010228lxz/xzssh/blob/main/xzssh/model/types.py): `xzssh/model/types.py`
- [Config validation](https://github.com/010228lxz/xzssh/blob/main/xzssh/validator/validate.py): `xzssh/validator/validate.py`
- [OpenSSH generator](https://github.com/010228lxz/xzssh/blob/main/xzssh/generator/openssh.py): `xzssh/generator/openssh.py`
- [Drift comparison](https://github.com/010228lxz/xzssh/blob/main/xzssh/sync/diff.py): `xzssh/sync/diff.py`
- **JSON source config**

### SSH Operations

- **OpenSSH config**
- [Connect and health checks](https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/commands/connect.py): `xzssh/cli/commands/connect.py`
- [Tunnels and transfers](https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/tunnels.py): `xzssh/cli/tunnels.py`
- [Key lifecycle](https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/commands/key.py): `xzssh/cli/commands/key.py`
- [Connection history](https://github.com/010228lxz/xzssh/blob/main/xzssh/cli/eventlog.py): `xzssh/cli/eventlog.py`

### Security And Profiles

- [Config encryption](https://github.com/010228lxz/xzssh/blob/main/xzssh/crypto/envelope.py): `xzssh/crypto/envelope.py`
- [Paths and permissions](https://github.com/010228lxz/xzssh/blob/main/xzssh/platform/paths.py): `xzssh/platform/paths.py`

### Other components

- **SSH administrator**
- **GPG or age**
- **OpenSSH tools**

## Connections

- SSH administrator → CLI dispatcher: runs commands
- CLI dispatcher → Interactive dashboard: dispatches
- CLI dispatcher → Host management: dispatches
- CLI dispatcher → Search and listing: dispatches
- CLI dispatcher → Connect and health checks: dispatches
- CLI dispatcher → Profiles and themes: resolves profile
- CLI dispatcher → Tunnels and transfers: dispatches
- CLI dispatcher → Key lifecycle: dispatches
- CLI dispatcher → Connection history: dispatches
- CLI dispatcher → Config encryption: dispatches
- CLI dispatcher → Drift comparison: dispatches
- Host management → JSON parser: loads config
- Search and listing → JSON parser: loads config
- Connect and health checks → JSON parser: loads config
- JSON parser → JSON source config: reads and writes
- JSON parser → Config encryption: decrypts envelope
- JSON parser → Config model: builds model
- OpenSSH importer → OpenSSH config: reads for import
- OpenSSH importer → Config model: creates hosts
- Host management → Config validation: validates changes
- Config validation → Config model: checks fields
- Config validation → Paths and permissions: checks paths
- OpenSSH generator → Config model: renders model
- OpenSSH generator → OpenSSH config: writes config
- Drift comparison → OpenSSH importer: compares parsed hosts
- Drift comparison → Config model: compares JSON hosts
- Drift comparison → OpenSSH config: checks drift
- Connect and health checks → OpenSSH tools: starts connections
- Tunnels and transfers → OpenSSH tools: opens forwards
- Tunnels and transfers → OpenSSH tools: runs transfer tools
- Key lifecycle → OpenSSH tools: invokes key tools
- Connection history → JSON source config: stores opt-in log
- Config encryption → GPG or age: encrypts or decrypts
- Config encryption → JSON source config: protects source file
- Paths and permissions → JSON source config: secures permissions