dotfiles/ARCHITECTURE.md

# Dotfiles Architecture Documentation

## Philosophy: μέτρον γὰρ καὶ συμμετρία καὶ τὸ πρόσφορον

This dotfiles system is built upon the prime directive: **"Prioritize durable, thoughtful solutions over expedient ones"**. The Greek principle of μέτρον (measure), συμμετρία (proportion), and τὸ πρόσφορον (what is fitting) guides every architectural decision.

## Core Principles

### 1. Durability Over Convenience
- **Long-term thinking**: Solutions that remain stable across system updates
- **Graceful degradation**: System continues to function when components are missing
- **Version stability**: Lockfiles and rollback mechanisms prevent breaking changes

### 2. Thoughtful Modularization  
- **Single responsibility**: Each script and configuration file has a clear purpose
- **Composable design**: Components work independently and together
- **Context awareness**: System adapts behavior based on working directory and usage patterns

### 3. Measured Implementation
- **What is fitting**: Tools and configurations chosen for specific needs, not trends
- **Proportional complexity**: Simple solutions for simple problems
- **Observable behavior**: System provides visibility into its operations

## System Architecture

```
~/dotfiles/
├── engage                    # Master deployment script (Star Trek theme)
├── Brewfile                  # Package definitions (120+ tools)
├── Brewfile.lock            # Version snapshots for reproducibility
├── shell/                   # Modular shell configuration
│   ├── .zshrc              # Main shell config (replaces ~/.zshrc)
│   ├── environment.zsh     # Environment variables
│   ├── paths.zsh           # PATH management with deduplication  
│   ├── aliases.zsh         # Command aliases
│   ├── functions.zsh       # Custom functions
│   └── .zsh-plugins.txt    # Plugin manifest for Antidote
├── scripts/                # Automation and maintenance
│   ├── backup-ssh-keys.sh  # GPG encryption for sensitive data
│   ├── generate-lockfile.sh# Version tracking
│   ├── safe-update.sh      # Update with rollback protection
│   ├── detect-drift.sh     # Configuration consistency checking
│   ├── system-health.sh    # Observability and monitoring
│   └── set-macos-defaults.sh# System preferences automation
└── git/                    # Git configuration and hooks
    ├── .gitconfig          # Git settings
    └── hooks/              # Security and validation hooks
```

## Component Design Rationale

### The "engage" Script
**Inspiration**: Captain Picard's decisive command  
**Purpose**: Single-entry point for complete system deployment  
**Design**: Interactive menu with phased installation and pre-flight checks

```bash
# Philosophy: Make complex deployment feel effortless
echo "🖖 ENGAGE - Make it so!"
```

### Shell Configuration Strategy
**Problem**: Monolithic .zshrc files become unmaintainable  
**Solution**: Modular architecture with graceful degradation

**Key decisions**:
- **environment.zsh**: Sets the foundation (XDG, locale, history)
- **paths.zsh**: Intelligent PATH building with deduplication
- **functions.zsh**: Enhanced system utilities (sysupdate, deep_clean, vault integration)
- **Context awareness**: Behavior adapts to work/chamber/vault/dotfiles environments

### Package Management Philosophy
**Brewfile Design**: Organized by purpose, not alphabetically
```ruby
# Development tools come first (core workflow)
brew "git"
brew "ripgrep" 
brew "fzf"

# Productivity tools second (daily usage)
brew "obsidian"
brew "raycast"
```

**Rationale**: Reflects actual importance hierarchy, not convenience

### Version Control Strategy
**Three-tier approach**:
1. **Brewfile**: What should be installed
2. **Brewfile.lock**: What versions are currently installed  
3. **safe-update.sh**: How to update safely with rollback

This mirrors software engineering best practices (requirements → lockfile → deployment).

### Security Architecture
**Defense in depth**:
- **SSH key backup**: GPG-encrypted with restore instructions
- **Git hooks**: Prevent accidental secret commits
- **Firewall monitoring**: System health checks include security posture
- **Sensitive data handling**: Never commit secrets, always encrypt backups

