# ocx-sh/ocx architecture

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

- Interactive diagram: https://gitdiagram.com/ocx-sh/ocx
- Repository: https://github.com/ocx-sh/ocx

## Overview

OCX is a Rust package manager for installing pre-built binaries, switching package versions, and running tools in clean environments, including CI use. The main user path is a CLI command that installs or selects a package and then runs it; package resolution, registry access, and local package management support that path. The repository also has substantial index, project, shell, and supply-chain signing and verification capabilities. Edges are limited to README-documented workflow links and references in the supplied source index; unsampled implementation connections are left unasserted.

Main entry points: [`crates/ocx_cli/src/app.rs`](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_cli/src/app.rs) (Command interface), [`crates/ocx_oci/src/client.rs`](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_oci/src/client.rs) (OCI client), [`crates/ocx_package_manager/src/tasks.rs`](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_package_manager/src/tasks.rs) (Package tasks), [`crates/ocx_package_manager/src/tasks/resolve.rs`](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_package_manager/src/tasks/resolve.rs) (Package resolution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_cli["Command interface<br/>[app.rs]"]
  node_commands["Package commands"]
  node_exit["Error classification<br/>[exit.rs]"]
end

subgraph group_packages["Package lifecycle"]
  node_manager["Package tasks<br/>[tasks.rs]"]
  node_resolve["Package resolution<br/>[resolve.rs]"]
  node_install["Install and select<br/>[install.rs]"]
  node_launch["Execution environment<br/>[launch.rs]"]
  node_package["Package metadata<br/>[authoring.rs]"]
end

subgraph group_registry["Registry and indexes"]
  node_oci["OCI client<br/>[client.rs]"]
  node_registry[("OCI registries")]
  node_index["Package indexes<br/>[lib.rs]"]
end

subgraph group_trust["Supply-chain trust"]
  node_sign["Image signing<br/>[pipeline.rs]"]
  node_attest["Attestations<br/>[pipeline.rs]"]
  node_verify["Signature verification<br/>[pipeline.rs]"]
  node_forge["Forge announcements<br/>[forge.rs]"]
end

subgraph group_runtime["Project and shell"]
  node_config["Configuration<br/>[lib.rs]"]
  node_project["Project context<br/>[compose.rs]"]
  node_shell["Shell integration<br/>[shell.rs]"]
end

node_user(("Package user"))

node_user -->|"runs command"| node_cli
node_cli -->|"dispatches"| node_commands
node_commands -.->|"invokes tasks"| node_manager
node_manager -.->|"resolves package"| node_resolve
node_manager -.->|"installs package"| node_install
node_manager -.->|"runs package"| node_launch
node_resolve -.->|"queries index"| node_index
node_resolve -.->|"fetches package"| node_oci
node_install -.->|"pulls artifacts"| node_oci
node_oci -.->|"reads and writes"| node_registry
node_install -.->|"uses metadata"| node_package
node_cli -.->|"loads settings"| node_config
node_cli -.->|"uses project context"| node_project
node_launch -.->|"sets environment"| node_shell
node_cli -.->|"supports package signing"| node_sign
node_cli -.->|"supports attestations"| node_attest
node_cli -.->|"supports verification"| node_verify
node_sign -->|"publishes referrer"| node_oci
node_attest -->|"pushes referrer"| node_oci
node_verify -.->|"checks referrers"| node_oci
node_cli -.->|"supports announcements"| node_forge
node_cli -->|"classifies failures"| node_exit

click node_cli "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_cli/src/app.rs"
click node_manager "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_package_manager/src/tasks.rs"
click node_resolve "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_package_manager/src/tasks/resolve.rs"
click node_install "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_package_manager/src/tasks/install.rs"
click node_launch "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_package_manager/src/launch.rs"
click node_package "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_package/src/metadata/authoring.rs"
click node_oci "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_oci/src/client.rs"
click node_index "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_index/src/lib.rs"
click node_config "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_config/src/lib.rs"
click node_project "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_project/src/compose.rs"
click node_shell "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_shell/src/shell.rs"
click node_sign "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_sign/src/sign/pipeline.rs"
click node_attest "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_sign/src/attest/pipeline.rs"
click node_verify "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_sign/src/verify/pipeline.rs"
click node_forge "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_announce/src/forge.rs"
click node_exit "https://github.com/ocx-sh/ocx/blob/main/crates/ocx_cli/src/exit.rs"

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_commands,node_exit,node_user toneBlue
class node_manager,node_resolve,node_install,node_launch,node_package toneAmber
class node_oci,node_registry,node_index toneMint
class node_sign,node_attest,node_verify,node_forge toneRose
class node_config,node_project,node_shell toneIndigo
```

## Components

### CLI

- [Command interface](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_cli/src/app.rs): `crates/ocx_cli/src/app.rs`
- **Package commands**
- [Error classification](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_cli/src/exit.rs): `crates/ocx_cli/src/exit.rs`

### Package lifecycle

- [Package tasks](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_package_manager/src/tasks.rs): `crates/ocx_package_manager/src/tasks.rs`
- [Package resolution](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_package_manager/src/tasks/resolve.rs): `crates/ocx_package_manager/src/tasks/resolve.rs`
- [Install and select](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_package_manager/src/tasks/install.rs): `crates/ocx_package_manager/src/tasks/install.rs`
- [Execution environment](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_package_manager/src/launch.rs): `crates/ocx_package_manager/src/launch.rs`
- [Package metadata](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_package/src/metadata/authoring.rs): `crates/ocx_package/src/metadata/authoring.rs`

### Registry and indexes

- [OCI client](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_oci/src/client.rs): `crates/ocx_oci/src/client.rs`
- **OCI registries**
- [Package indexes](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_index/src/lib.rs): `crates/ocx_index/src/lib.rs`

### Supply-chain trust

- [Image signing](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_sign/src/sign/pipeline.rs): `crates/ocx_sign/src/sign/pipeline.rs`
- [Attestations](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_sign/src/attest/pipeline.rs): `crates/ocx_sign/src/attest/pipeline.rs`
- [Signature verification](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_sign/src/verify/pipeline.rs): `crates/ocx_sign/src/verify/pipeline.rs`
- [Forge announcements](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_announce/src/forge.rs): `crates/ocx_announce/src/forge.rs`

### Project and shell

- [Configuration](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_config/src/lib.rs): `crates/ocx_config/src/lib.rs`
- [Project context](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_project/src/compose.rs): `crates/ocx_project/src/compose.rs`
- [Shell integration](https://github.com/ocx-sh/ocx/blob/main/crates/ocx_shell/src/shell.rs): `crates/ocx_shell/src/shell.rs`

### Other components

- **Package user**

## Connections

- Package user → Command interface: runs command (evidence: `README.md`)
- Command interface → Package commands: dispatches (evidence: `crates/ocx_cli/src/app.rs`)
- Package commands → Package tasks: invokes tasks
- Package tasks → Package resolution: resolves package (evidence: `crates/ocx_package_manager/src/tasks.rs`)
- Package tasks → Install and select: installs package (evidence: `crates/ocx_package_manager/src/tasks.rs`)
- Package tasks → Execution environment: runs package
- Package resolution → Package indexes: queries index
- Package resolution → OCI client: fetches package
- Install and select → OCI client: pulls artifacts
- OCI client → OCI registries: reads and writes
- Install and select → Package metadata: uses metadata
- Command interface → Configuration: loads settings
- Command interface → Project context: uses project context
- Execution environment → Shell integration: sets environment
- Command interface → Image signing: supports package signing
- Command interface → Attestations: supports attestations
- Command interface → Signature verification: supports verification
- Image signing → OCI client: publishes referrer (evidence: `crates/ocx_sign/src/sign/pipeline.rs`)
- Attestations → OCI client: pushes referrer (evidence: `crates/ocx_sign/src/attest/pipeline.rs`)
- Signature verification → OCI client: checks referrers
- Command interface → Forge announcements: supports announcements
- Command interface → Error classification: classifies failures (evidence: `crates/ocx_cli/src/exit.rs`)