# tylerbutler/repoverlay architecture

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

- Interactive diagram: https://gitdiagram.com/tylerbutler/repoverlay
- Repository: https://github.com/tylerbutler/repoverlay

## Overview

repoverlay is a Rust CLI for defining reusable overlays and applying their files to a Git repository without committing them. The primary workflow is to discover or select an overlay, resolve its local or remote source, apply files into the working tree, and track state while excluding applied files from Git. Separate capabilities manage sources, caches, the in-repository library, and experimental profiles with harness instructions and plugins. Relationships among unsampled command implementations are limited to documented workflows and SOURCE INDEX references.

Main entry points: [`src/resolve.rs`](https://github.com/tylerbutler/repoverlay/blob/main/src/resolve.rs) (Source resolution), [`src/cli/mod.rs`](https://github.com/tylerbutler/repoverlay/blob/main/src/cli/mod.rs) (Command dispatch), [`src/profile_plan.rs`](https://github.com/tylerbutler/repoverlay/blob/main/src/profile_plan.rs) (Profile planning), [`src/cli/commands/browse.rs`](https://github.com/tylerbutler/repoverlay/blob/main/src/cli/commands/browse.rs) (Browse overlays)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and selection"]
  node_cli["Command dispatch<br/>[mod.rs]"]
  node_browse["Browse overlays<br/>[browse.rs]"]
  node_selection["Interactive selection<br/>[selection.rs]"]
end

subgraph group_overlays["Overlay lifecycle"]
  node_create["Create overlays<br/>[create.rs]"]
  node_edit["Edit overlays<br/>[edit.rs]"]
  node_sync["Sync overlays<br/>[sync.rs]"]
  node_apply["Apply and manage<br/>[mod.rs]"]
  node_detection["File detection<br/>[detection.rs]"]
  node_gitexclude["Git exclusions<br/>[git_exclude.rs]"]
  node_status["Overlay status<br/>[status.rs]"]
  node_restore["Restore overlays<br/>[restore.rs]"]
  node_state[("Overlay state<br/>[state.rs]")]
end

subgraph group_sources["Sources and storage"]
  node_resolve["Source resolution<br/>[resolve.rs]"]
  node_references["Overlay references<br/>[reference.rs]"]
  node_sources["Source registry<br/>[sources.rs]"]
  node_cache[("Repository cache<br/>[cache.rs]")]
  node_github["GitHub parsing<br/>[github.rs]"]
  node_upstream["Upstream updates<br/>[upstream.rs]"]
  node_overlayrepo[("Shared overlay repo<br/>[overlay_repo.rs]")]
  node_library[("In-repo library<br/>[library.rs]")]
end

subgraph group_profiles["Profiles and harnesses"]
  node_config["Configuration<br/>[config.rs]"]
  node_profile["Profile definitions<br/>[profile.rs]"]
  node_plan["Profile planning<br/>[profile_plan.rs]"]
  node_plugin["Plugin resolution<br/>[plugin.rs]"]
  node_applicators["Harness applicators<br/>[mod.rs]"]
  node_claude["Claude integration<br/>[claude.rs]"]
  node_copilot["Copilot integration<br/>[copilot.rs]"]
end

node_user(("CLI user"))

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches to"| node_browse
node_cli -->|"dispatches to"| node_create
node_cli -->|"dispatches to"| node_edit
node_cli -->|"dispatches to"| node_sync
node_browse -->|"uses"| node_selection
node_browse -->|"resolves sources"| node_resolve
node_browse -->|"applies selection"| node_apply
node_create -->|"uses"| node_selection
node_edit -->|"uses"| node_detection
node_edit -->|"uses"| node_selection
node_sync -->|"uses"| node_selection
node_sync -->|"reuses logic"| node_create
node_apply -->|"persists state"| node_state
node_apply -->|"excludes files"| node_gitexclude
node_apply -->|"caches remote source"| node_cache
node_status -->|"reads state"| node_state
node_restore -.->|"restores from state"| node_state
node_resolve -->|"parses GitHub sources"| node_github
node_resolve -->|"uses registry"| node_sources
node_resolve -->|"uses cached repos"| node_cache
node_resolve -->|"parses references"| node_references
node_resolve -->|"uses overlay repo"| node_overlayrepo
node_resolve -->|"uses library"| node_library
node_sources -->|"manages cached sources"| node_cache
node_upstream -->|"uses GitHub data"| node_github
node_cli -->|"loads configuration"| node_config
node_config -->|"defines profiles"| node_profile
node_plan -->|"plans profiles"| node_profile
node_plan -->|"resolves plugins"| node_plugin
node_plan -->|"delegates application"| node_applicators
node_applicators -->|"dispatches harness"| node_claude
node_applicators -->|"dispatches harness"| node_copilot
node_plan -->|"uses repo state"| node_state
node_plugin -->|"resolves remote assets"| node_cache

click node_cli "https://github.com/tylerbutler/repoverlay/blob/main/src/cli/mod.rs"
click node_browse "https://github.com/tylerbutler/repoverlay/blob/main/src/cli/commands/browse.rs"
click node_selection "https://github.com/tylerbutler/repoverlay/blob/main/src/selection.rs"
click node_create "https://github.com/tylerbutler/repoverlay/blob/main/src/cli/commands/create.rs"
click node_edit "https://github.com/tylerbutler/repoverlay/blob/main/src/cli/commands/edit.rs"
click node_sync "https://github.com/tylerbutler/repoverlay/blob/main/src/cli/commands/sync.rs"
click node_apply "https://github.com/tylerbutler/repoverlay/blob/main/src/cli/mod.rs"
click node_detection "https://github.com/tylerbutler/repoverlay/blob/main/src/detection.rs"
click node_gitexclude "https://github.com/tylerbutler/repoverlay/blob/main/src/git_exclude.rs"
click node_status "https://github.com/tylerbutler/repoverlay/blob/main/src/status.rs"
click node_restore "https://github.com/tylerbutler/repoverlay/blob/main/src/restore.rs"
click node_state "https://github.com/tylerbutler/repoverlay/blob/main/src/state.rs"
click node_resolve "https://github.com/tylerbutler/repoverlay/blob/main/src/resolve.rs"
click node_references "https://github.com/tylerbutler/repoverlay/blob/main/src/reference.rs"
click node_sources "https://github.com/tylerbutler/repoverlay/blob/main/src/sources.rs"
click node_cache "https://github.com/tylerbutler/repoverlay/blob/main/src/cache.rs"
click node_github "https://github.com/tylerbutler/repoverlay/blob/main/src/github.rs"
click node_upstream "https://github.com/tylerbutler/repoverlay/blob/main/src/upstream.rs"
click node_overlayrepo "https://github.com/tylerbutler/repoverlay/blob/main/src/overlay_repo.rs"
click node_library "https://github.com/tylerbutler/repoverlay/blob/main/src/library.rs"
click node_config "https://github.com/tylerbutler/repoverlay/blob/main/src/config.rs"
click node_profile "https://github.com/tylerbutler/repoverlay/blob/main/src/profile.rs"
click node_plan "https://github.com/tylerbutler/repoverlay/blob/main/src/profile_plan.rs"
click node_plugin "https://github.com/tylerbutler/repoverlay/blob/main/src/plugin.rs"
click node_applicators "https://github.com/tylerbutler/repoverlay/blob/main/src/profile_applicators/mod.rs"
click node_claude "https://github.com/tylerbutler/repoverlay/blob/main/src/profile_applicators/claude.rs"
click node_copilot "https://github.com/tylerbutler/repoverlay/blob/main/src/profile_applicators/copilot.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_browse,node_selection,node_user toneBlue
class node_create,node_edit,node_sync,node_apply,node_detection,node_gitexclude,node_status,node_restore,node_state toneAmber
class node_resolve,node_references,node_sources,node_cache,node_github,node_upstream,node_overlayrepo,node_library toneMint
class node_config,node_profile,node_plan,node_plugin,node_applicators,node_claude,node_copilot toneRose
```

## Components

### CLI and selection

- [Command dispatch](https://github.com/tylerbutler/repoverlay/blob/main/src/cli/mod.rs): `src/cli/mod.rs`
- [Browse overlays](https://github.com/tylerbutler/repoverlay/blob/main/src/cli/commands/browse.rs): `src/cli/commands/browse.rs`
- [Interactive selection](https://github.com/tylerbutler/repoverlay/blob/main/src/selection.rs): `src/selection.rs`

### Overlay lifecycle

- [Create overlays](https://github.com/tylerbutler/repoverlay/blob/main/src/cli/commands/create.rs): `src/cli/commands/create.rs`
- [Edit overlays](https://github.com/tylerbutler/repoverlay/blob/main/src/cli/commands/edit.rs): `src/cli/commands/edit.rs`
- [Sync overlays](https://github.com/tylerbutler/repoverlay/blob/main/src/cli/commands/sync.rs): `src/cli/commands/sync.rs`
- [Apply and manage](https://github.com/tylerbutler/repoverlay/blob/main/src/cli/mod.rs): `src/cli/mod.rs`
- [File detection](https://github.com/tylerbutler/repoverlay/blob/main/src/detection.rs): `src/detection.rs`
- [Git exclusions](https://github.com/tylerbutler/repoverlay/blob/main/src/git_exclude.rs): `src/git_exclude.rs`
- [Overlay status](https://github.com/tylerbutler/repoverlay/blob/main/src/status.rs): `src/status.rs`
- [Restore overlays](https://github.com/tylerbutler/repoverlay/blob/main/src/restore.rs): `src/restore.rs`
- [Overlay state](https://github.com/tylerbutler/repoverlay/blob/main/src/state.rs): `src/state.rs`

### Sources and storage

- [Source resolution](https://github.com/tylerbutler/repoverlay/blob/main/src/resolve.rs): `src/resolve.rs`
- [Overlay references](https://github.com/tylerbutler/repoverlay/blob/main/src/reference.rs): `src/reference.rs`
- [Source registry](https://github.com/tylerbutler/repoverlay/blob/main/src/sources.rs): `src/sources.rs`
- [Repository cache](https://github.com/tylerbutler/repoverlay/blob/main/src/cache.rs): `src/cache.rs`
- [GitHub parsing](https://github.com/tylerbutler/repoverlay/blob/main/src/github.rs): `src/github.rs`
- [Upstream updates](https://github.com/tylerbutler/repoverlay/blob/main/src/upstream.rs): `src/upstream.rs`
- [Shared overlay repo](https://github.com/tylerbutler/repoverlay/blob/main/src/overlay_repo.rs): `src/overlay_repo.rs`
- [In-repo library](https://github.com/tylerbutler/repoverlay/blob/main/src/library.rs): `src/library.rs`

### Profiles and harnesses

- [Configuration](https://github.com/tylerbutler/repoverlay/blob/main/src/config.rs): `src/config.rs`
- [Profile definitions](https://github.com/tylerbutler/repoverlay/blob/main/src/profile.rs): `src/profile.rs`
- [Profile planning](https://github.com/tylerbutler/repoverlay/blob/main/src/profile_plan.rs): `src/profile_plan.rs`
- [Plugin resolution](https://github.com/tylerbutler/repoverlay/blob/main/src/plugin.rs): `src/plugin.rs`
- [Harness applicators](https://github.com/tylerbutler/repoverlay/blob/main/src/profile_applicators/mod.rs): `src/profile_applicators/mod.rs`
- [Claude integration](https://github.com/tylerbutler/repoverlay/blob/main/src/profile_applicators/claude.rs): `src/profile_applicators/claude.rs`
- [Copilot integration](https://github.com/tylerbutler/repoverlay/blob/main/src/profile_applicators/copilot.rs): `src/profile_applicators/copilot.rs`

### Other components

- **CLI user**

## Connections

- CLI user → Command dispatch: runs commands (evidence: `README.md`)
- Command dispatch → Browse overlays: dispatches to
- Command dispatch → Create overlays: dispatches to (evidence: `src/cli/mod.rs`)
- Command dispatch → Edit overlays: dispatches to (evidence: `src/cli/mod.rs`)
- Command dispatch → Sync overlays: dispatches to (evidence: `src/cli/mod.rs`)
- Browse overlays → Interactive selection: uses (evidence: `src/cli/commands/browse.rs`)
- Browse overlays → Source resolution: resolves sources (evidence: `src/cli/commands/browse.rs`)
- Browse overlays → Apply and manage: applies selection (evidence: `README.md`)
- Create overlays → Interactive selection: uses (evidence: `src/cli/commands/create.rs`)
- Edit overlays → File detection: uses (evidence: `src/cli/commands/edit.rs`)
- Edit overlays → Interactive selection: uses (evidence: `src/cli/commands/edit.rs`)
- Sync overlays → Interactive selection: uses (evidence: `src/cli/commands/sync.rs`)
- Sync overlays → Create overlays: reuses logic (evidence: `src/cli/commands/sync.rs`)
- Apply and manage → Overlay state: persists state (evidence: `src/cli/mod.rs`)
- Apply and manage → Git exclusions: excludes files (evidence: `README.md`)
- Apply and manage → Repository cache: caches remote source (evidence: `README.md`)
- Overlay status → Overlay state: reads state
- Restore overlays → Overlay state: restores from state
- Source resolution → GitHub parsing: parses GitHub sources (evidence: `src/resolve.rs`)
- Source resolution → Source registry: uses registry (evidence: `src/resolve.rs`)
- Source resolution → Repository cache: uses cached repos (evidence: `src/resolve.rs`)
- Source resolution → Overlay references: parses references (evidence: `src/resolve.rs`)
- Source resolution → Shared overlay repo: uses overlay repo (evidence: `src/resolve.rs`)
- Source resolution → In-repo library: uses library (evidence: `src/resolve.rs`)
- Source registry → Repository cache: manages cached sources (evidence: `src/sources.rs`)
- Upstream updates → GitHub parsing: uses GitHub data (evidence: `src/upstream.rs`)
- Command dispatch → Configuration: loads configuration (evidence: `src/cli/mod.rs`)
- Configuration → Profile definitions: defines profiles (evidence: `src/config.rs`)
- Profile planning → Profile definitions: plans profiles (evidence: `src/profile_plan.rs`)
- Profile planning → Plugin resolution: resolves plugins (evidence: `src/profile_plan.rs`)
- Profile planning → Harness applicators: delegates application (evidence: `src/profile_plan.rs`)
- Harness applicators → Claude integration: dispatches harness (evidence: `src/profile_applicators/mod.rs`)
- Harness applicators → Copilot integration: dispatches harness (evidence: `src/profile_applicators/mod.rs`)
- Profile planning → Overlay state: uses repo state (evidence: `src/profile_plan.rs`)
- Plugin resolution → Repository cache: resolves remote assets (evidence: `src/plugin.rs`)
