# trevonix/trxo architecture

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

- Interactive diagram: https://gitdiagram.com/trevonix/trxo
- Repository: https://github.com/trevonix/trxo

## Overview

1. **What this repo is**
   TRXO is a Python CLI for managing Ping configurations across PingOne Advanced Identity Cloud, PingAM, and PingIDM. Its core job is to move configuration objects between environments, compare them, store them locally or in Git, and safely apply changes.

2. **Primary entrypoint and command surface**
   `src/trxo/main.py` is the runtime entrypoint. The CLI is organized into command groups under `src/trxo/commands/`: `export`, `imports`, `batch`, `config`, `logs`, and `project`. This gives the tool a clear top-level flow: authenticate, choose an operation, then delegate to a specialized command handler.

3. **Authentication boundary**
   Auth is split by environment type in `src/trxo/auth/`:
   - `service_account.py` for PingOne Advanced Identity Cloud
   - `on_premise.py` for PingAM/PingIDM
   - `token_manager.py` for token lifecycle handling  
   The command layer uses a shared auth manager, so authentication is centralized rather than duplicated across commands.

4. **Export pipeline**
   Export logic lives under `src/trxo/commands/export/` with one module per configuration domain: realms, applications, OAuth, SAML, connectors, policies, managed objects, themes, scripts, webhooks, and more. These modules likely collect data from Ping APIs and normalize it into files or versioned artifacts through shared base/export manager classes.

5. **Import pipeline**
   Import logic mirrors export under `src/trxo/commands/imports/`. The symmetry suggests a two-way configuration migration model: export from a source, then import into a target. Shared utilities such as `component_mapper`, `file_loader`, `sync_handler`, and `cherry_pick_filter` indicate support for selective imports, dependency handling, and sync mode.

6. **Storage modes and Git-backed workflow**
   A major architectural boundary is storage. TRXO can persist exported configuration either to the local filesystem or to a Git repository. The Git-specific path is handled in `src/trxo/utils/git/` with repository, branch, credential, and operation helpers, while `src/trxo/utils/export/` contains file saving, metadata building, versioning context, and rendering. This is the foundation for auditability, diffing, and rollback.

7. **Diff and change-preview subsystem**
   The diff stack in `src/trxo/utils/diff/` supports “preview before import.” `data_fetcher`, `diff_engine`, `diff_manager`, `diff_reporter`, and `insights_generator` work together to compare current and desired state and produce human-readable change summaries. This is a key safety boundary between read-only comparison and mutation.

8. **Batch and automation flow**
   `src/trxo/commands/batch/` supports large-scale operations, likely for realm-wide or multi-object migration. The presence of a config generator and batch manager shows this repo is built not just for interactive CLI use, but also for repeatable pipeline-style execution in CI/CD or scripted migrations.

9. **Configuration and validation**
   `src/trxo/commands/config/` manages tool setup, auth configuration, and validation. This layer separates user/environment settings from operational commands, which helps keep auth, storage, and runtime options consistent across exports/imports.

10. **Safety, rollback, and deletion handling**
   TRXO includes explicit safeguards in utility code such as `rollback_manager`, `deletion_manager`, and hash-based tracking. Together with Git storage and diff previews, these form the tool’s “safe deployment” boundary: detect what will change, apply selectively, and recover when needed.

11. **Logging and observability**
   `src/trxo/logging/` provides structured logging, formatting, utilities, and masking of sensitive values. The README and `logs` command indicate logging is a first-class operational feature, used for tracing API activity and troubleshooting without exposing secrets.

12. **Important external dependencies and runtime context**
   The system is a Python package (`pyproject.toml`) with MkDocs documentation and GitHub Actions workflows for CI, docs deployment, and releases. The main external systems it interacts with are Ping configuration APIs and Git repositories; those are the two dominant integration boundaries in the architecture.

13. **How the main data flow works**
   Typical flow: authenticate to a Ping environment, export configuration objects through resource-specific modules, normalize and store them locally or in Git, optionally diff source vs target, then import selected changes into the destination with rollback and sync/cherry-pick controls. The repo is structured around that end-to-end migration lifecycle rather than around a single isolated command.

