Full GenHub System Backup, Export & Disaster Recovery (CAS Pool, Manifests, Profiles & State)

[undead2146]

[Feature] Full GenHub System Backup, Export & Disaster Recovery (CAS Pool, Manifests, Profiles & State)

1. Problem Statement & Context

GenHub's content architecture separates configuration from binary assets:

• Game Profiles & Settings: %LOCALAPPDATA%\GenHub\Profiles\ and %LOCALAPPDATA%\GenHub\settings.json
• Manifest Pool: %LOCALAPPDATA%\GenHub\Manifests\
• Content-Addressable Storage (CAS) Pool: %APPDATA%\Roaming\GenHub\cas-pool\ and drive-adjacent .genhub-workspace\cas-pool\
• Application State & Preferences: User configuration, tool installations, and launcher mappings.

When a user performs a clean uninstallation (or migrates to a new system/drive), Velopack completely wipes %LOCALAPPDATA%\GenHub.

The Critical CAS Dependency Problem

A GameProfile is only an abstract configuration recipe referencing ManifestIds and content entries. It does not contain game binaries, DLLs, or BIG files. If the CAS object store or Manifest Pool is wiped or missing:

• Restoring only gameprofiles.json yields unlaunchable profiles because there are no physical CAS blobs to hard-link into the game directory.
• For complete disaster recovery, an offline backup must package Profiles, Manifests, User Settings, and CAS Object Blobs into a single, deduplicated archive (.ghbak).

(Note: Standalone Profile Sharing—where missing CAS objects are dynamically re-downloaded via remote acquisition resolvers—will be tracked in a separate future issue).

---

Architectural Clarification: Disaster Recovery vs. GameProfile Sharing

Dimension	Full System Backup & Disaster Recovery (This Issue)	GameProfile Sharing / Bundles (Future Feature)
Scope	Complete system snapshot or selected offline profile bundle.	Lightweight profile definition + manifest references.
CAS Content	Includes all underlying CAS blobs required to reconstruct files offline.	Excludes binary blobs; contains only hashes and acquisition URLs.
Target Use Case	Cold storage backup, PC migration, offline recovery, zero-dependency restore.	Community modpack sharing, exporting configuration to friends.
Network Requirement	100% Offline / Air-gapped restore capability.	Requires online acquisition resolvers to fetch missing CAS blobs.
Size	Gigabytes (contains full mod assets, game client binaries, tools).	Kilobytes to Megabytes (pure metadata and manifests).

---

2. User Stories & Use Cases

• UC-1 (Full Disaster Recovery): As a user upgrading or wiping my OS/drive, I want to create a complete GenHub backup so that I can restore all my modded profiles, settings, and downloaded content without re-downloading gigabytes of data.
• UC-2 (Pre-Update Automated Snapshot): As a user updating to a new GenHub version, I want an automatic snapshot taken before the update so that if anything breaks, I can roll back my full environment with one click.
• UC-3 (Full Environment Cloning): As a player with multiple PCs (e.g. Desktop and Steam Deck/Laptop), I want to export my entire GenHub state to a portable .ghbak archive and import it on my other machine for instant offline play.

---

3. Technical Architecture & Archive Specification

A. Archive Structure (.ghbak ZIP Container)

backup_2026-08-19_120000.ghbak
├── backup-manifest.json       <- Backup metadata (SchemaVersion, CreatedAt, AppVersion, HashIndex)
├── settings/
│   └── user-settings.json     <- Global preferences, tools, and launcher configurations
├── profiles/
│   ├── {profileId-1}.json     <- Individual GameProfile JSON definitions
│   └── {profileId-2}.json
├── manifests/
│   ├── {manifestId-1}.json    <- ContentManifest definitions (file trees + SHA256 hashes)
│   └── {manifestId-2}.json
└── cas-pool/
    ├── 36/
    │   └── 36565177e8...      <- Raw deduplicated content blobs
    └── f4/
        └── f4f4daa96c...

B. Deduplication & Space Efficiency

• Because CAS is inherently hash-addressed by SHA-256, all assets shared across multiple profiles (e.g. base game files, community patches) are stored only once in the archive.
• Deflate / Zstandard compression applied to the archive achieves 40–60% space savings on game assets.

---

4. Proposed Interfaces & Data Models

namespace GenHub.Core.Interfaces.Storage;

public interface IFullSystemBackupService
{
    Task<OperationResult<string>> CreateFullBackupAsync(
        string destinationDirectory,
        IProgress<BackupProgress>? progress = null,
        CancellationToken cancellationToken = default);

    Task<OperationResult<BackupSummary>> InspectBackupAsync(
        string backupFilePath,
        CancellationToken cancellationToken = default);

    Task<OperationResult<RestoreResult>> RestoreFullBackupAsync(
        string backupFilePath,
        RestoreOptions options,
        IProgress<RestoreProgress>? progress = null,
        CancellationToken cancellationToken = default);
}

public sealed class BackupManifest
{
    public int SchemaVersion { get; set; } = 1;
    public string AppVersion { get; set; } = string.Empty;
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
    public int ProfileCount { get; set; }
    public int ManifestCount { get; set; }
    public long TotalCasBytes { get; set; }
    public int CasObjectCount { get; set; }
    public Dictionary<string, string> CasHashIndex { get; set; } = [];
}

---

5. UI/UX Wireframe (Settings -> Backup & Recovery)

