Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
62 lines (47 loc) · 3.23 KB

ARCHITECTURE.md

File metadata and controls

62 lines (47 loc) · 3.23 KB

gravityfile Architecture

gravityfile is designed as a modular, high-performance system for file system exploration and analysis.

Core Design Principles

  1. Concurrency First: Every core module is built with parallelization as a first-class citizen using tokio, rayon, and jwalk.
  2. Memory Efficiency: Massive file systems are handled by minimizing heap allocations. CompactString and boxed optional fields (like content_hash) ensure low memory pressure.
  3. Unified State: A single, source-of-truth FileTree structure powers all views (Usage, Duplicates, Age, Treemap).
  4. Asynchronous TUI: The UI never blocks on I/O. Background tasks (scanning, hashing, analysis) communicate with the main loop via MPSC channels.

🏗️ Crate Overview

gravityfile-core

The heartbeat of the system.

  • FileNode: The fundamental unit of the tree. Features id-based lookups and lazy-loaded attributes.
  • FileTree: A high-performance container for nodes. Includes advanced statistics tracking.
  • Error Types: Unified error handling across all crates.

gravityfile-scan

The high-speed traversal engine.

  • JwalkScanner: Implements parallel directory traversal with customizable ignore rules (e.g., .gitignore).
  • InodeTracker: Prevents double-counting hardlinks across a single device by tracking (inode, device) pairs.
  • Git Integration: Uses libgit2 (via git2-rs) to detect repository status in real-time.

gravityfile-analyze

The intelligence layer.

  • Duplicate Detection: Uses a 3-phase algorithm for efficiency:
    1. Size Matching: Instant filtering of unique-sized files.
    2. Partial Hashing: Reads only the first and last 4KB of size-matched candidates.
    3. Full BLAKE3: Only performs full cryptographic hashes on final candidate groups.
  • Age Analysis: Computes the distribution of file ages and identifies "stale" directories.

gravityfile-ops

The file operation and safety engine.

  • OperationExecutor: Orchestrates copy, move, rename, and delete tasks.
  • Conflict Resolution: Implements interactive policies (Overwrite, Rename, Skip) for destination collisions.
  • Undo System: Maintains a rolling log of reversible operations (excluding permanent deletions).

gravityfile-tui

The interactive user interface.

  • Layouts:
    • Tree: Classical hierarchical view.
    • Miller Columns: Ranger-style navigation for deep drill-downs.
    • Treemap: Squarified space-filling visualization for rapid disk usage identification.
  • Rendering: Highly optimized ratatui integration with diff-based drawing and deferred updates.

🚀 Performance Benchmarks (Typical)

  • Traversal: ~500k files/sec (SSD, 12-core CPU).
  • Memory Consumption: ~120MB per 1M nodes.
  • Duplicate Detection: Scans 100GB of data for duplicates in <15s (I/O limited).

🛡️ Security Model

  • Sandboxed Plugins: Third-party extensions run in isolated environments with restricted FS access.
  • Safe Operations: Destructive operations default to Trash (via the trash crate) rather than permanent deletion.
  • No-Root Execution: gravityfile is designed to run with user-level permissions, gracefully handling permission errors without crashing.