# a2-ai/rv architecture

> Architecture diagram of the GitHub repository a2-ai/rv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/a2-ai/rv
- Repository: https://github.com/a2-ai/rv

## Overview

##### Project type and purpose
- This is a command-line application written in Rust named “rv” for reproducible, declarative management of R package libraries. It is an open-source developer tool (no frontend/UI beyond the CLI) that computes a lock-file and synchronizes an R project’s package state against TOML config, remote CRAN-style repos, local git repos, and the local filesystem.

##### File structure
- Top-level:
- Cargo.toml/Cargo.lock – Rust project manifest and dependency lock
- src/ – all Rust code
- docs/ – Markdown documentation
- example_projects/ – sample configs for demonstration
- scripts/, .github/, justfile, rustwrap.yaml – CI, release, install, convenience scripts
- Inside src/:
- main.rs – binary entrypoint
- lib.rs – shared library glue (when built as crate)
- cli/ – CLI parsing and command definitions (init, add, migrate, tree, etc.)
- config.rs & configure.rs – load and validate rproject.toml
- resolver/ – dependency resolution (SAT solver, rules, lockfile handling)
- sync/ – plan and sync execution (install/remove/link packages)
- cache/ – disk cache of downloads/artifacts
- git/, http.rs – abstractions for fetching packages from git or HTTP repos
- r_cmd.rs, renv.rs, system_info.rs – shelling out to R, handling renv lockfiles, collecting system requirements
- package/ – parsing and representing DESCRIPTION files, version constraints
- repository.rs & repository_urls.rs – representation of remote repo endpoints
- lockfile.rs – reading and writing the rv.lock file
- fs.rs & utils.rs – filesystem operations
- Tests and snapshots exist alongside modules to drive unit and snapshot testing.

##### Insights from README
- Two primary top-level commands:
- rv plan – dry-run resolution and plan
- rv sync – execute installs, removals, updates
- Uses rproject.toml for declarative project state (R version, repos, dependencies).
- Integrates with R itself via shell commands and can install recommended or suggested packages.

a. Main components:
- CLI Frontend
- Config Loader (rproject.toml)
- Dependency Resolver
- Lockfile Manager
- Cache Manager (disk cache)
- Sync Engine
- Package Fetchers (Git, HTTP)
- File System Layer
- R Runner (r_cmd integration)
- System Info / Requirements
- External Services: remote CRAN repos, Git hosts
b. Relationships and interactions:
1. User invokes CLI → CLI Frontend
2. CLI parses arguments → Config Loader
3. Config Loader emits ProjectState → passed to Resolver
4. Resolver consults Lockfile Manager & remote repos (via Package Fetchers) → computes BuildPlan
5. BuildPlan handed to Sync Engine →
– uses Cache Manager to download artifacts
– uses Git/HTTP fetchers to pull source/binaries
– uses File System Layer to place packages in library
– invokes R Runner to install/build locally as needed
6. Sync Engine updates Lockfile Manager with concrete versions
c. Architectural patterns / design principles:
- Separation of concerns: CLI parsing vs. core logic vs. IO
- Modular subsystems: resolver, sync, cache, fetchers
- Declarative config → imperative plan & execution
- Snapshot testing ensures reproducibility
d. Key technologies & libraries:
- Rust (async IO likely via tokio or std threads)
- Clap or similar for CLI
- SAT solver approach in resolver
- Filesystem abstractions (std::fs)
- HTTP (reqwest/hyper) and Git (git2 or shelling out)
- Integration with external R process

##### Detailed breakdown
- Layer 1: CLI Frontend
- Layer 2: Config Loader + System Info
- Layer 3: Dependency Resolver + Lockfile Manager
- Layer 4: Sync Engine
- Sub‐layer: Cache Manager
- Sub‐layer: Package Fetchers (Git, HTTP)
- Sub‐layer: FileSystem Writer
- Sub‐layer: R Runner
- External: CRAN repos, Git hosts, local filesystem

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: CLI Frontend
    CLI["CLI Frontend"]:::stateless
    click CLI "https://github.com/a2-ai/rv/tree/main/src/cli"

    %% Layer 2: Config Loader + System Info
    subgraph "Configuration Layer"
        Config["Config Loader"]:::stateless
        click Config "https://github.com/a2-ai/rv/blob/main/src/config.rs"
        SysInfo["System Info/Requirements"]:::stateless
        click SysInfo "https://github.com/a2-ai/rv/blob/main/src/system_info.rs"
    end

    %% Layer 3: Resolver + Lockfile
    subgraph "Resolution Layer"
        Resolver["Dependency Resolver"]:::stateless
        click Resolver "https://github.com/a2-ai/rv/blob/main/src/resolver/mod.rs"
        Lockfile["Lockfile Manager"]:::io
        click Lockfile "https://github.com/a2-ai/rv/blob/main/src/lockfile.rs"
    end

    %% Layer 4: Sync Engine and Subsystems
    subgraph "Sync Engine" 
        direction TB
        SyncEng["Sync Engine"]:::stateless
        click SyncEng "https://github.com/a2-ai/rv/blob/main/src/sync/mod.rs"

        subgraph "Cache Manager" 
            Cache["Cache Manager"]:::io
            click Cache "https://github.com/a2-ai/rv/blob/main/src/cache/mod.rs"
        end

        subgraph "Package Fetchers"
            direction TB
            GitFetch["Git Fetcher"]:::io
            click GitFetch "https://github.com/a2-ai/rv/blob/main/src/sync/sources/git.rs"
            HTTPFetch["HTTP Fetcher"]:::io
            click HTTPFetch "https://github.com/a2-ai/rv/blob/main/src/http.rs"
            RepoFetch["Repository Fetcher"]:::io
            click RepoFetch "https://github.com/a2-ai/rv/blob/main/src/sync/sources/repositories.rs"
            LocalFetch["Local Source Fetcher"]:::io
            click LocalFetch "https://github.com/a2-ai/rv/blob/main/src/sync/sources/local.rs"
        end

        FS["File System Layer"]:::io
        click FS "https://github.com/a2-ai/rv/blob/main/src/fs.rs"

        RRunner["R Runner"]:::io
        click RRunner "https://github.com/a2-ai/rv/blob/main/src/r_cmd.rs"
    end

    %% External Services
    CRAN["CRAN Repositories"]:::external
    GitHosts["Git Hosts"]:::external
    LocalFS["Local File System"]:::external

    %% Connections
    CLI -->|"invokes"| Config
    CLI -->|"invokes"| SysInfo
    Config -->|"emits ProjectState"| Resolver
    SysInfo --> Resolver
    Resolver -->|"reads/writes"| Lockfile
    Resolver -->|"computes BuildPlan"| SyncEng
    SyncEng -->|"uses"| Cache
    SyncEng -->|"fetches via"| GitFetch
    SyncEng -->|"fetches via"| HTTPFetch
    SyncEng -->|"fetches via"| RepoFetch
    SyncEng -->|"fetches via"| LocalFetch
    SyncEng -->|"writes"| FS
    SyncEng -->|"invokes"| RRunner
    GitFetch --> GitHosts
    HTTPFetch --> CRAN
    RepoFetch --> CRAN
    LocalFetch --> LocalFS

    %% Styles
    classDef stateless fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef io fill:#ccccff,stroke:#333,stroke-width:1px
    classDef external fill:#ffcccc,stroke:#333,stroke-width:1px
```
