Skip to content
Rivet

Architecture

Rivet is a Cargo workspace. This page is the map: which crate owns what, which direction the dependencies point, and where to look when you want to change something. For why each boundary is where it is, read the architecture decision records.

Crates

Section titled “Crates”
Crate Owns
rivet-core Types, selection policy, secret-safety checks, the centralised file/symlink collector, plugin hook execution (rivet_core::hooks), the curated + Repology-derived cross-distro package map (rivet_core::packagemap), and the object-safe Platform/PackageManager/Backend/Plugin traits. Depends on no other rivet-* crate.
rivet-platform Distro detection (Arch, Debian/Ubuntu, Fedora/RHEL, openSUSE, NixOS, Void) and their native package managers (Pacman+AUR, APT, DNF, Zypper, nix profile, XBPS), plus the cross-cutting Snap/Flatpak managers and AppImage discovery. macOS adds Homebrew, MacPorts, and the Mac App Store.
rivet-backend Snapshot storage: GitBackend (default), FsBackend (local or mounted NAS), RcloneBackend (S3, B2, Drive, Dropbox, SFTP, WebDAV, …), and ResticBackend, selected via registry::build/resolve. Also policy persistence and reading a snapshot at the current worktree or a historical revision, including captured hook artifacts.
rivet-plugins The built-in, data-driven configuration groups: KDE Plasma, GNOME, Cinnamon, Xfce, Hyprland, Sway, niri, i3, shell/Git, terminal tools, Kitty, VS Code, Vim/Neovim, fonts/themes, user scripts. GNOME and Cinnamon additionally run a dconf export/import hook for settings that live outside any config file.
rivet-crypto age primitives: at-rest blob encryption for the fs/rclone backends, plus the vault surface (multi-recipient encryption, passphrase-wrapped identities). Pure crypto; owns no policy.
rivet-secretstores The SecretStore implementations behind the vault — the built-in age store (over rivet-crypto) and an optional sops store. Chosen per declared secret by sealing_store/unsealing_store.
rivet-cli The rivet binary: argument parsing, snapshot/restore orchestration, the vault subcommands, the terminal UI, and all terminal presentation.
rivet-pkgmap-gen Offline maintainer tool that turns a downloaded Repology export into rivet-core/packagemap/generated.toml. Not a runtime dependency.

Dependency direction

Section titled “Dependency direction”

Platform, backend, plugin, and secret-store crates depend on rivet-core, never the reverse. rivet-core holds the traits; the CLI wires concrete implementations together and hands them to core logic as &dyn / Box<dyn> trait objects.

That is the rule worth defending. It means adding a distro, a storage backend, or a configuration group never edits selection policy or the secret-safety checks — the two places where a mistake is expensive.

Where to look

Section titled “Where to look”
To change Start in
What gets captured or refused rivet-core (selection policy, secret checks)
Support for a new distro or package manager rivet-platform
A new snapshot destination rivet-backend
A new application’s config group rivet-plugins, or a user plugin — see Tracking & plugins
Command surface, output, TUI rivet-cli
Section titled “Related pages”