shell/tui/README.md

# 📁 Backup File Browser TUI

A modern, interactive Terminal User Interface (TUI) for browsing and viewing backup files and logs in your shell environment. Built with Go and Charm's Bubble Tea framework for a delightful file exploration experience. This TUI provides read-only access to your backup infrastructure, allowing you to explore backup directories, view file details, and browse operation logs without modifying any files.

## ⌨️ Key Bindings

### Navigation & File Browsing

| 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` | Browse selected directory | View backup files and details |

### View Management

| Key | Action | Description |
|-----|--------|-------------|
| `v` | View backup logs | Switch to logs view |
| `s` | View backup status | Display backup file status information |
| `f` | View configuration | Show system and service configuration |
| `r` | Refresh current view | Reload directory and status information |
| `Esc` | Return to main view | Go back to main backup selection |

### Interface Control

| Key | Action | Description |
|-----|--------|-------------|
| `c` | Clear output panel | Clear the output display area |
| `?` | Toggle help | Show/hide comprehensive help information |
| `q/Ctrl+C` | Quit application | Exit the TUI application |

## 🚀 Features

### 📁 File Browser Interface

- **Directory Navigation**: Browse backup directories for different services
- **File Details**: View file sizes, modification dates, and backup types
- **Service Organization**: Organized by backup service (Plex, Immich, Media services, etc.)
- **Log File Viewing**: Browse and read backup operation logs

### 📊 Information Display

- **Backup Statistics**: View file counts, total sizes, and backup ages
- **Status Information**: Display backup directory health and availability
- **Configuration Details**: Show system and service configuration information
- **File Metadata**: Display compressed file status and service associations

### 🖥️ User Interface

- **Dual-panel System**: Service list and detailed information viewer
- **Multiple View Modes**: Main browser, logs viewer, status, and configuration views
- **Tab Navigation**: Switch between panels with Tab key
- **Smart Key Bindings**: Intuitive keyboard shortcuts for navigation
- **Color-coded Display**: Dynamic visual indicators for file types and status
- **Context-sensitive Information**: Detailed descriptions for each backup service

### 📦 Backup Service Directories

- **🔵 Plex Backups**: Browse Plex Media Server backup files and archives
- **🖼️ Immich Backups**: View Immich photo management backup files
- **🎬 Media Services**: Browse Sonarr, Radarr, Prowlarr, and other media service backups
- **🔧 Environment Files**: View Docker environment and configuration file backups
- **🐳 Docker Configuration**: Browse container and compose file backups
- **📊 Tautulli**: Browse Plex statistics and monitoring backups
- **📚 Audiobookshelf**: View audiobook server backup files
- **📥 SABnzbd**: Browse download client configuration backups
- **🎯 Jellyseerr**: View request management system backups

### 📋 Log and Status Viewing

- **Backup History**: Browse historical backup operation logs
- **File Information**: View detailed file metadata and timestamps
- **Directory Statistics**: See backup counts, sizes, and dates
- **System Configuration**: Display current system and service settings

## 🎯 Quick Start

### Installation

The TUI uses a consistent build system with multiple options:

```bash
# Option 1: Use the launcher script (recommended)
cd /home/acedanger/shell
./launch-backup-tui.sh

# Option 2: Use Makefile for development
cd tui
make all          # Build and install
make build        # Build only
make dev          # Quick development build

# Option 3: Use build script
cd tui
./build.sh

# Option 4: Direct Go build
cd tui
go build -o backup-tui main.go
```

### 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 `./launch-backup-tui.sh`
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 (recommended - auto-builds if needed)
./launch-backup-tui.sh

# Or if binary exists
./backup-tui

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

### 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` | Browse selected directory |
| `Tab` | Switch between panels |
| `v` | View backup logs |
| `s` | View backup status |
| `f` | View configuration |
| `x` | Return to main view |
| `c` | Clear output panel |
| `Esc` | Return to main view |
| `?` | Toggle help |
| `q/Ctrl+C` | Quit application |

## 📁 Available Backup Directories

### Backup Service Directories

1. **📦 Plex Backups** - Browse Plex Media Server backup archives and files
2. **🖼️ Immich Backups** - View Immich photo management backup files
3. **🎬 Sonarr Backups** - Browse Sonarr TV series management backup files
4. **🎭 Radarr Backups** - View Radarr movie management backup files
5. **🔍 Prowlarr Backups** - Browse Prowlarr indexer management backup files
6. **🎯 Jellyseerr Backups** - View Jellyseerr request management backup files
7. **📥 SABnzbd Backups** - Browse SABnzbd download client backup files
8. **📊 Tautulli Backups** - View Tautulli Plex statistics backup files
9. **📚 Audiobookshelf Backups** - Browse Audiobookshelf server backup files
10. **🐳 Docker Data Backups** - View Docker container data and volume backups
11. **📋 Backup Logs** - Browse backup operation logs and history

