# gblach/reflicate architecture

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

- Interactive diagram: https://gitdiagram.com/gblach/reflicate
- Repository: https://github.com/gblach/reflicate

## Overview

##### Project type and purpose
- This is a Rust-based command-line utility (CLI) named “Reflicate.”
- Its goal is to deduplicate files in specified directories by creating reflinks or hardlinks between identical files, using hashing and an index file for speed.

##### File structure
- Top-level:
- Cargo.toml, Cargo.lock: Rust project metadata and dependencies.
- src/: contains Rust source modules.
- systemd/: contains service/unit files for periodic execution.
- src/:
- main.rs – entry-point: parses CLI arguments, dispatches modes (dry-run, paranoid, indexfile).
- index.rs – indexfile management: read/write CDB+msgpack, track file metadata and hashes.
- utils.rs – hashing, file enumeration, reflink/hardlink wrappers.
- (possibly index.rs is named indexfile module, note utils.rs and indexfile functionality in README)
- systemd/:
- repliclate.service & repliclate.timer: example units to automate runs via systemd user timers.

##### README for additional insights
- Core flow: scan directories → collect file size & timestamps → compute blake3 (and xxhash in paranoid) → compare to index or peers → issue reflink/hardlink operations → update indexfile.
- External dependency: filesystem must support reflinks (e.g., XFS); fallback to hardlinks.
- Indexfile: constant-time lookup (CDB), serialization via msgpack.

##### Essential details to capture
- That indexfile both reads and writes metadata & hashes.
- Decision branch for hardlink vs reflink.
- Incremental optimization: skip hashing unchanged files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Triggers
    User["User"]:::external
    SysService["Systemd Service"]:::external
    SysTimer["Systemd Timer"]:::external

    %% Core Binary Subgraph
    subgraph "Reflicate CLI"
        direction TB
        CLIParser["CLI Parser"]:::core
        DirScanner["Directory Scanner"]:::core
        HashEngine["Hashing Engine"]:::core
        DedupEngine["Deduplication Engine"]:::core
        IndexManager["Indexfile Manager\n(CDB + msgpack)"]:::persistence
        FSInterface["Filesystem Interface\n(reflink vs. hardlink)"]:::external
        CLIOutput["CLI Output\n(summary)"]:::core
    end

    %% Trigger Flows
    User -->|invoke| CLIParser
    SysService -->|timer start| CLIParser
    SysTimer -->|triggers service| SysService

    %% Core Workflow
    CLIParser -->|scan dirs| DirScanner
    DirScanner -->|file metadata| HashEngine
    DirScanner -->|file metadata| IndexManager

    HashEngine -->|"CDB lookup"| IndexManager
    IndexManager -->|"existing hash"| HashEngine
    HashEngine -->|hash results| DedupEngine

    DedupEngine -->|decide reflink/hardlink| FSInterface
    FSInterface -->|update index| IndexManager
    DedupEngine -->|results| CLIOutput

    %% Click Events
    click CLIParser "https://github.com/gblach/reflicate/blob/main/src/main.rs"
    click DirScanner "https://github.com/gblach/reflicate/blob/main/src/utils.rs"
    click HashEngine "https://github.com/gblach/reflicate/blob/main/src/utils.rs"
    click IndexManager "https://github.com/gblach/reflicate/blob/main/src/index.rs"
    click DedupEngine "https://github.com/gblach/reflicate/blob/main/src/main.rs"
    click FSInterface "https://github.com/gblach/reflicate/blob/main/src/utils.rs"
    click SysService "https://github.com/gblach/reflicate/blob/main/systemd/reflicate.service"
    click SysTimer "https://github.com/gblach/reflicate/blob/main/systemd/reflicate.timer"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#024a86,color:#024a86;
    classDef persistence fill:#DFFFE0,stroke:#4a7c0c,color:#4a7c0c;
    classDef external fill:#FFD8A8,stroke:#a64d00,color:#a64d00;
```
