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

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

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

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

Features

1. System Tray Icon

• Show a system tray icon when the app is active

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
• 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
• Backup location
  • User should be able to pick the destination location within their file system
  • Destination should be a folder
• 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
• 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
• 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
• Notifications
  • User should be able to toggle notifications for backup progress
  • Notifications should be native to the platform
• Compression
  • User should be able to toggle compression for backup files
  • A description should inform the user what the consequences of compression are

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

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

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

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