dotfiles/docs/ARCHITECTURE.md

Architecture Overview

This document details the technical architecture and implementation specifics of the Modern Dotfiles Management System.

🏗️ System Structure

The core components of the dotfiles system are organized as follows:

~/.dotfiles/
├── install.sh              # Main installation script
├── sync.sh                  # Auto-sync with git repository
├── reset.sh                 # Reset to vanilla state
├── machine-profiles.yaml   # Machine type definitions
├── packages.yaml           # Package definitions
├── bash/                   # Bash-specific configurations
├── zsh/                    # Zsh-specific configurations
├── shared/                 # Universal configurations
├── git/                    # Git configuration
├── vim/                    # Vim configuration
├── lib/                    # Core libraries
└── docs/                   # Documentation

🤖 Machine Profiles

The system automatically detects and configures based on machine type using a scoring algorithm:

Server Profile

• Purpose: Minimal server setup
• Packages: curl, git, vim, sshuttle, ripgrep, fd
• Use Case: Production servers, minimal VMs
• Auto-detection: SSH connections, systemd services, no GUI

Development Profile

• Purpose: Full development environment
• Packages: All tools including Claude AI, Gemini CLI, Docker, modern CLI tools
• Use Case: Primary development machines
• Auto-detection: Code editors, development directories, Node.js/Python

Development Lite Profile

• Purpose: Development without heavy packages
• Packages: Development tools but no Docker/containers
• Use Case: Lightweight VMs, resource-constrained machines
• Auto-detection: Development tools present but limited resources

Personal Profile

• Purpose: Personal machines with all conveniences
• Packages: Everything including task management tools
• Use Case: Personal laptops, home workstations
• Auto-detection: Personal directories, browsers, GUI environment

Minimal Profile

• Purpose: Absolute bare bones
• Packages: curl, git, vim only
• Use Case: Emergency access, extremely limited environments

🔧 Technical Implementation

Profile Detection Algorithm

The system uses a scoring algorithm to detect machine type:

# Server indicators (weight)
- systemd active (30 points)
- SSH connection (25 points)
- Multi-user target (20 points)
- No logged users (10 points)

# Development indicators
- Development tools present (30 points)
- Code editor available (25 points)
- Dev directories exist (20 points)
- GUI environment (15 points)

# Personal indicators
- Personal directories (20 points)
- Browser available (25 points)
- Personal home path (15 points)

Update Checking Strategy

# Fast check methods
npm outdated -g --json      # No installs, just version comparison
GitHub API calls            # Latest release info
Local version parsing       # Current installed versions

# Selective updates
Only outdated packages      # Skip up-to-date ones
Profile filtering          # Server won't check Claude/Gemini
Batch operations          # Update multiple efficiently

Sync Optimization

# Timing controls
24-hour auto-sync limit    # Prevent excessive git operations
5-minute manual override   # Allow frequent manual syncing
Background execution       # Non-blocking terminal startup

# Change detection
Git fetch + compare        # Check for remote changes
Local diff detection       # Handle local modifications
Automatic stash/restore    # Preserve local changes

🛡️ Safety Features

Backup System

• Pre-installation backup: All existing configs saved
• Timestamped backups: Never overwrites previous backups
• Symlink detection: Preserves existing dotfiles setups
• Restoration capability: Can restore original configs

Reset Capabilities

• Soft reset: Remove dotfiles, restore originals
• Hard reset: Also uninstall packages
• Nuclear reset: Complete removal
• Safety prompts: Confirmation for destructive operations

Error Handling

• Graceful failures: Continue on non-critical errors
• Detailed logging: All operations logged with timestamps
• Rollback capability: Can undo changes if needed
• Dependency checking: Verify requirements before installation

📈 Performance Characteristics

Startup Time

• Cold start: ~2 seconds (first terminal of day with sync)
• Warm start: ~0.1 seconds (subsequent terminals)
• Background sync: Non-blocking, invisible to user

Update Efficiency

• Traditional approach: npm update -g (30-60 seconds)
• Smart checking: dotupdatecheck (2-5 seconds)
• Selective updates: Only outdated packages (10-20 seconds)

Resource Usage

• Memory footprint: Minimal (shell functions only)
• Disk usage: ~50MB for full dev profile
• Network usage: Efficient API calls, cached results