+-------------------------------------------------------------------------+
| [Settings] > [Backup & Disaster Recovery]                              |
+-------------------------------------------------------------------------+
| Complete System Backup                                                  |
| Create a self-contained offline archive (.ghbak) containing all your    |
| profiles, content manifests, settings, and downloaded CAS game assets.  |
|                                                                         |
| Total CAS Pool: 14.2 GB (223 objects) | Profiles: 6 | Manifests: 12     |
|                                                                         |
| [  Create Full System Backup (.ghbak)  ]   [  Restore From Backup...  ] |
+-------------------------------------------------------------------------+
| Automated Snapshots                                                     |
| [X] Automatically create a safety backup before applying app updates   |
|                                                                         |
| Recent Snapshots:                                                       |
| • 2026-08-18 (Pre-Update v0.0.1282) - 14.2 GB      [Restore] [Delete]   |
| • 2026-08-10 (Manual Backup) - 11.8 GB             [Restore] [Delete]   |
+-------------------------------------------------------------------------+

---

6. Acceptance Criteria

• CreateFullBackupAsync packages Profiles, Manifests, Settings, and CAS objects into a .ghbak archive.
• InspectBackupAsync reads and validates the archive manifest without extracting all multi-GB blobs into RAM.
• RestoreFullBackupAsync restores CAS blobs into the target CAS pool, verifies SHA-256 integrity, and restores manifests and profiles.
• Pre-update hook in VelopackUpdateManager captures an automatic snapshot before executing update installation.
• Full unit and integration test suite in GenHub.Tests.Core.

[coderabbitai]

🔗 Related PRs

#267 - feat: Implement copy profile functionality [merged]
#312 - fix: disable unsafe CAS garbage collection [merged]
#349 - fix(cas): fall back from unwritable installation pools [merged]
#374 - feat(userdata): deploy GeneralsOnline game data patch to user documents with safe backup and restore [merged]
#375 - feat(gameprofiles): enable runtime content hot-swapping for active game sessions [open]
#384 - fix(config): preserve profiles, settings and workspace metadata across the v0.0.3 upgrade [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Reuse existing storage abstractions (IGameProfileRepository, IUserSettingsService, IContentManifestPool, ICasService/ICasStorage) for enumeration and restore. This avoids duplicated path-resolution logic and reuses CAS verification.
• Build the .ghbak container with System.IO.Compression.ZipArchive and Deflate. Stream CAS blobs to avoid loading multi-GB data into memory. Inspect reads only backup-manifest.json.
• Restore in dependency order: CAS blobs, then manifests, then profiles, then settings. Verify SHA-256 through ICasService.StoreContentAsync(stream, expectedHash).
• Add the pre-update snapshot as an optional, bounded, non-fatal hook in VelopackUpdateManager. Expose all actions through a new "Backup & Recovery" Settings section, following existing MVVM and notification patterns.

Design Choices

Design Choice 1: Archive library for the `.ghbak` container

Options Considered:

1. System.IO.Compression.ZipArchive/ZipFile with Deflate. Already used for extraction. No new dependency.
2. SharpCompress. Already a dependency, supports write APIs, but has no archive-creation precedent in this repo.

Chosen Option: 1

Rationale: System.IO.Compression.ZipArchive provides streaming entry read/write, supports per-entry inspection without full extraction, and needs no new dependency. The ticket mentions "Deflate / Zstandard". Zstandard is not available in the codebase.

Design Choice 2: How CAS blobs are written back during restore

Options Considered:

1. Copy blob files directly to objects/{hash[0:2]}/{hash} paths.
2. Read each blob stream and call ICasService.StoreContentAsync(stream, expectedHash).

Chosen Option: 2

Rationale: StoreContentAsync with expectedHash reuses the existing atomic write, locking, dedup, and verify-on-write logic. It also resolves the authoritative pool root without duplicating path logic. The blobs must land in the correct CAS pool and must pass SHA-256 verification.

Design Choice 3: Location of the pre-update snapshot hook

Options Considered:

1. Add the hook inside VelopackUpdateManager apply methods.
2. Add the hook at the UpdateNotificationViewModel call site.

Chosen Option: 1

Rationale: The ticket requires the hook in VelopackUpdateManager. Run the backup after download and before apply, with a bounded timeout, and treat failure as non-fatal. The update apply methods are synchronous and can terminate the process.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Core Models and Interface

This phase defines the contract and data shapes for the backup feature. It groups the interface and all supporting models so later phases have stable types to depend on. All new types go in GenHub.Core.

Task 1: Add the backup service interface

Define the public contract for backup, inspect, and restore.

• Create IFullSystemBackupService in GenHub/GenHub.Core/Interfaces/Storage/.
• Declare CreateFullBackupAsync(string destinationDirectory, IProgress<BackupProgress>?, CancellationToken) returning Task<OperationResult<string>> (the created archive path).
• Declare InspectBackupAsync(string backupFilePath, CancellationToken) returning Task<OperationResult<BackupSummary>>.
• Declare RestoreFullBackupAsync(string backupFilePath, RestoreOptions options, IProgress<RestoreProgress>?, CancellationToken) returning Task<OperationResult<RestoreResult>>.

Task 2: Add backup metadata and result models

Define the archive metadata and operation result models.

