axonops/axonops-workbench

Purpose and Runtime

AxonOps Workbench is a cross-platform Electron desktop client for administering Apache Cassandra, DataStax Enterprise, and Astra DB. It provides CQL querying, metadata/tracing workflows, workspace-managed connections, SSH access, and optional local Cassandra clusters. Development requires Node.js, pnpm, and Python; packaged targets are macOS, Windows, and Linux.

Process Entry Points and Boundary

Electron’s privileged main process owns application lifecycle, windows, native dialogs, filesystem/keychain-adjacent operations, CQL sessions, and IPC handlers: main/main.js, main/ipc.js, custom_modules/main/cqlsession.js. The renderer process owns HTML UI and user interactions: renderer/views/index.html, renderer/js/init.js, renderer/js/events/common.js. IPC is the principal trust and control boundary between them.

Main-Process Application Services

The main-side custom modules centralize process-level services rather than placing them in Electron bootstrap code:

• Startup arguments, app configuration, constants, and logging: custom_modules/main/argv.js, custom_modules/main/config.js, custom_modules/main/logging.js.

• Cassandra connection/session execution is isolated in custom_modules/main/cqlsession.js.

• Native dialogs, report generation, and scripts are handled through custom_modules/main/dialogs.js, custom_modules/main/reports.js, custom_modules/main/scripts.js.

This layer mediates renderer requests before they reach local OS resources or databases.

Connection and CQL Workflow

Renderer connection events collect and manage connection state, then invoke IPC CQL and metadata operations: renderer/js/events/connections.js, renderer/js/events/connections/ipc-cql-operations.js, renderer/js/events/connections/ipc-metadata-dialog.js. The main process establishes Cassandra sessions and returns results/metadata through IPC. The UI includes CQL highlighting and tree-oriented metadata presentation via renderer/js/utils/cql_highlight.js and renderer/js/utils/treeview.js. Remote connectivity may traverse SSH tunnels; the bundled tunnel integration is renderer/js/external/open_ssh_tunnel.js.

Workspaces, Credentials, and Persistent State

Workspaces organize shareable cluster/connection definitions and are handled in renderer and main service layers: renderer/js/events/workspaces.js, custom_modules/renderer/workspaces.js, custom_modules/main/config.js. Repository defaults/data directories indicate local persistence for workspace and local-cluster state: data/workspaces/, data/localclusters/localclusters.json. README-defined credential storage uses the operating system keychain/credential manager, making secrets deliberately outside ordinary workspace files.

Local Cluster Orchestration

Local Cassandra development clusters are an optional infrastructure path, separated from normal remote database access. Docker/Podman detection, Compose generation/execution, and migration support reside in custom_modules/renderer/docker.js, custom_modules/renderer/docker-migration.js, and renderer/js/events/docker.js; the Compose template is renderer/js/defaults/docker-compose.js. Docker or Podman with Compose is an external runtime dependency.

CLI, Integrations, and Distribution

A CLI supports automation and launching CQLSH from workspace connections: custom_modules/renderer/cli.js, with contract documentation in docs/cli.md. CQLSH binaries are obtained by tools/install_tools.sh from the separate axonops-workbench-cqlsh release stream. AxonOps-specific embedded/webview surfaces are represented by renderer/js/axonops/agent-webview.js and renderer/js/axonops/ai-webview.js. Electron packaging/signing resources are platform-specific under resources/, while release automation is defined in .github/workflows/release.yml.