shell/tui/README.md

# 🔧 Enhanced Backup Manager TUI

A modern, interactive Terminal User Interface (TUI) for## ⌨️ Enhanced Key Bindings

### Navigation & Control

| Key | Action | Description |
|-----|--------|-------------|
| `↑/k` | Move up in list | Navigate backup services |
| `↓/j` | Move down in list | Navigate backup services |
| `←/h` | Move left (panel navigation) | Switch to service list panel |
| `→/l` | Move right (panel navigation) | Switch to output panel |
| `Tab` | Switch between panels | Toggle between service list and output |
| `Enter/Space` | Execute selected backup | Start the selected backup operation |

### View Management

| Key | Action | Description |
|-----|--------|-------------|
| `v` | View backup logs | Switch to logs view with real-time updates |
| `s` | View backup status | Display comprehensive status dashboard |
| `c` | View configuration | Show system and service configuration |
| `r` | Refresh status and logs | Reload all status information |
| `Esc` | Return to main view | Go back to main backup selection |

### Process Control

| Key | Action | Description |
|-----|--------|-------------|
| `x` | Stop running backup | Gracefully cancel active backup process |
| `Space` | Clear output panel | Clear the output display area |
| `?` | Toggle help | Show/hide comprehensive help information |
| `q/Ctrl+C` | Quit application | Exit the TUI application |

### Advanced Features

| Key | Action | Description |
|-----|--------|-------------|
| `f` | View configuration | Detailed system and service information |
| `p` | Progress details | Show detailed progress metrics |
| `l` | Live logs | Real-time log streaming display |p operations in your shell environment. Built with Go and Charm's Bubble Tea framework with advanced real-time features.

## 🚀 Enhanced Features

### 📊 Real-time Progress Tracking

- **Visual Progress Bars**: Live progress indicators with percentage display
- **ETA Calculations**: Intelligent time estimation based on current progress
- **Output Streaming**: Real-time display of backup command output
- **Performance Metrics**: Elapsed time tracking and transfer statistics

### 🎛️ Advanced Process Management

- **Context Cancellation**: Graceful backup cancellation with context support
- **Process Monitoring**: Track and control multiple simultaneous backups
- **Resource Management**: Memory-safe output handling with line limits
- **Thread Safety**: Concurrent operation support with proper synchronization

### 🖥️ Enhanced User Interface

- **Dual-panel System**: Service list and live output viewer
- **Multiple View Modes**: Main, logs, status, and configuration views  
- **Tab Navigation**: Switch between panels with Tab key
- **Smart Key Bindings**: Intuitive keyboard shortcuts for all actions
- **Color-coded Status**: Dynamic status indicators with real-time updates
- **Progressive Disclosure**: Context-sensitive information display

### 📦 Integrated Backup Services

- **🔵 Plex Backup**: Complete Plex Media Server backup with integrity checking
- **🖼️ Immich Backup**: Database and uploads backup with B2 cloud sync
- **🎬 Media Services**: Sonarr, Radarr, Prowlarr, and other media services backup
- **🔧 Environment Files**: Docker environment and configuration files backup
- **🐳 Docker Configuration**: Container and compose files backup

### ✅ Validation & Monitoring

- **Backup Validation**: Integrity checking for all backup types
- **Real-time Monitoring**: Live backup status and progress tracking
- **Health Checks**: Comprehensive backup health monitoring
- **Status Dashboard**: Detailed status view with statistics and summaries

### 🔄 Restoration Services

- **Safe Restoration**: Validated restoration with dry-run options
- **Current Data Backup**: Automatic backup before restoration
- **Interactive Selection**: Choose from available backup files

### 🛡️ Intelligent Error Handling

- **Comprehensive Error Tracking**: Detailed error analysis and reporting
- **User-friendly Messages**: Clear error descriptions with context
- **Recovery Suggestions**: Automated recommendations for error resolution
- **Graceful Degradation**: Continues operation when individual components fail

## 🎯 Quick Start

### Installation

The TUI is already built and ready to use! Simply run:

```bash
# From the shell directory
./backup-tui

# Or directly from the tui directory
cd tui && ./backup-manager
```

### First Time Setup

1. **Ensure Go 1.19+ is installed** (only needed for rebuilding)
2. **Navigate to your shell directory** where backup scripts are located
3. **Launch the TUI** using `./backup-tui`
4. **Use arrow keys or hjkl** to navigate the interface
5. **Press `?`** for comprehensive help and key bindings

### Launch the TUI

```bash
# From the shell directory
./backup-tui

# Or directly from the tui directory
cd tui && ./backup-manager
```

### Key Bindings