## Advanced Features

### Configuration Drift Detection
**Problem**: Systems inevitably drift from their defined state  
**Solution**: Automated comparison between actual and intended configuration

**Three drift types monitored**:
1. **Package drift**: Installed vs. Brewfile definitions
2. **Configuration drift**: Live files vs. dotfiles repository  
3. **System drift**: Current macOS settings vs. defaults script

### System Health Monitoring
**Observability philosophy**: "You can't manage what you can't measure"

**Monitored components**:
- **Resources**: CPU, memory, disk usage with intelligent thresholds
- **Services**: Critical tools (Homebrew, Git, Zsh, SSH) health status
- **Packages**: Total count, outdated packages, broken installations
- **Shell performance**: Load time and plugin count impact
- **Network**: Internet, DNS, GitHub connectivity for development
- **Security**: SSH keys, GPG keys, firewall status

### Context-Aware Behavior
**Philosophy**: Tools should adapt to how you work

**Context detection**:
```bash
# Automatic context detection based on PWD
detect_context() {
    case "$PWD" in
        *work*) CURRENT_CONTEXT="work" ;;
        *chamber*) CURRENT_CONTEXT="chamber" ;;
        *vault*) CURRENT_CONTEXT="vault" ;;
        *dotfiles*) CURRENT_CONTEXT="dotfiles" ;;
        *) CURRENT_CONTEXT="general" ;;
    esac
}
```

**Context-specific behaviors**:
- **Work**: Enhanced productivity shortcuts, stricter security
- **Chamber**: Creative workspace optimizations  
- **Vault**: Knowledge management integration (Obsidian shortcuts)
- **Dotfiles**: System administration tools prominently available

## Error Handling Philosophy

### Graceful Degradation
**Principle**: System remains functional when components fail

**Implementation patterns**:
```bash
# Tool availability checks
if command -v fzf >/dev/null; then
    eval "$(fzf --zsh)"
elif [[ -z "${P10K_INSTANT_PROMPT-}" ]]; then
    echo "⚠️  FZF not available - install with: brew install fzf"
fi
```

### Rollback Capabilities
**Safe-update pattern**: Always create recovery points before changes
- **Snapshots**: Package states and configuration backups
- **Health testing**: Verify system function after updates
- **Automatic rollback**: Return to last known good state on failure

## Performance Considerations

### Shell Startup Optimization
**Problem**: Plugin-heavy shells can have slow startup times  
**Solutions**:
- **Instant prompt**: Powerlevel10k instant prompt for immediate responsiveness
- **Conditional loading**: Only load tools that are actually installed
- **Fast mode**: Non-interactive shells bypass expensive operations

### Plugin Management Strategy
**Antidote over Oh My Zsh**: Faster, more reliable plugin management
**Curated plugin list**: Only essential plugins, regularly audited
**Performance monitoring**: Track shell load times and plugin impact

## Future Evolution

### Extensibility Points
**Plugin architecture**: Additional modules can be added to `shell/` directory
**Hook system**: Custom scripts can extend behavior at defined points
**Context expansion**: New work environments easily added to context detection

### Maintenance Strategy
**Regular audits**: Quarterly review of tools and configurations
**Dependency tracking**: Monitor for deprecated packages or breaking changes
**Documentation updates**: Architecture docs updated with any design changes

## Conclusion

This dotfiles system embodies the principle that **good tools become invisible**. By prioritizing durability, thoughtfulness, and proportionality, it creates a computing environment that supports focused work rather than demanding constant maintenance.

The μέτρον principle ensures that every component has the right measure of complexity - no more, no less - for its intended purpose. This creates a system that remains stable and usable across years of computing, embodying the prime directive of durable, thoughtful solutions.

---

*"The best tools are the ones you forget you're using."*  
*"Make it so!" - Captain Jean-Luc Picard*