Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
199 lines (163 loc) · 8.01 KB

ARCHITECTURE.md

File metadata and controls

199 lines (163 loc) · 8.01 KB
Raw

Architecture Overview

┌──────────────────────────────────────────────────────────────────┐
│                     TUXSYNC ARCHITECTURE                         │
└──────────────────────────────────────────────────────────────────┘

                         User Command
                      tuxsync [command]
                              ↓
                ┌─────────────────────────────┐
                │     CLI Interface           │
                │       (cli.py)              │
                │                             │
                │  • backup    • restore      │
                │  • list      • config       │
                └──────────────┬──────────────┘
                               ↓
                ┌─────────────────────────────┐
                │    Scanner Module           │
                │     (scanner.py)            │
                │                             │
                │  • Detect distro            │
                │  • Query package manager    │
                │    - apt-mark (Ubuntu)      │
                │    - dnf history (Fedora)   │
                │    - pacman -Qe (Arch)      │
                │  • Filter system packages   │
                │  • Scan bashrc/configs      │
                └──────────────┬──────────────┘
                               ↓
                ┌─────────────────────────────┐
                │   Storage Backend           │
                │     (storage.py)            │
                │                             │
                │  • GitHub Gists (default)   │
                │  • Custom server (future)   │
                │  • Save/retrieve profiles   │
                └──────────────┬──────────────┘
                               ↓
                ┌─────────────────────────────┐
                │   Restore Manager           │
                │     (restore.py)            │
                │                             │
                │  • Fetch profile            │
                │  • Delegate to tuxmate-cli  │
                │  • Delegate to chezmoi      │
                │  • Restore configs          │
                │  • Dry-run mode             │
                └──────────────┬──────────────┘
                               ↓
                  ┌────────────────────────┐
                  │  tuxmate-cli           │
                  │  (external executor)   │
                  │                        │
                  │  Cross-distro install  │
                  │  Uses tuxmate's DB     │
                  └────────────┬───────────┘
                               ↓
                  ┌────────────────────────┐
                  │  chezmoi (optional)    │
                  │  (external executor)   │
                  │                        │
                  │  Dotfile management    │
                  │  Template support      │
                  └────────────┬───────────┘
                               ↓
                       📦 Restored System

Note: tuxmate-cli uses the curated package database from
      tuxmate (https://github.com/abusoww/tuxmate)
      chezmoi provides comprehensive dotfile management
      (https://github.com/twpayne/chezmoi)

Data Flow

Backup Flow

User → tuxsync backup → Scanner → Storage → GitHub Gist
                           ↓              ↓
                    Package List    Chezmoi (optional)
                    + Configs       Dotfiles → Git Repo
  1. Scanner queries package manager (apt/dnf/pacman)
  2. Filters system packages (libraries, dependencies)
  3. Collects bashrc and config files
  4. Optionally delegates dotfile backup to chezmoi
  5. Storage saves to GitHub Gist with metadata

Restore Flow

User → tuxsync restore <GIST_ID> → Storage → Restore Manager → tuxmate-cli → System
                                       ↓                ↓
                               Profile Data       chezmoi (optional)
                               (YAML)             Dotfiles restore
  1. Storage fetches profile from GitHub Gist
  2. Restore Manager parses package list
  3. Calls tuxmate-cli install <packages> via subprocess
  4. Optionally calls chezmoi init and chezmoi apply for dotfiles
  5. Restores bashrc and configs to home directory

Key Components

  • Scanner: Distro-agnostic package detection
  • Chezmoi Integration: Optional dotfile management delegation
  • Storage: Pluggable backend (GitHub Gists, custom server)
  • Restore Manager: Orchestrates restoration workflow
  • Utils: Helper functions (distro detection, subprocess execution)

Backup Structure

TuxSync stores backups with two files in a GitHub Gist:

tuxsync.yaml

version: "1.0"
created_at: "2024-12-28T10:30:00Z"
distro: "Ubuntu"
distro_version: "24.04"
package_manager: "apt"
package_count: 142
packages:
  - vim
  - git
  - docker.io
  - nodejs
  # ... more packages
has_bashrc: true

bashrc

Raw content of ~/.bashrc (if backed up).

Storage Backend

GitHub Gists (Current)

  • Pros: Free, no server setup, public/private options
  • Cons: Requires GitHub CLI (gh), tied to GitHub ecosystem
  • Format: YAML with metadata (distro, packages, configs)

Custom Server

  • Pros: Complete privacy, self-hosted
  • Cons: Requires server setup
  • Implementation: Simple REST API for upload/download
  • Status: WIP - See Custom Server API for details

Magic Restore Command

TuxSync generates a one-liner for new machines:

curl -sL https://raw.githubusercontent.com/Gururagavendra/tuxsync/main/restore.sh | bash -s -- <GIST_ID>

This script:

  1. Installs Python + uv (if needed)
  2. Installs tuxmate-cli (if needed)
  3. Installs TuxSync
  4. Runs tuxsync restore <GIST_ID>

Design Philosophy

Loose Coupling

TuxSync follows a separation of concerns principle: Orchestrator (coordinates backup/restore workflow)

  • tuxmate-cli = Package Manager (handles cross-distro package installation using tuxmate's curated package database)
  • chezmoi = Dotfile Manager (optional, handles comprehensive dotfile syncing)

This design means:

  • TuxSync calls external tools as subprocesses (no code sharing)
  • If tools aren't installed, TuxSync auto-downloads them gracefully
  • Updates to any tool don't break the others
  • Users can use tuxmate-cli or chezmoi independently
  • Swapping dotfile managers (chezmoi → yadm) is trivial
  • Users can use tuxmate-cli independently for package installation

Why This Architecture?

  1. Single Responsibility: Each tool does one thing well
  2. Independent Updates: tuxmate-cli can improve without TuxSync changes
  3. User Choice: Users can use tuxmate-cli directly if they prefer
  4. Smaller Codebase: No duplicate package installation logic
  5. Better Maintenance: Bugs in one tool don't affect the other

Quick Links

  • README - User guide with examples