pxmon/docs/ARCHITECTURE.md

Architecture

Components

• cmd/pxmon: main CLI and TUI entrypoint.
• cmd/pxmon-agent: node-side agent binary.
• internal/cli: command parsing, TUI, bot integration, UX flows.
• internal/cluster: cluster model/store/service, SSH operations, alerts, reports, backup/runbooks/scheduler.
• internal/history: metrics history stores and chart helpers.
• internal/agent: agent API server and stats collection types.

Data model

• Registry is encrypted and stored locally.
• Default path: <user-config-dir>/pxmon/clusters.enc
• Master key path defaults to <user-config-dir>/pxmon/master.key
• Supports environment overrides:
  • PXMON_CONFIG
  • PXMON_MASTER_KEY

Runtime flow

1. User invokes CLI/TUI command.
2. internal/cli resolves cluster selector and command flags.
3. internal/cluster.Service performs SSH/agent calls.
4. Results are rendered in CLI tables/JSON or TUI panels.
5. Optional telemetry/history snapshots are persisted for trends.

Security model

• Local registry encryption with a generated master key.
• Locker subsystem can block operational commands until unlock.
• Config export/import supports passphrase-protected bundles.