• Create BackupManifest in GenHub/GenHub.Core/Models/Storage/ with SchemaVersion, AppVersion, CreatedAt, ProfileCount, ManifestCount, TotalCasBytes, CasObjectCount, and CasHashIndex (a Dictionary<string,string> mapping hash to archive entry path).
• Create BackupSummary in the same directory to expose inspected metadata (app version, created date, counts, total CAS bytes, schema version) for UI display.
• Create RestoreResult with restored counts (profiles, manifests, CAS objects), verified object count, and any integrity-issue details reusing the existing CasValidationIssue shape where useful.
• Create RestoreOptions with flags for what to restore (settings, profiles, manifests, CAS) and an overwrite/skip-existing policy.

Task 3: Add progress models

Define progress models that mirror existing progress conventions.

• Create BackupProgress and RestoreProgress in GenHub/GenHub.Core/Models/Storage/.
• Add a BackupPhase enum and a RestorePhase enum (for example Preparing, Settings, Profiles, Manifests, CasObjects, Verifying, Completed) following the pattern of ContentAcquisitionPhase.
• Include phase, CurrentOperation text, FilesProcessed/TotalFiles, BytesProcessed/TotalBytes, a computed PercentComplete, and IsCompleted/HasError/ErrorMessage fields, matching WorkspacePreparationProgress and UpdateProgress.

Task 4: Add backup settings to UserSettings

Add persisted settings that control automatic snapshots and backup location.

• Update GenHub/GenHub.Core/Models/Common/UserSettings.cs to add EnableAutomaticPreUpdateBackup (bool) and an optional BackupDirectory (string?).
• Add both new properties to the Clone() deep-copy logic.
• Follow existing naming conventions (Enable prefix for the toggle, nullable string for the optional path).

🤖 Prompt for AI agents

Implement Phase 1: define the contract and data shapes for the backup feature in
`GenHub.Core`, so later phases have stable types to depend on.

- Create `IFullSystemBackupService` in `GenHub/GenHub.Core/Interfaces/Storage/`
with three methods: `CreateFullBackupAsync(string destinationDirectory,
IProgress<BackupProgress>?, CancellationToken)` returning
`Task<OperationResult<string>>` (the created archive path),
`InspectBackupAsync(string backupFilePath, CancellationToken)` returning
`Task<OperationResult<BackupSummary>>`, and `RestoreFullBackupAsync(string
backupFilePath, RestoreOptions options, IProgress<RestoreProgress>?,
CancellationToken)` returning `Task<OperationResult<RestoreResult>>`.

- In `GenHub/GenHub.Core/Models/Storage/`, create `BackupManifest` with
`SchemaVersion`, `AppVersion`, `CreatedAt`, `ProfileCount`, `ManifestCount`,
`TotalCasBytes`, `CasObjectCount`, and `CasHashIndex`
(`Dictionary<string,string>` mapping hash to archive entry path). Create
`BackupSummary` exposing inspected metadata (app version, created date, counts,
total CAS bytes, schema version). Create `RestoreResult` with restored counts
(profiles, manifests, CAS objects), verified object count, and integrity-issue
details, reusing the existing `CasValidationIssue` shape where useful. Create
`RestoreOptions` with flags for what to restore (settings, profiles, manifests,
CAS) and an overwrite/skip-existing policy.

- In the same directory, create `BackupProgress` and `RestoreProgress`, plus a
`BackupPhase` enum and a `RestorePhase` enum (for example `Preparing`,
`Settings`, `Profiles`, `Manifests`, `CasObjects`, `Verifying`, `Completed`),
following the pattern of `ContentAcquisitionPhase`. Include phase,
`CurrentOperation` text, `FilesProcessed`/`TotalFiles`,
`BytesProcessed`/`TotalBytes`, a computed `PercentComplete`, and
`IsCompleted`/`HasError`/`ErrorMessage` fields, matching
`WorkspacePreparationProgress` and `UpdateProgress`.

- Update `GenHub/GenHub.Core/Models/Common/UserSettings.cs` to add
`EnableAutomaticPreUpdateBackup` (bool) and an optional `BackupDirectory`
(string?). Add both properties to the `Clone()` deep-copy logic. Follow existing
naming conventions.

Phase 2: Backup Service Implementation and DI Wiring

This phase implements the backup, inspect, and restore logic and registers the service in DI. The service reuses existing storage abstractions instead of reimplementing path resolution.

Task 1: Implement the backup service

Create the concrete service that reads and writes the .ghbak archive.

• Create FullSystemBackupService in GenHub/GenHub/Features/Storage/Services/.
• Inject IGameProfileRepository, IUserSettingsService, IContentManifestPool, ICasService, ICasStorage, IConfigurationProviderService, and ILogger<FullSystemBackupService>.
• Use the primary-constructor DI style used by sibling storage services.
• Follow the OperationResult<T> factory pattern (CreateSuccess/CreateFailure) and measure elapsed time with Stopwatch.
• Report progress through the injected IProgress<T> on phase transitions and per-object during CAS work.

Task 2: Implement `CreateFullBackupAsync`

Package all data into a single deduplicated ZIP archive.

