# clockworksspheres/jenkinstools architecture

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

- Interactive diagram: https://gitdiagram.com/clockworksspheres/jenkinstools
- Repository: https://github.com/clockworksspheres/jenkinstools

## Overview

#### Purpose and Runtime

`jenkinsTools` is a Python-based operator toolkit for administering a Jenkins server: managing agent nodes, creating/configuring/running/checking simple pipelines, and adding SSH-key credentials. It uses the external `python-jenkins` client library and targets Jenkins over its API. Dependencies are declared in `requirements.txt` and `src/requirements.txt`.

#### User Entry Points

Standalone command-line entry scripts expose the principal workflows:
- Node administration: `src/jenkinsTools/jenkinsNodeTool.py`
- Pipeline lifecycle operations: `src/jenkinsTools/jenkinsPipelineTool.py`
- SSH-key preparation/credential work: `src/jenkinsTools/jenkinsSshKeyWrangling.py`
- Desktop GUI launcher: `src/jenkinsTools/jenkinsToolsGui.py`

These are packaged as platform-native executables rather than operated as a web service.

#### Jenkins Domain Operations

The `JenkinsTools` package contains the Jenkins-facing operation layer. Node creation, update, status, and management are separated into focused commands in `src/jenkinsTools/JenkinsTools/AddJenkinsNode.py`, `src/jenkinsTools/JenkinsTools/NodeManage.py`, and `src/jenkinsTools/JenkinsTools/update_node.py`. This layer is the main boundary between local CLI/GUI inputs and Jenkins API calls.

Pipeline operations form a second domain group: pipeline creation/configuration, triggering, and result polling are represented by `src/jenkinsTools/JenkinsTools/CreateJenkinsPipeline.py`, `src/jenkinsTools/JenkinsTools/RunJenkinsPipeline.py`, and `src/jenkinsTools/JenkinsTools/CheckJenkinsPipelineRun.py`.

#### Configuration and Credentials

Shared Jenkins connection/configuration handling is centralized in `src/jenkinsTools/ConfigFile.py`. SSH credential operations are split between the user-facing workflow in `src/jenkinsTools/sshKeyWrangling.py` and Jenkins credential registration in `src/jenkinsTools/JenkinsTools/AddSshKeyCredential.py`. SSH keys must already exist; the tool adds their credentials to Jenkins rather than acting as a key-generation service.

#### Input and Interaction Boundary

CLI and GUI paths should converge on the domain operation layer after validation. Input validators are organized by workflow in `src/jenkinsTools/lib/inputValidation/generalFieldsValidation.py`, `src/jenkinsTools/lib/inputValidation/nodesFieldsValidation.py`, and `src/jenkinsTools/lib/inputValidation/pipelinesFieldsValidation.py`.

The optional Qt-style desktop interface is implemented in `src/jenkinsTools/ux/main.py`, with node and pipeline screens in `src/jenkinsTools/ux/nodesMain.py` and `src/jenkinsTools/ux/pipelinesMain.py`. Generated/UI-designer artifacts remain alongside these controllers.

#### Packaging and Cross-Platform Delivery

The repository builds native distributables for Debian-family Linux, Red Hat-family Linux, macOS, and Windows. Platform scripts/specifications live in `src/BuildScripts/build.deb-based.sh`, `src/BuildScripts/build.rh-based.sh`, `src/BuildScripts/build.macos.sh`, and `src/BuildScripts/build.windows.ps1`. Python packaging helpers produce Debian, RPM, and macOS package formats in `src/BuildScripts/buildDeb.py`, `src/BuildScripts/buildRpm.py`, and `src/BuildScripts/buildMacosPkg.py`.

#### CI and Test Infrastructure

Jenkins itself is also the project CI runtime, with cross-platform pipeline definitions in `ci/Jenkinsfile`, `ci/Jenkinsfile.debbased`, and `ci/Jenkinsfile.rhelbased`. Setup documentation describes a Jenkins controller plus platform-specific agents under `src/docs/BasicSetUpJenkinsServerForTesting/` and `src/docs/BasicSetUpJenkinsSlavesForTesting/`. The project can pair with external `mvm`-managed VMs to exercise these platform boundaries.

