# 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:

```bash
# 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
```bash
# 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
```bash
# 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