• Resolve the destination path. Default the archive name to a timestamped backup_{yyyy-MM-dd_HHmmss}.ghbak under the configured backup directory (default %AppData%\GenHub\Backups using DirectoryNames.Backups).
• Open a ZipArchive in Create mode with CompressionLevel.Optimal (Deflate).
• Serialize current UserSettings from IUserSettingsService.Get() into settings/user-settings.json.
• Enumerate profiles with IGameProfileRepository.LoadAllProfilesAsync and write each as profiles/{profileId}.json.
• Enumerate manifests with IContentManifestPool.GetAllManifestsAsync and write each as manifests/{manifestId}.manifest.json.
• Enumerate CAS blobs with ICasStorage.GetAllObjectHashesAsync, open each with ICasStorage.OpenObjectStreamAsync, and stream each into cas-pool/{hash[0:2]}/{hash}. CAS is already hash-deduplicated, so each blob is written once.
• Build and write backup-manifest.json last, filling counts, TotalCasBytes, AppVersion, and CasHashIndex.
• Wrap disk work in try/catch, log through ILogger, and return the archive path on success.

Task 3: Implement `InspectBackupAsync`

Read archive metadata without extracting large blobs.

• Open the archive with ZipFile.OpenRead.
• Locate only the backup-manifest.json entry with archive.GetEntry(...).
• Deserialize that single entry stream into BackupManifest. Do not enumerate or extract the cas-pool/ entries.
• Map the manifest into a BackupSummary and return it. Return a failure result if the entry is missing or the schema version is unsupported.

Task 4: Implement `RestoreFullBackupAsync`

Restore all data and verify CAS integrity.