### Directory Information

Each directory shows:

- **File listings** with names, sizes, and modification dates
- **Directory statistics** including total files and combined size
- **Backup metadata** such as compression status and service type
- **Path information** for easy navigation and reference

## 🔧 How It Works

### Directory Structure Detection

The TUI automatically discovers and organizes backup directories:

- **Backup Path**: Scans `/mnt/share/media/backups/` for service directories
- **Service Recognition**: Identifies Plex, Immich, media services, and other backup folders
- **File Analysis**: Reads file metadata including sizes, dates, and compression status
- **Log Discovery**: Locates and organizes backup operation log files

### File Browsing System

- **Directory Navigation**: Browse through backup files organized by service
- **File Details**: Display comprehensive file information and metadata
- **Content Organization**: Sort files by date, size, or modification time
- **Path Tracking**: Maintain breadcrumb navigation for easy orientation

### Log File Integration

- **Log File Reading**: Access backup operation logs from `logs/` directories
- **Date Parsing**: Extract timestamps and service information from log filenames
- **Content Display**: Show log contents with proper formatting and navigation
- **Historical Viewing**: Browse logs by date and service for troubleshooting

## 🎨 Interface Layout

```text
┌─── 📁 Backup File Browser ────────────┐
│┌─────────────── Services ──────────────┐┌─── File Details ────┐│
││> 1. 📦 Plex Backups                   ││📦 Plex Backups      ││
││  2. 🖼️ Immich Backups                 ││                     ││
││  3. 🎬 Sonarr Backups                 ││Files: 15            ││
││  4. 🎭 Radarr Backups                 ││Size: 2.3 GB         ││
││  5. 🔍 Prowlarr Backups               ││Last: 2024-01-15     ││
│└───────────────────────────────────────┘└─────────────────────┘│
│View: MAIN | Panel: Backup List | Path: /mnt/share/media/backups │
└──────────────────────────────────────────────────────────────────┘
```

## 🔨 Development

### Prerequisites

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

### Building from Source

The TUI includes multiple build options for consistent binary naming:

```bash
# Option 1: Use Makefile (recommended for development)
cd tui
make all          # Clean, build, and install
make build        # Build only
make dev          # Quick development build
make clean        # Remove build artifacts
make help         # Show all targets

# Option 2: Use build script
cd tui
./build.sh

# Option 3: Direct Go build
cd tui
export GOROOT=/usr/lib/go-1.19
export PATH=$PATH:$GOROOT/bin
go mod tidy
go build -o backup-tui main.go
```

**Binary Naming**: All build methods consistently create `backup-tui` binary.

### 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 |
|------|--------|-------------|
| ✅ | Available | Directory exists and contains backup files |
| ❌ | Missing | Directory path not found or inaccessible |
| 📁 | Directory | Backup service directory with file contents |
| 📋 | Logs | Log files and backup operation history |

## 🚀 Advanced Usage

### File Browsing Features

The TUI provides comprehensive backup file exploration:

- **Directory Exploration**: Browse backup files organized by service type
- **File Filtering**: Navigate through files by date, size, or service
- **Metadata Display**: View detailed file information including compression status

### Backup Analysis

- **Size Tracking**: Monitor backup file sizes and storage usage
- **Date Analysis**: Review backup frequency and file modification dates
- **Service Organization**: Files organized by backup service for easy navigation
- **Compression Detection**: Identify compressed archives and their contents

### Log File Management

- **Log Browsing**: Navigate through backup operation logs by date and service
- **Content Viewing**: Read log file contents directly within the TUI
- **Error Investigation**: Quickly locate and review backup operation issues
- **Historical Analysis**: Track backup patterns and success rates over time

## 🔗 Integration

### Existing Workflow

The TUI complements your existing backup infrastructure:

- **Read-Only Access**: Safely browse backup files without risk of modification
- **Log Integration**: View backup operation logs from existing automation
- **Directory Monitoring**: Track backup file creation and organization
- **Compatible Viewing**: Works alongside existing backup scripts and cron jobs

### Backup Infrastructure Viewing

- **File Discovery**: Automatically detects backup files from all services
- **Status Information**: Shows backup file health and availability
- **Log Analysis**: Provides easy access to backup operation history
- **Storage Monitoring**: Track backup storage usage and file organization

## 📝 Notes

- The TUI automatically detects backup directory structure and organization
- Provides read-only access to backup files for safe browsing and analysis
- Backup files are displayed with metadata including sizes, dates, and compression status
- Log files can be viewed directly within the interface for troubleshooting and analysis

---

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