| Key | Action |
|-----|--------|
| `↑/k` | Move up in list |
| `↓/j` | Move down in list |
| `←/h` | Move left (panel navigation) |
| `→/l` | Move right (panel navigation) |
| `Enter/Space` | Execute selected backup |
| `Tab` | Switch between panels |
| `v` | View backup logs |
| `s` | View backup status |
| `f` | View configuration |
| `r` | Refresh status and logs |
| `x` | Stop running backup |
| `c` | Clear output panel |
| `Esc` | Return to main view |
| `?` | Toggle help |
| `q/Ctrl+C` | Quit application |

## 📋 Available Operations

### Core Backup Operations

1. **📦 Plex Backup** - Enhanced backup with integrity verification
2. **🖼️ Immich Backup** - Complete database and media backup
3. **🎬 Media Services Backup** - All media service configurations
4. **🔧 Environment Files Backup** - Docker environment files
5. **🐳 Docker Configuration Backup** - Container configurations

### Validation Services

1. **✅ Validate Plex Backups** - Check Plex backup integrity
2. **✅ Validate Immich Backups** - Verify Immich backups
3. **✅ Validate Environment Backups** - Check environment backup health

### Monitoring & Status

1. **📊 Monitor Plex Status** - Real-time Plex backup monitoring

### Restoration Services

1. **🔄 Restore Plex** - Safe Plex restoration with validation
2. **🔄 Restore Immich** - Immich restoration from backup

## 🔧 How It Works

### Script Integration

The TUI integrates with your existing backup scripts:

- **Plex Scripts**: `plex/backup-plex.sh`, `plex/restore-plex.sh`, etc.
- **Immich Scripts**: `immich/backup-immich.sh`, `immich/restore-immich.sh`, etc.
- **Media Scripts**: `backup-media.sh`, `backup-env-files.sh`, etc.

### Real-time Execution

- Scripts are executed with appropriate arguments
- Output is captured and displayed in real-time
- Status is tracked and updated live
- Errors are handled gracefully with detailed reporting

### Log Integration

- Reads from existing log files in `logs/` directories
- Parses performance data from JSON logs
- Displays recent activity and status information
- Provides searchable log viewer

## 🎨 Interface Layout

```text
┌─── 🔧 Media & Plex Backup Manager ────┐
│┌─────────────── Services ──────────────┐┌─── Output / Logs ───┐│
││> 1. 📦 Plex Backup                    ││Running backup...     ││
││  2. 🖼️ Immich Backup                  ││                     ││
││  3. 🎬 Media Services Backup          ││Status: ✅ Success    ││
││  4. ✅ Validate Plex Backups          ││Duration: 45.3s      ││
││  5. 🔧 Environment Files Backup       ││                     ││
│└───────────────────────────────────────┘└─────────────────────┘│
│plex: ✅ 45.3s | immich: idle | Panel: Backup List               │
└──────────────────────────────────────────────────────────────────┘
```

## 🔨 Development

### Prerequisites

- Go 1.19+ installed
- Access to backup scripts in the shell environment
- Terminal with at least 80x24 resolution

### Building from Source

```bash
cd tui
export GOROOT=/usr/lib/go-1.19
export PATH=$PATH:$GOROOT/bin
go mod tidy
go build -o backup-manager main.go
```

### Dependencies

- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - TUI framework
- [Bubbles](https://github.com/charmbracelet/bubbles) - TUI components
- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Styling

## 📊 Status Indicators

| Icon | Status | Description |
|------|--------|-------------|
| ✅ | Success | Operation completed successfully |
| ❌ | Error | Operation failed with errors |
| 🔄 | Running | Operation currently in progress |
| ⏸️ | Idle | Service available but not running |

## 🚀 Advanced Usage

### Automated Operations

The TUI integrates with your existing automation:

- Cron jobs continue to work independently
- TUI provides manual execution and monitoring
- Status reflects both manual and automated runs

### Script Arguments

- Backup scripts are called with appropriate flags (`--non-interactive`, etc.)
- Restore operations use safe defaults (`--dry-run` for Plex)
- Validation scripts run with comprehensive checks

### Log Management

- View recent logs with `v` key
- Logs are sorted by timestamp (newest first)
- Real-time updates when logs change
- Integration with existing logging infrastructure

## 🔗 Integration

### Existing Workflow

The TUI complements your existing backup infrastructure:

- **Preserves** all existing scripts and functionality
- **Enhances** with interactive management
- **Integrates** with current logging and monitoring
- **Maintains** compatibility with automation

### Notification Integration

- Scripts continue to send notifications (webhook, email)
- TUI provides additional visual feedback
- Status updates reflect script execution results
- Status updates reflect script execution results

## 📝 Notes

- The TUI automatically detects the shell directory structure
- Scripts are executed from their proper directories
- Environment variables and paths are preserved
- Safe execution with proper error handling

---

*Built with ❤️ using [Charm](https://charm.sh/) tools for a delightful terminal experience!*