• Open the archive with ZipFile.OpenRead.
• Read and validate backup-manifest.json first (reuse the inspect logic).
• For each cas-pool/ entry, open the entry stream and call ICasService.StoreContentAsync(stream, expectedHash) where expectedHash is the blob filename. This reuses atomic write, dedup, and verify-on-write and reports any mismatch.
• Restore manifests: deserialize each manifests/*.manifest.json entry into a ContentManifest and persist it. Prefer IContentManifestPool.AddManifestAsync (overwrite semantics) after the referenced CAS blobs exist.
• Restore profiles: deserialize each profiles/*.json entry into a GameProfile and call IGameProfileRepository.SaveProfileAsync (overwrites by matching Id).
• Restore settings: deserialize settings/user-settings.json and persist through IUserSettingsService (mutate then SaveAsync), honoring RestoreOptions policy.
• Order the steps so CAS blobs restore before manifests and manifests before profiles, because profiles depend on manifests and manifests depend on CAS blobs.
• Optionally run ICasService.ValidateIntegrityAsync for restored hashes and record results in RestoreResult.
• Honor RestoreOptions selective flags and overwrite policy. Report progress per phase and per object.

Task 5: Register the backup service in DI

Wire the service so the update flow and Settings UI can resolve it.

• Register IFullSystemBackupService → FullSystemBackupService in an existing storage-related module (for example CasModule.AddCasServices) or a new AddBackupServices extension, following the Add{Feature}Services convention.
• Use AddSingleton to match sibling storage service lifetimes.

🤖 Prompt for AI agents

Implement Phase 2: build the backup, inspect, and restore logic in
`FullSystemBackupService`, and register it in DI. Reuse existing storage
abstractions instead of reimplementing path resolution.

- Create `FullSystemBackupService` in
`GenHub/GenHub/Features/Storage/Services/`. Inject `IGameProfileRepository`,
`IUserSettingsService`, `IContentManifestPool`, `ICasService`, `ICasStorage`,
`IConfigurationProviderService`, and `ILogger<FullSystemBackupService>` using
the primary-constructor DI style used by sibling storage services. Follow the
`OperationResult<T>` factory pattern (`CreateSuccess`/`CreateFailure`) and
measure elapsed time with `Stopwatch`. Report progress through the injected
`IProgress<T>` on phase transitions and per-object during CAS work.

- Implement `CreateFullBackupAsync`: resolve the destination path, defaulting
the archive name to a timestamped `backup_{yyyy-MM-dd_HHmmss}.ghbak` under the
configured backup directory (default `%AppData%\GenHub\Backups` using
`DirectoryNames.Backups`). Open a `ZipArchive` in `Create` mode with
`CompressionLevel.Optimal` (Deflate). Serialize current `UserSettings` from
`IUserSettingsService.Get()` into `settings/user-settings.json`. Enumerate
profiles with `IGameProfileRepository.LoadAllProfilesAsync` and write each as
`profiles/{profileId}.json`. Enumerate manifests with
`IContentManifestPool.GetAllManifestsAsync` and write each as
`manifests/{manifestId}.manifest.json`. Enumerate CAS blobs with
`ICasStorage.GetAllObjectHashesAsync`, open each with
`ICasStorage.OpenObjectStreamAsync`, and stream each into
`cas-pool/{hash[0:2]}/{hash}` (CAS is already hash-deduplicated, so each blob is
written once). Build and write `backup-manifest.json` last, filling counts,
`TotalCasBytes`, `AppVersion`, and `CasHashIndex`. Wrap disk work in try/catch,
log through `ILogger`, and return the archive path on success.

- Implement `InspectBackupAsync`: open the archive with `ZipFile.OpenRead`,
locate only the `backup-manifest.json` entry with `archive.GetEntry(...)`, and
deserialize just that entry into `BackupManifest` without enumerating or
extracting `cas-pool/` entries. Map the manifest into a `BackupSummary` and
return it. Return a failure result if the entry is missing or the schema version
is unsupported.

- Implement `RestoreFullBackupAsync`: open the archive with `ZipFile.OpenRead`
and validate `backup-manifest.json` first (reuse the inspect logic). For each
`cas-pool/` entry, open the entry stream and call
`ICasService.StoreContentAsync(stream, expectedHash)` where `expectedHash` is
the blob filename, reusing atomic write, dedup, and verify-on-write, and
reporting any mismatch. Restore manifests by deserializing each
`manifests/*.manifest.json` entry into a `ContentManifest` and persisting it,
preferring `IContentManifestPool.AddManifestAsync` (overwrite semantics) after
the referenced CAS blobs exist. Restore profiles by deserializing each
`profiles/*.json` entry into a `GameProfile` and calling
`IGameProfileRepository.SaveProfileAsync` (overwrites by matching `Id`). Restore
settings by deserializing `settings/user-settings.json` and persisting through
`IUserSettingsService` (mutate then `SaveAsync`), honoring `RestoreOptions`
policy. Order the steps so CAS blobs restore before manifests and manifests
before profiles, because profiles depend on manifests and manifests depend on
CAS blobs. Optionally run `ICasService.ValidateIntegrityAsync` for restored
hashes and record results in `RestoreResult`. Honor `RestoreOptions` selective
flags and overwrite policy, and report progress per phase and per object.

- Register `IFullSystemBackupService` → `FullSystemBackupService` in an existing
storage-related module (for example `CasModule.AddCasServices`) or a new
`AddBackupServices` extension, following the `Add{Feature}Services` convention,
using `AddSingleton` to match sibling storage service lifetimes.

Phase 3: Pre-Update Automatic Snapshot Hook

This phase adds the automatic snapshot before an update installs. The hook must not block the update indefinitely and must degrade gracefully on failure.

Task 1: Inject the backup service into the update manager

Add an optional dependency so the update manager can trigger a snapshot.

• Update GenHub/GenHub/Features/AppUpdate/Services/VelopackUpdateManager.cs to accept an optional IFullSystemBackupService? and an optional IUserSettingsService? (if not already present) through the constructor, matching the existing optional-service injection style.

Task 2: Run the snapshot before apply

Create the snapshot after download and before install.

• Add a private async pre-step that runs before the Velopack apply call in ApplyUpdatesAndRestart and ApplyUpdatesAndExit.
• Only run the snapshot when EnableAutomaticPreUpdateBackup is true.
• Call CreateFullBackupAsync with a bounded timeout using Task.WaitAsync(TimeSpan, CancellationToken).
• Treat timeout or failure as non-fatal: log a warning and continue the update, matching the existing graceful-degradation pattern in the apply fallback block.
• Since the apply methods are synchronous void, run the awaited pre-step in a controlled manner (for example .GetAwaiter().GetResult() inside a guarded block) so the process does not restart before the snapshot completes.

🤖 Prompt for AI agents

Implement Phase 3: add an automatic snapshot before an update installs. The hook
must not block the update indefinitely and must degrade gracefully on failure.

- Update `GenHub/GenHub/Features/AppUpdate/Services/VelopackUpdateManager.cs` to
accept an optional `IFullSystemBackupService?` and, if not already present, an
optional `IUserSettingsService?` through the constructor, matching the existing
optional-service injection style.

- Add a private async pre-step that runs before the Velopack apply call in
`ApplyUpdatesAndRestart` and `ApplyUpdatesAndExit`. Only run the snapshot when
`EnableAutomaticPreUpdateBackup` is true. Call `CreateFullBackupAsync` with a
bounded timeout using `Task.WaitAsync(TimeSpan, CancellationToken)`. Treat
timeout or failure as non-fatal: log a warning and continue the update, matching
the existing graceful-degradation pattern in the apply fallback block. Because
the apply methods are synchronous `void`, run the awaited pre-step in a
controlled manner (for example `.GetAwaiter().GetResult()` inside a guarded
block) so the process does not restart before the snapshot completes.

Phase 4: Settings UI Integration

This phase adds the "Backup & Recovery" section to Settings. It follows the existing ViewModel and view conventions.

Task 1: Add ViewModel state and commands

Add observable state and commands for backup and restore actions.

• Update GenHub/GenHub/Features/Settings/ViewModels/SettingsViewModel.cs to inject IFullSystemBackupService.
• Add [ObservableProperty] fields for EnableAutomaticPreUpdateBackup, backup directory, live progress (BackupProgress/RestoreProgress), and totals (CAS bytes/object count, profile count, manifest count) for the wireframe summary line.
• Add [RelayCommand] methods CreateFullBackup, RestoreFromBackup, and BrowseBackupDirectory using the existing IStorageProvider picker pattern.
• Bind progress ticks to observable fields through Dispatcher.UIThread.InvokeAsync, following the update/downloads progress pattern.
• Use INotificationService.ShowSuccess/ShowError/ShowWarning for terminal results, matching the Danger Zone command pattern.
• Load and persist EnableAutomaticPreUpdateBackup and backup directory in LoadSettings() and the SaveSettings update block.

Task 2: Add the Backup & Recovery view section

Add the UI section to the Settings view.

• Update GenHub/GenHub/Features/Settings/Views/SettingsView.axaml to add a new Expander using the shared Border.settings-card, TextBlock.section-header, and setting-label/setting-description styles.
• Add the summary line (CAS pool size and object count, profile count, manifest count).
• Add the "Create Full System Backup (.ghbak)" and "Restore From Backup..." buttons, the automatic-snapshot checkbox, and a progress bar bound to the ViewModel progress fields.

🤖 Prompt for AI agents

Implement Phase 4: add a "Backup & Recovery" section to Settings, following the
existing ViewModel and view conventions.

- Update `GenHub/GenHub/Features/Settings/ViewModels/SettingsViewModel.cs` to
inject `IFullSystemBackupService`. Add `[ObservableProperty]` fields for
`EnableAutomaticPreUpdateBackup`, backup directory, live progress
(`BackupProgress`/`RestoreProgress`), and totals (CAS bytes/object count,
profile count, manifest count) for the wireframe summary line. Add
`[RelayCommand]` methods `CreateFullBackup`, `RestoreFromBackup`, and
`BrowseBackupDirectory` using the existing `IStorageProvider` picker pattern.
Bind progress ticks to observable fields through
`Dispatcher.UIThread.InvokeAsync`, following the update/downloads progress
pattern. Use `INotificationService.ShowSuccess`/`ShowError`/`ShowWarning` for
terminal results, matching the Danger Zone command pattern. Load and persist
`EnableAutomaticPreUpdateBackup` and backup directory in `LoadSettings()` and
the `SaveSettings` update block.

- Update `GenHub/GenHub/Features/Settings/Views/SettingsView.axaml` to add a new
`Expander` using the shared `Border.settings-card`, `TextBlock.section-header`,
and `setting-label`/`setting-description` styles. Add the summary line (CAS pool
size and object count, profile count, manifest count). Add the "Create Full
System Backup (.ghbak)" and "Restore From Backup..." buttons, the
automatic-snapshot checkbox, and a progress bar bound to the ViewModel progress
fields.

Phase 5: Testing

This phase adds unit and integration tests in GenHub.Tests.Core, following the established temp-directory and DI-container conventions.

Task 1: Add unit tests for models and inspect logic

Verify model behavior and archive inspection without large blobs.

• Add tests for BackupManifest/BackupSummary/RestoreResult serialization and BackupProgress/RestoreProgress computed percentages.
• Add a test that InspectBackupAsync reads a crafted .ghbak archive and returns correct counts without extracting cas-pool/ entries.

Task 2: Add integration tests for backup and restore round-trip

Verify a full create-then-restore cycle.

• Create BackupServiceIntegrationTests in GenHub/GenHub.Tests/GenHub.Tests.Core/Features/Storage/.
• Follow the WorkspaceCasIntegrationTests pattern: create guid-named temp directories, configure CasConfiguration.CasRootPath to a temp dir, mock IConfigurationProviderService, register real Sha256HashProvider, CasStorage, CasReferenceTracker, and CasService.
• Seed sample profiles, manifests, settings, and CAS blobs, call CreateFullBackupAsync, then restore into a fresh temp environment and assert that CAS blobs, manifests, profiles, and settings match and pass SHA-256 verification.
• Implement IDisposable cleanup of all temp directories.
• Add per-test-class helper methods (CreateTestManifest, CreateTestProfile) following the sibling test convention (no shared fixture exists).

Task 3: Add a test for the pre-update snapshot hook

Verify the hook triggers and degrades gracefully.

• Add a unit test that verifies CreateFullBackupAsync is called before apply when EnableAutomaticPreUpdateBackup is true.
• Add a test that verifies a backup failure or timeout does not abort the update flow (non-fatal behavior).

🤖 Prompt for AI agents

Implement Phase 5: add unit and integration tests in `GenHub.Tests.Core`,
following the established temp-directory and DI-container conventions.

- Add unit tests for `BackupManifest`/`BackupSummary`/`RestoreResult`
serialization and for `BackupProgress`/`RestoreProgress` computed percentages.
Add a test that `InspectBackupAsync` reads a crafted `.ghbak` archive and
returns correct counts without extracting `cas-pool/` entries.

- Create `BackupServiceIntegrationTests` in
`GenHub/GenHub.Tests/GenHub.Tests.Core/Features/Storage/`, following the
`WorkspaceCasIntegrationTests` pattern: create guid-named temp directories,
configure `CasConfiguration.CasRootPath` to a temp dir, mock
`IConfigurationProviderService`, and register real `Sha256HashProvider`,
`CasStorage`, `CasReferenceTracker`, and `CasService`. Seed sample profiles,
manifests, settings, and CAS blobs, call `CreateFullBackupAsync`, then restore
into a fresh temp environment and assert that CAS blobs, manifests, profiles,
and settings match and pass SHA-256 verification. Implement `IDisposable`
cleanup of all temp directories. Add per-test-class helper methods
(`CreateTestManifest`, `CreateTestProfile`) following the sibling test
convention, since no shared fixture exists.

- Add a unit test that verifies `CreateFullBackupAsync` is called before apply
when `EnableAutomaticPreUpdateBackup` is true, and a test that verifies a backup
failure or timeout does not abort the update flow (non-fatal behavior).

Research

GenHub separates configuration from binary assets. GameProfiles persist as one JSON file per profile through IGameProfileRepository. UserSettings persist as a single JSON blob through IUserSettingsService. ContentManifests persist as *.manifest.json files through IContentManifestPool. Binary content persists as SHA-256-addressed blobs in the CAS pool through ICasService/ICasStorage, sharded as objects/{hash[0:2]}/{hash}. Each ManifestFile with SourceType == ContentAddressable references a CAS blob by Hash.

The app already uses System.IO.Compression.ZipFile for extraction (no archive-creation precedent yet), SharpCompress for 7z reads, and Velopack for updates through VelopackUpdateManager. Results follow the OperationResult<T> factory pattern. Progress uses IProgress<T> with mutable POCO progress models. Settings UI uses CommunityToolkit.Mvvm with per-section Expander blocks and INotificationService for terminal toasts. DI modules follow the Add{Feature}Services extension pattern.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: define the contract and data shapes for the backup feature in
`GenHub.Core`, so later phases have stable types to depend on.

- Create `IFullSystemBackupService` in `GenHub/GenHub.Core/Interfaces/Storage/`
with three methods: `CreateFullBackupAsync(string destinationDirectory,
IProgress<BackupProgress>?, CancellationToken)` returning
`Task<OperationResult<string>>` (the created archive path),
`InspectBackupAsync(string backupFilePath, CancellationToken)` returning
`Task<OperationResult<BackupSummary>>`, and `RestoreFullBackupAsync(string
backupFilePath, RestoreOptions options, IProgress<RestoreProgress>?,
CancellationToken)` returning `Task<OperationResult<RestoreResult>>`.

- In `GenHub/GenHub.Core/Models/Storage/`, create `BackupManifest` with
`SchemaVersion`, `AppVersion`, `CreatedAt`, `ProfileCount`, `ManifestCount`,
`TotalCasBytes`, `CasObjectCount`, and `CasHashIndex`
(`Dictionary<string,string>` mapping hash to archive entry path). Create
`BackupSummary` exposing inspected metadata (app version, created date, counts,
total CAS bytes, schema version). Create `RestoreResult` with restored counts
(profiles, manifests, CAS objects), verified object count, and integrity-issue
details, reusing the existing `CasValidationIssue` shape where useful. Create
`RestoreOptions` with flags for what to restore (settings, profiles, manifests,
CAS) and an overwrite/skip-existing policy.

- In the same directory, create `BackupProgress` and `RestoreProgress`, plus a
`BackupPhase` enum and a `RestorePhase` enum (for example `Preparing`,
`Settings`, `Profiles`, `Manifests`, `CasObjects`, `Verifying`, `Completed`),
following the pattern of `ContentAcquisitionPhase`. Include phase,
`CurrentOperation` text, `FilesProcessed`/`TotalFiles`,
`BytesProcessed`/`TotalBytes`, a computed `PercentComplete`, and
`IsCompleted`/`HasError`/`ErrorMessage` fields, matching
`WorkspacePreparationProgress` and `UpdateProgress`.

- Update `GenHub/GenHub.Core/Models/Common/UserSettings.cs` to add
`EnableAutomaticPreUpdateBackup` (bool) and an optional `BackupDirectory`
(string?). Add both properties to the `Clone()` deep-copy logic. Follow existing
naming conventions.
===============================================================================

Task: 2

Implement Phase 2: build the backup, inspect, and restore logic in
`FullSystemBackupService`, and register it in DI. Reuse existing storage
abstractions instead of reimplementing path resolution.

- Create `FullSystemBackupService` in
`GenHub/GenHub/Features/Storage/Services/`. Inject `IGameProfileRepository`,
`IUserSettingsService`, `IContentManifestPool`, `ICasService`, `ICasStorage`,
`IConfigurationProviderService`, and `ILogger<FullSystemBackupService>` using
the primary-constructor DI style used by sibling storage services. Follow the
`OperationResult<T>` factory pattern (`CreateSuccess`/`CreateFailure`) and
measure elapsed time with `Stopwatch`. Report progress through the injected
`IProgress<T>` on phase transitions and per-object during CAS work.

- Implement `CreateFullBackupAsync`: resolve the destination path, defaulting
the archive name to a timestamped `backup_{yyyy-MM-dd_HHmmss}.ghbak` under the
configured backup directory (default `%AppData%\GenHub\Backups` using
`DirectoryNames.Backups`). Open a `ZipArchive` in `Create` mode with
`CompressionLevel.Optimal` (Deflate). Serialize current `UserSettings` from
`IUserSettingsService.Get()` into `settings/user-settings.json`. Enumerate
profiles with `IGameProfileRepository.LoadAllProfilesAsync` and write each as
`profiles/{profileId}.json`. Enumerate manifests with
`IContentManifestPool.GetAllManifestsAsync` and write each as
`manifests/{manifestId}.manifest.json`. Enumerate CAS blobs with
`ICasStorage.GetAllObjectHashesAsync`, open each with
`ICasStorage.OpenObjectStreamAsync`, and stream each into
`cas-pool/{hash[0:2]}/{hash}` (CAS is already hash-deduplicated, so each blob is
written once). Build and write `backup-manifest.json` last, filling counts,
`TotalCasBytes`, `AppVersion`, and `CasHashIndex`. Wrap disk work in try/catch,
log through `ILogger`, and return the archive path on success.

- Implement `InspectBackupAsync`: open the archive with `ZipFile.OpenRead`,
locate only the `backup-manifest.json` entry with `archive.GetEntry(...)`, and
deserialize just that entry into `BackupManifest` without enumerating or
extracting `cas-pool/` entries. Map the manifest into a `BackupSummary` and
return it. Return a failure result if the entry is missing or the schema version
is unsupported.

- Implement `RestoreFullBackupAsync`: open the archive with `ZipFile.OpenRead`
and validate `backup-manifest.json` first (reuse the inspect logic). For each
`cas-pool/` entry, open the entry stream and call
`ICasService.StoreContentAsync(stream, expectedHash)` where `expectedHash` is
the blob filename, reusing atomic write, dedup, and verify-on-write, and
reporting any mismatch. Restore manifests by deserializing each
`manifests/*.manifest.json` entry into a `ContentManifest` and persisting it,
preferring `IContentManifestPool.AddManifestAsync` (overwrite semantics) after
the referenced CAS blobs exist. Restore profiles by deserializing each
`profiles/*.json` entry into a `GameProfile` and calling
`IGameProfileRepository.SaveProfileAsync` (overwrites by matching `Id`). Restore
settings by deserializing `settings/user-settings.json` and persisting through
`IUserSettingsService` (mutate then `SaveAsync`), honoring `RestoreOptions`
policy. Order the steps so CAS blobs restore before manifests and manifests
before profiles, because profiles depend on manifests and manifests depend on
CAS blobs. Optionally run `ICasService.ValidateIntegrityAsync` for restored
hashes and record results in `RestoreResult`. Honor `RestoreOptions` selective
flags and overwrite policy, and report progress per phase and per object.

- Register `IFullSystemBackupService` → `FullSystemBackupService` in an existing
storage-related module (for example `CasModule.AddCasServices`) or a new
`AddBackupServices` extension, following the `Add{Feature}Services` convention,
using `AddSingleton` to match sibling storage service lifetimes.
===============================================================================

Task: 3

Implement Phase 3: add an automatic snapshot before an update installs. The hook
must not block the update indefinitely and must degrade gracefully on failure.

- Update `GenHub/GenHub/Features/AppUpdate/Services/VelopackUpdateManager.cs` to
accept an optional `IFullSystemBackupService?` and, if not already present, an
optional `IUserSettingsService?` through the constructor, matching the existing
optional-service injection style.

- Add a private async pre-step that runs before the Velopack apply call in
`ApplyUpdatesAndRestart` and `ApplyUpdatesAndExit`. Only run the snapshot when
`EnableAutomaticPreUpdateBackup` is true. Call `CreateFullBackupAsync` with a
bounded timeout using `Task.WaitAsync(TimeSpan, CancellationToken)`. Treat
timeout or failure as non-fatal: log a warning and continue the update, matching
the existing graceful-degradation pattern in the apply fallback block. Because
the apply methods are synchronous `void`, run the awaited pre-step in a
controlled manner (for example `.GetAwaiter().GetResult()` inside a guarded
block) so the process does not restart before the snapshot completes.
===============================================================================

Task: 4

Implement Phase 4: add a "Backup & Recovery" section to Settings, following the
existing ViewModel and view conventions.

- Update `GenHub/GenHub/Features/Settings/ViewModels/SettingsViewModel.cs` to
inject `IFullSystemBackupService`. Add `[ObservableProperty]` fields for
`EnableAutomaticPreUpdateBackup`, backup directory, live progress
(`BackupProgress`/`RestoreProgress`), and totals (CAS bytes/object count,
profile count, manifest count) for the wireframe summary line. Add
`[RelayCommand]` methods `CreateFullBackup`, `RestoreFromBackup`, and
`BrowseBackupDirectory` using the existing `IStorageProvider` picker pattern.
Bind progress ticks to observable fields through
`Dispatcher.UIThread.InvokeAsync`, following the update/downloads progress
pattern. Use `INotificationService.ShowSuccess`/`ShowError`/`ShowWarning` for
terminal results, matching the Danger Zone command pattern. Load and persist
`EnableAutomaticPreUpdateBackup` and backup directory in `LoadSettings()` and
the `SaveSettings` update block.

- Update `GenHub/GenHub/Features/Settings/Views/SettingsView.axaml` to add a new
`Expander` using the shared `Border.settings-card`, `TextBlock.section-header`,
and `setting-label`/`setting-description` styles. Add the summary line (CAS pool
size and object count, profile count, manifest count). Add the "Create Full
System Backup (.ghbak)" and "Restore From Backup..." buttons, the
automatic-snapshot checkbox, and a progress bar bound to the ViewModel progress
fields.
===============================================================================

Task: 5

Implement Phase 5: add unit and integration tests in `GenHub.Tests.Core`,
following the established temp-directory and DI-container conventions.

- Add unit tests for `BackupManifest`/`BackupSummary`/`RestoreResult`
serialization and for `BackupProgress`/`RestoreProgress` computed percentages.
Add a test that `InspectBackupAsync` reads a crafted `.ghbak` archive and
returns correct counts without extracting `cas-pool/` entries.

- Create `BackupServiceIntegrationTests` in
`GenHub/GenHub.Tests/GenHub.Tests.Core/Features/Storage/`, following the
`WorkspaceCasIntegrationTests` pattern: create guid-named temp directories,
configure `CasConfiguration.CasRootPath` to a temp dir, mock
`IConfigurationProviderService`, and register real `Sha256HashProvider`,
`CasStorage`, `CasReferenceTracker`, and `CasService`. Seed sample profiles,
manifests, settings, and CAS blobs, call `CreateFullBackupAsync`, then restore
into a fresh temp environment and assert that CAS blobs, manifests, profiles,
and settings match and pass SHA-256 verification. Implement `IDisposable`
cleanup of all temp directories. Add per-test-class helper methods
(`CreateTestManifest`, `CreateTestProfile`) following the sibling test
convention, since no shared fixture exists.

- Add a unit test that verifies `CreateFullBackupAsync` is called before apply
when `EnableAutomaticPreUpdateBackup` is true, and a test that verifies a backup
failure or timeout does not abort the update flow (non-fatal behavior).

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!