# sebt3/vynil architecture

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

- Interactive diagram: https://gitdiagram.com/sebt3/vynil
- Repository: https://github.com/sebt3/vynil

## Overview

Vynil is a Kubernetes distribution package manager: package authors build and validate packages, publish them as OCI images, and users install or manage system, service, and tenant instances through kubectl or controller reconciliation. The operator manages JukeBox package sources and instance resources; the agent provides package, lifecycle, template, and scanning commands. The README also describes signing, air-gapped workflows, and disaster recovery. Sampled excerpts confirm CLI dispatch, controller setup, and parts of the diagnostic server; some subsystem links are therefore left unspecified.

Main entry points: [`agent/src/service/mod.rs`](https://github.com/sebt3/vynil/blob/main/agent/src/service/mod.rs) (Instance lifecycle), [`agent/src/main.rs`](https://github.com/sebt3/vynil/blob/main/agent/src/main.rs) (Agent CLI), [`operator/src/manager.rs`](https://github.com/sebt3/vynil/blob/main/operator/src/manager.rs) (Operator manager), [`server/src/server.rs`](https://github.com/sebt3/vynil/blob/main/server/src/server.rs) (Diagnostic server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Package authoring"]
  node_agent_cli["Agent CLI<br/>[main.rs]"]
  node_package_build["Build packages<br/>[build.rs]"]
  node_package_ops["Package operations<br/>[mod.rs]"]
  node_package_lint["Package linting<br/>[lint.rs]"]
  node_scan["Package scanning<br/>[file_scan.rs]"]
end

subgraph group_runtime["Install and reconcile"]
  node_kubectl_plugin["kubectl plugin<br/>[main.rs]"]
  node_plugin_actions["CLI actions<br/>[actions.rs]"]
  node_operator["Operator manager<br/>[manager.rs]"]
  node_jukebox["JukeBox sources<br/>[jukebox.rs]"]
  node_instance_types["Instance resources<br/>[instanceservice.rs]"]
  node_agent_lifecycle["Instance lifecycle<br/>[mod.rs]"]
  node_system_lifecycle["System lifecycle<br/>[mod.rs]"]
  node_tenant_lifecycle["Tenant lifecycle<br/>[mod.rs]"]
end

subgraph group_platform["Kubernetes platform"]
  node_templates["Template rendering"]
  node_script_runtime["Rhai scripts<br/>[rhaihandler.rs]"]
end

subgraph group_observability["Diagnostics"]
  node_diag_server["Diagnostic server<br/>[server.rs]"]
  node_diag_auth["Auth and access<br/>[authz.rs]"]
  node_diag_collect["Cluster collectors<br/>[mod.rs]"]
  node_operator_metrics["Operator metrics<br/>[metrics.rs]"]
end

node_authors(("Package authors"))
node_kubectl_user(("kubectl user"))
node_oci[("OCI registry")]
node_kubernetes[("Kubernetes API")]
node_diagnostic_client(("Diagnostic client"))

node_authors -->|"invoke commands"| node_agent_cli
node_agent_cli -->|"dispatches build"| node_package_build
node_agent_cli -->|"dispatches package"| node_package_ops
node_agent_cli -->|"dispatches lint"| node_package_lint
node_agent_cli -->|"dispatches scan"| node_scan
node_package_build -->|"publishes image"| node_oci
node_package_ops -->|"reads or updates"| node_oci
node_kubectl_user -->|"invokes commands"| node_kubectl_plugin
node_kubectl_plugin -->|"dispatches actions"| node_plugin_actions
node_plugin_actions -->|"manages resources"| node_kubernetes
node_operator -->|"watches resources"| node_kubernetes
node_operator -->|"loads source state"| node_jukebox
node_operator -->|"reconciles instances"| node_instance_types
node_operator -->|"runs agent work"| node_agent_lifecycle
node_agent_lifecycle -->|"supports system work"| node_system_lifecycle
node_agent_lifecycle -->|"supports tenant work"| node_tenant_lifecycle
node_agent_lifecycle -->|"renders resources"| node_templates
node_agent_lifecycle -->|"evaluates scripts"| node_script_runtime
node_agent_lifecycle -->|"applies resources"| node_kubernetes
node_diagnostic_client -->|"requests diagnostics"| node_diag_server
node_diag_server -->|"checks access"| node_diag_auth
node_diag_server -->|"collects cluster data"| node_diag_collect
node_diag_collect -->|"reads cluster state"| node_kubernetes
node_operator_metrics -->|"exposes metrics"| node_operator

click node_agent_cli "https://github.com/sebt3/vynil/blob/main/agent/src/main.rs"
click node_package_build "https://github.com/sebt3/vynil/blob/main/agent/src/package/build.rs"
click node_package_ops "https://github.com/sebt3/vynil/blob/main/agent/src/package/mod.rs"
click node_package_lint "https://github.com/sebt3/vynil/blob/main/agent/src/package/lint.rs"
click node_scan "https://github.com/sebt3/vynil/blob/main/agent/src/boxes/file_scan.rs"
click node_kubectl_plugin "https://github.com/sebt3/vynil/blob/main/kubectl-vynil/src/main.rs"
click node_plugin_actions "https://github.com/sebt3/vynil/blob/main/kubectl-vynil/src/actions.rs"
click node_operator "https://github.com/sebt3/vynil/blob/main/operator/src/manager.rs"
click node_jukebox "https://github.com/sebt3/vynil/blob/main/common/src/jukebox.rs"
click node_instance_types "https://github.com/sebt3/vynil/blob/main/common/src/instanceservice.rs"
click node_agent_lifecycle "https://github.com/sebt3/vynil/blob/main/agent/src/service/mod.rs"
click node_system_lifecycle "https://github.com/sebt3/vynil/blob/main/agent/src/system/mod.rs"
click node_tenant_lifecycle "https://github.com/sebt3/vynil/blob/main/agent/src/tenant/mod.rs"
click node_templates "https://github.com/sebt3/vynil/blob/main/common/src/handlebarshandler.rs"
click node_script_runtime "https://github.com/sebt3/vynil/blob/main/common/src/rhaihandler.rs"
click node_diag_server "https://github.com/sebt3/vynil/blob/main/server/src/server.rs"
click node_diag_auth "https://github.com/sebt3/vynil/blob/main/server/src/authz.rs"
click node_diag_collect "https://github.com/sebt3/vynil/blob/main/server/src/collect/mod.rs"
click node_operator_metrics "https://github.com/sebt3/vynil/blob/main/operator/src/metrics.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_agent_cli,node_package_build,node_package_ops,node_package_lint,node_scan,node_kubectl_user,node_diagnostic_client toneBlue
class node_kubectl_plugin,node_plugin_actions,node_operator,node_jukebox,node_instance_types,node_agent_lifecycle,node_system_lifecycle,node_tenant_lifecycle,node_oci,node_kubernetes toneAmber
class node_templates,node_script_runtime toneMint
class node_diag_server,node_diag_auth,node_diag_collect,node_operator_metrics toneRose
class node_authors toneIndigo
```

## Components

### Package authoring

- [Agent CLI](https://github.com/sebt3/vynil/blob/main/agent/src/main.rs): `agent/src/main.rs`
- [Build packages](https://github.com/sebt3/vynil/blob/main/agent/src/package/build.rs): `agent/src/package/build.rs`
- [Package operations](https://github.com/sebt3/vynil/blob/main/agent/src/package/mod.rs): `agent/src/package/mod.rs`
- [Package linting](https://github.com/sebt3/vynil/blob/main/agent/src/package/lint.rs): `agent/src/package/lint.rs`
- [Package scanning](https://github.com/sebt3/vynil/blob/main/agent/src/boxes/file_scan.rs): `agent/src/boxes/file_scan.rs`

### Install and reconcile

- [kubectl plugin](https://github.com/sebt3/vynil/blob/main/kubectl-vynil/src/main.rs): `kubectl-vynil/src/main.rs`
- [CLI actions](https://github.com/sebt3/vynil/blob/main/kubectl-vynil/src/actions.rs): `kubectl-vynil/src/actions.rs`
- [Operator manager](https://github.com/sebt3/vynil/blob/main/operator/src/manager.rs): `operator/src/manager.rs`
- [JukeBox sources](https://github.com/sebt3/vynil/blob/main/common/src/jukebox.rs): `common/src/jukebox.rs`
- [Instance resources](https://github.com/sebt3/vynil/blob/main/common/src/instanceservice.rs): `common/src/instanceservice.rs`
- [Instance lifecycle](https://github.com/sebt3/vynil/blob/main/agent/src/service/mod.rs): `agent/src/service/mod.rs`
- [System lifecycle](https://github.com/sebt3/vynil/blob/main/agent/src/system/mod.rs): `agent/src/system/mod.rs`
- [Tenant lifecycle](https://github.com/sebt3/vynil/blob/main/agent/src/tenant/mod.rs): `agent/src/tenant/mod.rs`

### Kubernetes platform

- [Template rendering](https://github.com/sebt3/vynil/blob/main/common/src/handlebarshandler.rs): `common/src/handlebarshandler.rs`
- [Rhai scripts](https://github.com/sebt3/vynil/blob/main/common/src/rhaihandler.rs): `common/src/rhaihandler.rs`

### Diagnostics

- [Diagnostic server](https://github.com/sebt3/vynil/blob/main/server/src/server.rs): `server/src/server.rs`
- [Auth and access](https://github.com/sebt3/vynil/blob/main/server/src/authz.rs): `server/src/authz.rs`
- [Cluster collectors](https://github.com/sebt3/vynil/blob/main/server/src/collect/mod.rs): `server/src/collect/mod.rs`
- [Operator metrics](https://github.com/sebt3/vynil/blob/main/operator/src/metrics.rs): `operator/src/metrics.rs`

### Other components

- **Package authors**
- **kubectl user**
- **OCI registry**
- **Kubernetes API**
- **Diagnostic client**

## Connections

- Package authors → Agent CLI: invoke commands
- Agent CLI → Build packages: dispatches build
- Agent CLI → Package operations: dispatches package
- Agent CLI → Package linting: dispatches lint
- Agent CLI → Package scanning: dispatches scan
- Build packages → OCI registry: publishes image
- Package operations → OCI registry: reads or updates
- kubectl user → kubectl plugin: invokes commands
- kubectl plugin → CLI actions: dispatches actions
- CLI actions → Kubernetes API: manages resources
- Operator manager → Kubernetes API: watches resources
- Operator manager → JukeBox sources: loads source state
- Operator manager → Instance resources: reconciles instances
- Operator manager → Instance lifecycle: runs agent work
- Instance lifecycle → System lifecycle: supports system work
- Instance lifecycle → Tenant lifecycle: supports tenant work
- Instance lifecycle → Template rendering: renders resources
- Instance lifecycle → Rhai scripts: evaluates scripts
- Instance lifecycle → Kubernetes API: applies resources
- Diagnostic client → Diagnostic server: requests diagnostics
- Diagnostic server → Auth and access: checks access
- Diagnostic server → Cluster collectors: collects cluster data
- Cluster collectors → Kubernetes API: reads cluster state
- Operator metrics → Operator manager: exposes metrics