wow-backup/docs/masterplan.md

Major goals

• Provide a simple and configurable way to automatically backup WoW's config data
• Provide a way to restore backed up data

Current Implementation Status

Milestone / Feature	Status	Notes
Foundation (Feature 0)	✅ Complete	Package structure, JSON persistence (ConfigManager), platform abstractions (AppDirectories, Platform), daily rolling logback logging.
System Tray (Feature 1)	✅ Complete	Dynamic Java2D tray icon with template mode for dark/light themes, tray context menu, tray-aligned positioning for macOS & Windows.
Configuration (Feature 2)	✅ Complete	Full M3 Settings UI, path auto-detection & validation, native file pickers, startup registration (macOS LaunchAgent / Windows Registry), theme/accent customization.
Backup Engine (Feature 3)	✅ Complete	Background parallel copy and ZIP archive creation, process detection (WoWProcessDetector), drift-free scheduling (Cardiologist), automatic retention pruning, native notifications.
Status Screen (Feature 4)	✅ Complete	Real-time status cards, live backup progress tracking, "Backup Now" trigger, missing configuration banner, quick folder shortcuts.
Restore Screen (Feature 5)	🚧 In Progress / Next Priority	Restore engine, backup browser UI, extraction/overwrite mechanics, safety validation, cancellation flow.

---

Scope

• This is a desktop application, supporting both MacOS and Windows
• This uses Kotlin Compose Multiplatform to share as much code as possible
• This is a GUI application, which the user can interact with primarily through a dialog, accessible through the system tray
• The UI should be as native-looking as possible to each platform
• The UX should be as intuitive as possible
• This should be simple, straightforward to use, but configurable

Non-functional requirements

Logging

• All app operations should be logged to a file
• The log should be human-readable and timestamped
• Log files should be rotated and archived to keep sizes manageable
• Status: Implemented (logback-classic + LoggingSetup.kt, rotated daily and capped at 100MB).

Native look and feel

• The app should use native components for the UI, whenever possible
• The app should leverage native APIs, like the MacOS system tray, whenever possible
  • If needed, prioritise MacOS over Windows
• Status: Implemented (Tray integration, AWT FileDialog for macOS directories, JFileChooser fallback, tray-aligned window positioning).

Permissions

• The app should request the minimum permissions it needs to run, as proactively as possible
• The app should not request any permissions it doesn't need
• The app should gracefully handle missing permissions, showing a warning to the user explaining the reasoning for needing those permissions
• We must pay special attention to file and directory access permissions, particularly on MacOS
• Status: Implemented (WoWLocations.validateWoWInstall explicitly tests directory readability and returns user-facing permission warnings).

Features

1. System Tray Icon

• Show a system tray icon when the app is active
• Status: Complete (TrayIcon.kt, main.kt).

2. Configuration screen

• A configuration screen needs to be accessible
• Should be accessible through the system tray icon
• Should appear when the app is run, if any configuration is missing

2.1 Configuration options

• Run at startup
  • User should be able to enable/disable this
  • If enabled, the app should run automatically when the user logs in
  • Status: Complete (StartupManager.kt).
• WoW install location
  • User should be able to pick the location within their file system
  • The app should try to scan default locations for an existing install, potentially saving the user some clicks
  • Status: Complete (WoWLocations.findWoWInstall(), ConfigScreen.kt).
• Backup location
  • User should be able to pick the destination location within their file system
  • Destination should be a folder
  • Status: Complete (NativeFolderPicker.kt).
• Backup frequency
  • User should be able to define a schedule for their backups
  • A small message warning that the backup will run only if WoW isn't running
  • User should be able to define how much backup history to keep
  • Status: Complete (TimePicker.kt, BackupScheduler.kt).
• Force backup
  • A checkbox to force the backup to run even when WoW is running
  • A confirmation dialog should be shown if the user enables this
  • Status: Complete (ConfirmationDialog.kt).
• Folder selection
  • The user should be able to toggle the WTF and Interface folders for backup
  • Each folder should have a small description of why it can be important to backup
  • Status: Complete (ConfigScreen.kt).
• Notifications
  • User should be able to toggle notifications for backup progress
  • Notifications should be native to the platform
  • Status: Complete (BackupNotifier.kt).
• Compression
  • User should be able to toggle compression for backup files
  • A description should inform the user what the consequences of compression are
  • Status: Complete (BackupEngine.kt, ConfigScreen.kt).

3. Backup

• The actual backup process should happen in the background
• Backup only happens when the app is configured
• Backup is automatic, following the configured schedule
• The folders and all their contents should be backed up reliably
• If compression is enabled, the backup should be compressed in order to save space
• The result of the backup should be stored in the configured backup location, with a human-readable timestamped folder name
• If enabled, notifications should be shown to the user:
  • When backup starts
  • When backup finishes
  • When backup fails
• Status: Complete (BackupEngine.kt, BackupScheduler.kt, BackupHistory.kt).

4. Status screen

• Accessible when clicking the system tray icon
• Should show the status of the backup process, including:
  • Time and status (failed/success) of last backup
    • If failed, show the reason for the failure
  • Time of next scheduled backup
  • Is WoW running, and is 'force backup' enabled?
  • Is the backup currently running? If so, show the progress of the backup
• Should show a button to open the backup location
• Should show a button to open the configuration screen
• Should show a button to start the restore process
• Should show a message if configuration is missing or incomplete
• Status: Complete (StatusScreen.kt, StatusViewModel.kt).

5. Restore screen

• Should show a button to open the backup location
• Should display a list of all existing backups, and their date in a human-readable format
• Should allow the user to select a backup to restore
• Confirmation dialog should be shown before restoring, informing all current WoW data will be replaced
• Status: Pending (Feature 5 implementation).

5.1 Restore process

• The restore process should happen in the foreground, with a proper dialog displaying the progress and ETA to finish
• The restore should be done in a way that is as transparent as possible to the user
• The restore process should be cancellable by the user
• Status: Pending (Feature 5 implementation).