Main entry points: [`src/trxo/main.py`](https://github.com/trevonix/trxo/blob/main/src/trxo/main.py) (Main CLI), [`src/trxo/commands/shared/auth_manager.py`](https://github.com/trevonix/trxo/blob/main/src/trxo/commands/shared/auth_manager.py) (Auth manager), [`src/trxo/commands/imports/manager.py`](https://github.com/trevonix/trxo/blob/main/src/trxo/commands/imports/manager.py) (Import flow), [`src/trxo/commands/shared`](https://github.com/trevonix/trxo/tree/main/src/trxo/commands/shared) (Shared CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_cli["CLI surface"]
  node_node_main(("Main CLI<br/>entrypoint<br/>[main.py]"))
  node_node_shared_cmd["Shared CLI<br/>command core"]
  node_node_config_cmd["Config cmd<br/>settings command"]
  node_node_logs_cmd["Logs cmd<br/>logging command<br/>[logs.py]"]
  node_node_project_cmd["Project cmd<br/>project command<br/>[project.py]"]
end

subgraph group_grp_pipelines["Migration pipelines"]
  node_node_export_mgr["Export flow<br/>export orchestrator<br/>[manager.py]"]
  node_node_export_domain["Export domains<br/>resource exporters"]
  node_node_import_mgr["Import flow<br/>import orchestrator<br/>[manager.py]"]
  node_node_import_domain["Import domains<br/>resource importers"]
  node_node_batch["Batch ops<br/>bulk workflow"]
  node_node_diff["Diff engine<br/>change preview"]
end

subgraph group_grp_support["Support systems"]
  node_node_auth["Auth layer<br/>environment auth"]
  node_node_auth_mgr["Auth manager<br/>auth coordination<br/>[auth_manager.py]"]
  node_node_storage["Export storage<br/>file/git storage"]
  node_node_git["Git utils<br/>git integration"]
  node_node_import_utils["Import utils<br/>import helpers"]
  node_node_safety["Safety ops<br/>rollback and delete"]
  node_node_logging["Logging<br/>observability"]
  node_node_config_store["Config store<br/>runtime config<br/>[config_store.py]"]
  node_node_api["API config<br/>api headers<br/>[api_headers.py]"]
end

node_node_main -->|"dispatches"| node_node_shared_cmd
node_node_main -->|"exposes"| node_node_config_cmd
node_node_main -->|"exposes"| node_node_logs_cmd
node_node_main -->|"exposes"| node_node_project_cmd
node_node_shared_cmd -->|"uses"| node_node_auth_mgr
node_node_shared_cmd -->|"reads/writes"| node_node_config_store
node_node_config_cmd -->|"configures"| node_node_auth_mgr
node_node_auth_mgr -->|"delegates to"| node_node_auth
node_node_export_mgr -->|"orchestrates"| node_node_export_domain
node_node_import_mgr -->|"orchestrates"| node_node_import_domain
node_node_export_domain -->|"requires"| node_node_auth_mgr
node_node_import_domain -->|"requires"| node_node_auth_mgr
node_node_export_domain -->|"persists to"| node_node_storage
node_node_storage -->|"optionally uses"| node_node_git
node_node_import_mgr -->|"uses"| node_node_import_utils
node_node_import_mgr -->|"previews changes"| node_node_diff
node_node_diff -->|"compares against"| node_node_storage
node_node_diff -->|"informs"| node_node_safety
node_node_batch -->|"runs"| node_node_export_mgr
node_node_batch -->|"runs"| node_node_import_mgr
node_node_logging -->|"supports"| node_node_main
node_node_api -->|"supports"| node_node_auth

click node_node_main "https://github.com/trevonix/trxo/blob/main/src/trxo/main.py"
click node_node_shared_cmd "https://github.com/trevonix/trxo/tree/main/src/trxo/commands/shared"
click node_node_config_cmd "https://github.com/trevonix/trxo/tree/main/src/trxo/commands/config"
click node_node_logs_cmd "https://github.com/trevonix/trxo/blob/main/src/trxo/commands/logs.py"
click node_node_project_cmd "https://github.com/trevonix/trxo/blob/main/src/trxo/commands/project.py"
click node_node_export_mgr "https://github.com/trevonix/trxo/blob/main/src/trxo/commands/export/manager.py"
click node_node_export_domain "https://github.com/trevonix/trxo/tree/main/src/trxo/commands/export"
click node_node_import_mgr "https://github.com/trevonix/trxo/blob/main/src/trxo/commands/imports/manager.py"
click node_node_import_domain "https://github.com/trevonix/trxo/tree/main/src/trxo/commands/imports"
click node_node_batch "https://github.com/trevonix/trxo/tree/main/src/trxo/commands/batch"
click node_node_diff "https://github.com/trevonix/trxo/tree/main/src/trxo/utils/diff"
click node_node_auth "https://github.com/trevonix/trxo/tree/main/src/trxo/auth"
click node_node_auth_mgr "https://github.com/trevonix/trxo/blob/main/src/trxo/commands/shared/auth_manager.py"
click node_node_storage "https://github.com/trevonix/trxo/tree/main/src/trxo/utils/export"
click node_node_git "https://github.com/trevonix/trxo/tree/main/src/trxo/utils/git"
click node_node_import_utils "https://github.com/trevonix/trxo/tree/main/src/trxo/utils/imports"
click node_node_safety "https://github.com/trevonix/trxo/tree/main/src/trxo/utils"
click node_node_logging "https://github.com/trevonix/trxo/tree/main/src/trxo/logging"
click node_node_config_store "https://github.com/trevonix/trxo/blob/main/src/trxo/utils/config_store.py"
click node_node_api "https://github.com/trevonix/trxo/blob/main/src/trxo/config/api_headers.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_node_main,node_node_shared_cmd,node_node_config_cmd,node_node_logs_cmd,node_node_project_cmd toneBlue
class node_node_export_mgr,node_node_export_domain,node_node_import_mgr,node_node_import_domain,node_node_batch,node_node_diff toneAmber
class node_node_auth,node_node_auth_mgr,node_node_storage,node_node_git,node_node_import_utils,node_node_safety,node_node_logging,node_node_config_store,node_node_api toneMint
```

## Components

### CLI surface

Entry points, command dispatch, and user-facing operations.

- [Main CLI](https://github.com/trevonix/trxo/blob/main/src/trxo/main.py): entrypoint · Runtime entrypoint that boots the command-line interface. · `src/trxo/main.py`
- [Shared CLI](https://github.com/trevonix/trxo/tree/main/src/trxo/commands/shared): command core · Common command base, auth wiring, and CLI option handling. · `src/trxo/commands/shared`
- [Config cmd](https://github.com/trevonix/trxo/tree/main/src/trxo/commands/config): settings command · Tool setup, auth configuration, and validation commands. · `src/trxo/commands/config`
- [Logs cmd](https://github.com/trevonix/trxo/blob/main/src/trxo/commands/logs.py): logging command · User-facing logging and log inspection command surface. · `src/trxo/commands/logs.py`
- [Project cmd](https://github.com/trevonix/trxo/blob/main/src/trxo/commands/project.py): project command · Project-level command surface for repo/workspace operations. · `src/trxo/commands/project.py`

### Migration pipelines

Export, import, batch, and diff flows for Ping configuration movement.

- [Export flow](https://github.com/trevonix/trxo/blob/main/src/trxo/commands/export/manager.py): export orchestrator · Coordinates resource-specific export handlers. · `src/trxo/commands/export/manager.py`
- [Export domains](https://github.com/trevonix/trxo/tree/main/src/trxo/commands/export): resource exporters · Per-domain exporters for realms, apps, OAuth, SAML, policies, scripts, themes, and more. · `src/trxo/commands/export`
- [Import flow](https://github.com/trevonix/trxo/blob/main/src/trxo/commands/imports/manager.py): import orchestrator · Coordinates resource-specific import handlers. · `src/trxo/commands/imports/manager.py`
- [Import domains](https://github.com/trevonix/trxo/tree/main/src/trxo/commands/imports): resource importers · Per-domain importers mirroring the export side. · `src/trxo/commands/imports`
- [Batch ops](https://github.com/trevonix/trxo/tree/main/src/trxo/commands/batch): bulk workflow · Batch export/import and config generation for repeatable migration runs. · `src/trxo/commands/batch`
- [Diff engine](https://github.com/trevonix/trxo/tree/main/src/trxo/utils/diff): change preview · Fetches data, computes diffs, and generates change summaries before import. · `src/trxo/utils/diff`

### Support systems

Authentication, storage, Git, logging, and shared utilities.

- [Auth layer](https://github.com/trevonix/trxo/tree/main/src/trxo/auth): environment auth · Service-account and on-premise authentication with token lifecycle handling. · `src/trxo/auth`
- [Auth manager](https://github.com/trevonix/trxo/blob/main/src/trxo/commands/shared/auth_manager.py): auth coordination · Shared authentication coordination used by commands. · `src/trxo/commands/shared/auth_manager.py`
- [Export storage](https://github.com/trevonix/trxo/tree/main/src/trxo/utils/export): file/git storage · Stores exported configuration locally or through Git-backed workflows. · `src/trxo/utils/export`
- [Git utils](https://github.com/trevonix/trxo/tree/main/src/trxo/utils/git): git integration · Repository, branch, credential, and operation helpers for Git-backed exports. · `src/trxo/utils/git`
- [Import utils](https://github.com/trevonix/trxo/tree/main/src/trxo/utils/imports): import helpers · Component mapping, file loading, cherry-pick filtering, and sync handling. · `src/trxo/utils/imports`
- [Safety ops](https://github.com/trevonix/trxo/tree/main/src/trxo/utils): rollback and delete · Rollback, deletion, and hash tracking for controlled changes. · `src/trxo/utils`
- [Logging](https://github.com/trevonix/trxo/tree/main/src/trxo/logging): observability · Structured logging, formatting, and secret masking. · `src/trxo/logging`
- [Config store](https://github.com/trevonix/trxo/blob/main/src/trxo/utils/config_store.py): runtime config · Persistent tool settings and configuration state. · `src/trxo/utils/config_store.py`
- [API config](https://github.com/trevonix/trxo/blob/main/src/trxo/config/api_headers.py): api headers · Shared Ping API header and request configuration. · `src/trxo/config/api_headers.py`

## Connections

- Main CLI → Shared CLI: dispatches · Main CLI routes commands through the shared command layer.
- Main CLI → Config cmd: exposes · CLI exposes setup and validation commands.
- Main CLI → Logs cmd: exposes · CLI exposes logging-related commands.
- Main CLI → Project cmd: exposes · CLI exposes project-level commands.
- Shared CLI → Auth manager: uses · Shared command layer centralizes authentication handling.
- Shared CLI → Config store: reads/writes · Shared command layer relies on stored runtime settings.
- Config cmd → Auth manager: configures · Config commands set up and validate authentication.
- Auth manager → Auth layer: delegates to · Authentication manager delegates to environment-specific auth implementations.
- Export flow → Export domains: orchestrates · Export manager coordinates per-domain exporters.
- Import flow → Import domains: orchestrates · Import manager coordinates per-domain importers.
- Export domains → Auth manager: requires · Exports need authenticated API access.
- Import domains → Auth manager: requires · Imports need authenticated API access.
- Export domains → Export storage: persists to · Exported artifacts are written to local or Git-backed storage.
- Export storage → Git utils: optionally uses · Git-backed storage delegates repository operations to Git helpers.
- Import flow → Import utils: uses · Import orchestration depends on mapping, loading, and sync helpers.
- Import flow → Diff engine: previews changes · Import flow uses diffing to preview intended changes.
- Diff engine → Export storage: compares against · Diffing compares desired artifacts against stored state.
- Diff engine → Safety ops: informs · Diff results feed rollback and deletion safeguards.
- Batch ops → Export flow: runs · Batch export wraps the export orchestration.
- Batch ops → Import flow: runs · Batch import wraps the import orchestration.
- Logging → Main CLI: supports · Logging is a cross-cutting runtime concern for the CLI.
- API config → Auth layer: supports · API headers and request settings support authenticated Ping calls.