Main entry points: [`src/jenkinsTools/JenkinsTools/CreateJenkinsPipeline.py`](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/JenkinsTools/CreateJenkinsPipeline.py) (Pipeline creation), [`src/jenkinsTools/ConfigFile.py`](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/ConfigFile.py) (Jenkins connection config), [`src/jenkinsTools/ux/main.py`](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/ux/main.py) (Node and pipeline screens), [`src/jenkinsTools/JenkinsTools/RunJenkinsPipeline.py`](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/JenkinsTools/RunJenkinsPipeline.py) (Pipeline execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Local entry points"]
  node_node_cli["Node CLI<br/>Python CLI<br/>[jenkinsNodeTool.py]"]
  node_pipeline_cli["Pipeline CLI<br/>Python CLI"]
  node_ssh_cli["SSH credential CLI<br/>Python CLI"]
  node_gui_launcher["Desktop GUI launcher<br/>Python GUI<br/>[jenkinsToolsGui.py]"]
  node_gui_controllers["Node and pipeline screens<br/>Qt controllers<br/>[main.py]"]
end

subgraph group_validation["Input validation"]
  node_general_validation["General validation"]
  node_node_validation["Node validation"]
  node_pipeline_validation["Pipeline validation"]
end

subgraph group_domain["Jenkins operations"]
  node_node_ops["Node operations<br/>Jenkins domain<br/>[AddJenkinsNode.py]"]
  node_pipeline_create["Pipeline creation<br/>Jenkins domain"]
  node_pipeline_run["Pipeline execution<br/>Jenkins domain"]
  node_pipeline_check["Build result polling<br/>Jenkins domain"]
  node_ssh_workflow["SSH key workflow<br/>credential workflow<br/>[sshKeyWrangling.py]"]
  node_credential_registration["SSH credential registration<br/>Jenkins domain"]
end

subgraph group_delivery["Build and CI"]
  node_native_builds["Native package builds<br/>platform build scripts<br/>[build.deb-based.sh]"]
  node_package_helpers["Package format helpers<br/>Python packaging<br/>[buildDeb.py]"]
  node_ci_pipelines["Cross-platform CI pipelines<br/>Jenkinsfiles"]
end

node_config["Jenkins connection config<br/>shared config<br/>[ConfigFile.py]"]
node_jenkins{{"Jenkins server API<br/>external service"}}
node_platform_agents{{"Platform test agents<br/>external infrastructure"}}

node_node_cli -->|"validates"| node_general_validation
node_node_cli -->|"validates node input"| node_node_validation
node_pipeline_cli -->|"validates"| node_general_validation
node_pipeline_cli -->|"validates pipeline input"| node_pipeline_validation
node_ssh_cli -->|"runs"| node_ssh_workflow
node_gui_launcher -->|"launches"| node_gui_controllers
node_gui_controllers -->|"validates node forms"| node_node_validation
node_gui_controllers -->|"validates pipeline forms"| node_pipeline_validation
node_node_validation -->|"approved input"| node_node_ops
node_pipeline_validation -->|"approved input"| node_pipeline_create
node_pipeline_create -->|"created pipeline"| node_pipeline_run
node_pipeline_run -->|"run reference"| node_pipeline_check
node_ssh_workflow -->|"registers key"| node_credential_registration
node_config -->|"connection settings"| node_node_ops
node_config -->|"connection settings"| node_pipeline_create
node_config -->|"connection settings"| node_credential_registration
node_node_ops -->|"agent API calls"| node_jenkins
node_pipeline_create -->|"configure API"| node_jenkins
node_pipeline_run -->|"trigger API"| node_jenkins
node_pipeline_check -->|"poll API"| node_jenkins
node_credential_registration -->|"credential API"| node_jenkins
node_ci_pipelines -->|"executed by"| node_jenkins
node_jenkins -->|"dispatches CI work"| node_platform_agents
node_native_builds -->|"invokes"| node_package_helpers
node_ci_pipelines -->|"runs platform builds"| node_native_builds

click node_node_cli "https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/jenkinsNodeTool.py"
click node_pipeline_cli "https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/jenkinsPipelineTool.py"
click node_ssh_cli "https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/jenkinsSshKeyWrangling.py"
click node_gui_launcher "https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/jenkinsToolsGui.py"
click node_gui_controllers "https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/ux/main.py"
click node_general_validation "https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/lib/inputValidation/generalFieldsValidation.py"
click node_node_validation "https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/lib/inputValidation/nodesFieldsValidation.py"
click node_pipeline_validation "https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/lib/inputValidation/pipelinesFieldsValidation.py"
click node_config "https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/ConfigFile.py"
click node_node_ops "https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/JenkinsTools/AddJenkinsNode.py"
click node_pipeline_create "https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/JenkinsTools/CreateJenkinsPipeline.py"
click node_pipeline_run "https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/JenkinsTools/RunJenkinsPipeline.py"
click node_pipeline_check "https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/JenkinsTools/CheckJenkinsPipelineRun.py"
click node_ssh_workflow "https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/sshKeyWrangling.py"
click node_credential_registration "https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/JenkinsTools/AddSshKeyCredential.py"
click node_native_builds "https://github.com/clockworksspheres/jenkinstools/blob/main/src/BuildScripts/build.deb-based.sh"
click node_package_helpers "https://github.com/clockworksspheres/jenkinstools/blob/main/src/BuildScripts/buildDeb.py"
click node_ci_pipelines "https://github.com/clockworksspheres/jenkinstools/blob/main/ci/Jenkinsfile"

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_node_cli,node_pipeline_cli,node_ssh_cli,node_gui_launcher,node_gui_controllers toneBlue
class node_general_validation,node_node_validation,node_pipeline_validation toneAmber
class node_node_ops,node_pipeline_create,node_pipeline_run,node_pipeline_check,node_ssh_workflow,node_credential_registration toneMint
class node_native_builds,node_package_helpers,node_ci_pipelines toneRose
class node_config,node_jenkins,node_platform_agents toneNeutral
```

## Components

### Local entry points

- [Node CLI](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/jenkinsNodeTool.py): Python CLI · `src/jenkinsTools/jenkinsNodeTool.py`
- [Pipeline CLI](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/jenkinsPipelineTool.py): Python CLI · `src/jenkinsTools/jenkinsPipelineTool.py`
- [SSH credential CLI](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/jenkinsSshKeyWrangling.py): Python CLI · `src/jenkinsTools/jenkinsSshKeyWrangling.py`
- [Desktop GUI launcher](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/jenkinsToolsGui.py): Python GUI · `src/jenkinsTools/jenkinsToolsGui.py`
- [Node and pipeline screens](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/ux/main.py): Qt controllers · `src/jenkinsTools/ux/main.py`

### Input validation

- [General validation](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/lib/inputValidation/generalFieldsValidation.py): validation · `src/jenkinsTools/lib/inputValidation/generalFieldsValidation.py`
- [Node validation](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/lib/inputValidation/nodesFieldsValidation.py): validation · `src/jenkinsTools/lib/inputValidation/nodesFieldsValidation.py`
- [Pipeline validation](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/lib/inputValidation/pipelinesFieldsValidation.py): validation · `src/jenkinsTools/lib/inputValidation/pipelinesFieldsValidation.py`

### Jenkins operations

- [Node operations](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/JenkinsTools/AddJenkinsNode.py): Jenkins domain · Creates, updates, checks, and manages agents. · `src/jenkinsTools/JenkinsTools/AddJenkinsNode.py`
- [Pipeline creation](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/JenkinsTools/CreateJenkinsPipeline.py): Jenkins domain · `src/jenkinsTools/JenkinsTools/CreateJenkinsPipeline.py`
- [Pipeline execution](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/JenkinsTools/RunJenkinsPipeline.py): Jenkins domain · `src/jenkinsTools/JenkinsTools/RunJenkinsPipeline.py`
- [Build result polling](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/JenkinsTools/CheckJenkinsPipelineRun.py): Jenkins domain · `src/jenkinsTools/JenkinsTools/CheckJenkinsPipelineRun.py`
- [SSH key workflow](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/sshKeyWrangling.py): credential workflow · Uses existing SSH keys. · `src/jenkinsTools/sshKeyWrangling.py`
- [SSH credential registration](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/JenkinsTools/AddSshKeyCredential.py): Jenkins domain · `src/jenkinsTools/JenkinsTools/AddSshKeyCredential.py`

### Build and CI

- [Native package builds](https://github.com/clockworksspheres/jenkinstools/blob/main/src/BuildScripts/build.deb-based.sh): platform build scripts · Builds Linux, macOS, and Windows distributables. · `src/BuildScripts/build.deb-based.sh`
- [Package format helpers](https://github.com/clockworksspheres/jenkinstools/blob/main/src/BuildScripts/buildDeb.py): Python packaging · Produces Debian, RPM, and macOS packages. · `src/BuildScripts/buildDeb.py`
- [Cross-platform CI pipelines](https://github.com/clockworksspheres/jenkinstools/blob/main/ci/Jenkinsfile): Jenkinsfiles · `ci/Jenkinsfile`

### Other components

- [Jenkins connection config](https://github.com/clockworksspheres/jenkinstools/blob/main/src/jenkinsTools/ConfigFile.py): shared config · `src/jenkinsTools/ConfigFile.py`
- **Jenkins server API**: external service · Accessed through python-jenkins.
- **Platform test agents**: external infrastructure · Jenkins agents may run on mvm-managed VMs.

## Connections

- Node CLI → General validation: validates
- Node CLI → Node validation: validates node input
- Pipeline CLI → General validation: validates
- Pipeline CLI → Pipeline validation: validates pipeline input
- SSH credential CLI → SSH key workflow: runs
- Desktop GUI launcher → Node and pipeline screens: launches
- Node and pipeline screens → Node validation: validates node forms
- Node and pipeline screens → Pipeline validation: validates pipeline forms
- Node validation → Node operations: approved input
- Pipeline validation → Pipeline creation: approved input
- Pipeline creation → Pipeline execution: created pipeline
- Pipeline execution → Build result polling: run reference
- SSH key workflow → SSH credential registration: registers key
- Jenkins connection config → Node operations: connection settings
- Jenkins connection config → Pipeline creation: connection settings
- Jenkins connection config → SSH credential registration: connection settings
- Node operations → Jenkins server API: agent API calls
- Pipeline creation → Jenkins server API: configure API
- Pipeline execution → Jenkins server API: trigger API
- Build result polling → Jenkins server API: poll API
- SSH credential registration → Jenkins server API: credential API
- Cross-platform CI pipelines → Jenkins server API: executed by
- Jenkins server API → Platform test agents: dispatches CI work
- Native package builds → Package format helpers: invokes
- Cross-platform CI pipelines → Native package builds: runs platform builds