Architecture

XB Homebrew Vault uses the MVVM pattern with CommunityToolkit.Mvvm and Avalonia UI 12, running on .NET 10.

Layered Architecture

graph TD
    subgraph Views["Views (Avalonia XAML)"]
        MW[MainWindow]
        SW[SplashWindow]
        SetupW[SetupWizardWindow]
        BV[BrowseView]
        IV[InstalledView]
        SV[SettingsView]
        TV[ToolsView]
        LV[LogsView]
        FV[FileExplorerView]
        InV[InspectorView]
        NotifP[NotificationsPanel]
        TasksP[TasksPanel]
        CW[ConnectionWindow]
        NIW[NetworkInfoWindow]
        PW[ProcessesWindow]
        SIW[SystemInfoWindow]
        CDW[CrashDataWindow]
        PerfW[PerformanceWindow]
        UsbW[UsbPermissionWindow]
        LbW[LoopbackExemptWindow]
        SS[SScreenshotWindow]
        CustW[CustomInstallWindow]
        ItemW[ItemDetailWindow]
        DelW[DeleteConfirmWindow]
        DiscW[DiscordPopup]
        SftpW[SftpInfoWindow]
    end

    subgraph ViewModels["ViewModels (CommunityToolkit.Mvvm)"]
        MVM[MainViewModel]
        BVM[BrowseViewModel]
        IVM[InstalledViewModel]
        SVM[SettingsViewModel]
        TVM[ToolsViewModel]
        FVM[FileExplorerViewModel]
        InVM[InspectorViewModel]
        CVM[ConnectionViewModel]
        NIVM[NetworkInfoViewModel]
        PVM[ProcessesViewModel]
        SIVM[SystemInfoViewModel]
        CDVM[CrashDataViewModel]
        PerfVM[PerformanceViewModel]
        RVM[RefreshViewModel]
        ConfVM[ConfirmViewModel]
        CIWM[CustomInstallViewModel]
        SWVM[SetupWizardViewModel]
        USBVM[UsbPermissionViewModel]
        ShVM[ScreenshotViewModel]
        LbVM[LoopbackExemptViewModel]
        DelVM[DeleteConfirmViewModel]
        TkVM[TaskCenterViewModel]
    end

    subgraph Services["Services"]
        Auth[XboxAuthService]
        Pkg[XboxPackageService]
        Proc[XboxProcessService]
        Net[XboxNetworkService]
        Sys[XboxSystemService]
        Perf[XboxPerformanceService]
        Parser[XboxResponseParser]
        CAS[CatalogApiService]
        PS[PackageInstallService]
        SSvc[SettingsService]
        CS[CryptoService]
        CSvc[CacheService]
        UDD[UsbDriveDetector]
        Sftp[SftpService]
        SftpT[SftpTransferService]
        Portal[PortalAppFilesService]
        XRay[XrayAgentService]
        UpdChk[GitHubReleaseCheckerService]
        PO[PackageOverrideService]
        BgT[BackgroundTaskService]
        ConnMon[ConnectionMonitorService]
        NotifC[NotificationCenterService]
        PreF[PreFlightChecker]
        WinSet[WindowSettingsService]
        UpdCache[UpdateVersionCache]
        Colorizer[InspectorConsoleColorizer]
        PDiag[PlatformDialog]
        L[Logger]
    end

    subgraph Models["Models"]
        CI[CatalogItem]
        IP[InstalledPackage]
        PI[ProcessInfo]
        NI[NetworkInfo]
        SI[SystemInfo]
        CD[CrashDumpInfo]
        PSnap[PerformanceSnapshot]
        XC[XboxConnection]
        AS[AppSettings]
        IPI[InstallProgressInfo]
        UDI[UsbDriveInfo]
        SftpE[SftpEntry]
        XA[XrayAgentInfo]
        BgTask[BackgroundTask]
        Notif[NotificationItem]
    end

    Views --> ViewModels
    ViewModels --> Services
    Services --> Models

    style Views fill:#1A1D23,stroke:#447F3E,color:#9ACA3C
    style ViewModels fill:#1A1D23,stroke:#447F3E,color:#9ACA3C
    style Services fill:#447F3E,stroke:#9ACA3C,color:#fff
    style Models fill:#2A2D33,stroke:#447F3E,color:#9ACA3C

Data Flow

flowchart LR
    U[User Action] --> V[View]
    V -->|Command| VM[ViewModel]
    VM -->|HTTP/WS| S[Service]
    S -->|Parse| M[Model]
    M -->|Response| S
    S -->|ObservableProperty| VM
    VM -->|Binding| V
    V -->|Render| U

    style U fill:#447F3E,stroke:#9ACA3C,color:#fff
    style V fill:#2A2D33,stroke:#447F3E,color:#9ACA3C
    style VM fill:#2A2D33,stroke:#447F3E,color:#9ACA3C
    style S fill:#447F3E,stroke:#9ACA3C,color:#fff
    style M fill:#9ACA3C,stroke:#447F3E,color:#000

App Startup

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1A1D23', 'primaryBorderColor': '#447F3E', 'lineColor': '#9ACA3C', 'secondBkgColor': '#2A2D33', 'tertiaryColor': '#447F3E'}}}%%
sequenceDiagram
    autonumber
    participant User
    participant Main as Program.Main
    participant PF as PreFlightChecker
    participant App as App.axaml.cs
    participant Splash as SplashWindow
    participant SSvc as SettingsService
    participant Setup as SetupWizardWindow
    participant MainW as MainWindow

    User->>Main: Launch
    Main->>Main: Single-instance mutex check
    alt Another instance running
        Main->>Main: Activate existing window, exit
    end
    Main->>PF: Pre-flight: validate/corrupt-repair settings + cache
    Main->>App: BuildAvaloniaApp()
    App->>Splash: Show()
    Splash->>App: 2s min delay
    App->>SSvc: Load settings
    alt First run (no settings)
        App->>Setup: ShowDialog() — 3-step wizard
        Setup->>App: credentials captured
    end
    App->>App: Compose services (auth, package, system, network, process, performance, sftp, portal, cache, catalog, override)
    App->>App: Start BackgroundTaskService + ConnectionMonitorService
    App->>MainW: new MainWindow
    App->>Splash: Close()
    App->>MainW: Show()
    MainW->>MainW: Register dialog actions
    User->>MainW: Interact

Services

Verified from main code analysis (Aug 2026). Line counts approximate.

Xbox Service Split

The former XboxDeviceService god class (1,433 lines, ~41 public members, complexity 205) was split into focused services, each behind an interface:

Each takes XboxAuthService (shared connection) as its only constructor dependency. The split removed the god class; ViewModels now inject only the interfaces they need. See Refactor Proposal.

Key connection patterns (inherited from the original design):

• HTTP client recreation on Configure — a fresh HttpClient per connection works around BaseAddress immutability.
• Certificate validation bypass — self-signed console certificates; dev-only.
• CSRF token via CookieContainer — token attached automatically to requests.
• WebSocket for performance — real-time metrics stream, separate from the REST surface.

ViewModel → Service Dependency Map

graph LR
    MVM[MainViewModel] --> Auth
    BVM[BrowseViewModel] --> CAS
    BVM --> CSvc
    BVM --> Auth
    BVM --> Pkg
    BVM --> PS
    BVM --> PO
    IVM[InstalledViewModel] --> Auth
    IVM --> Pkg
    FVM[FileExplorerViewModel] --> Auth
    FVM --> Sftp
    FVM --> SftpT
    FVM --> Portal
    SVM[SettingsViewModel] --> Auth
    SVM --> CSvc
    TVM[ToolsViewModel] --> Auth
    TVM --> Sys
    CVM[ConnectionViewModel] --> Auth
    CVM --> Net
    NIVM[NetworkInfoViewModel] --> Net
    PVM[ProcessesViewModel] --> Proc
    SIVM[SystemInfoViewModel] --> Auth
    SIVM --> Sys
    CDVM[CrashDataViewModel] --> Auth
    CDVM --> Sys
    PerfVM[PerformanceViewModel] --> Auth
    PerfVM --> Perf
    RVM[RefreshViewModel] --> CAS
    CIWM[CustomInstallViewModel] --> Pkg
    CIWM --> PS
    InVM[InspectorViewModel] --> Auth
    InVM --> XRay
    ShVM[ScreenshotViewModel] --> Sys
    LbVM[LoopbackExemptViewModel] --> Auth
    LbVM --> Sftp
    LbVM --> Pkg
    USBVM[UsbPermissionViewModel]
    SWVM[SetupWizardViewModel] --> Auth
    TkVM[TaskCenterViewModel] --> BgT

    Auth[XboxAuthService]
    Pkg[XboxPackageService]
    Proc[XboxProcessService]
    Net[XboxNetworkService]
    Sys[XboxSystemService]
    Perf[XboxPerformanceService]
    CAS[CatalogApiService]
    CSvc[CacheService]
    PS[PackageInstallService]
    Sftp[SftpService]
    SftpT[SftpTransferService]
    Portal[PortalAppFilesService]
    XRay[XrayAgentService]
    PO[PackageOverrideService]
    BgT[BackgroundTaskService]

DI pattern: manual composition in App.axaml.cs (no DI container). Services constructed once, shared across VMs; dialog VMs constructed per-open with the services they need.

MVVM Patterns & Conventions

The app uses CommunityToolkit.Mvvm source generators throughout.

Observable properties & commands:

[ObservableProperty]
private string? selectedItem;            // generates SelectedItem + change notification

[RelayCommand]
private async Task BrowseItemAsync() { } // generates BrowseItemCommand (IAsyncRelayCommand)

ViewModel lifecycle: constructor injection of services → synchronous setup → async initialization fired from the View (e.g. Loaded) via a [RelayCommand].

public BrowseViewModel(PackageInstallService install, IXboxAuthService auth,
    IXboxPackageService packages, CatalogApiService catalog, PackageOverrideService overrides)
{
    _install = install;
    _auth = auth;
    _packages = packages;
    _catalog = catalog;
    _overrides = overrides;
}

[RelayCommand]
private async Task LoadCatalogAsync()
{
    var items = await _catalog.FetchCatalogAsync();
    Items.Clear();
    Items.AddRange(items);               // observable update — must run on UI thread
}

Async threading convention:

• Service layer should use .ConfigureAwait(false) (no UI affinity required).
• ViewModel layer intentionally omits ConfigureAwait — observable updates must stay on the UI thread.

The codebase does not yet apply ConfigureAwait(false) in services — tracked in Tech Debt.

Navigation

flowchart TD
    MW[MainWindow] --> SB[Sidebar ListBox]
    SB -->|SelectedTab=0| BV[BrowseView]
    SB -->|SelectedTab=1| IV[InstalledView]
    SB -->|SelectedTab=2| FV[FileExplorerView]
    SB -->|SelectedTab=3| TV[ToolsView]
    SB -->|SelectedTab=4| InV[InspectorView]
    SB -->|SelectedTab=5| SV[SettingsView]
    SB -->|SelectedTab=6| LV[LogsView]
    MW -->|Dialogs| Dialogs
    MW -->|Panels| Panels
    subgraph Dialogs["Dialog Windows"]
        SetupW[SetupWizardWindow]
        CW[ConnectionWindow]
        NIW[NetworkInfoWindow]
        PW[ProcessesWindow]
        SIW[SystemInfoWindow]
        CDW[CrashDataWindow]
        PerfW[PerformanceWindow]
        CustW[CustomInstallWindow]
        ConfW[ConfirmWindow]
        RD[RefreshWindow]
        ED[ErrorDialog]
        AW[AboutWindow]
        SS[ScreenshotWindow]
        ItemW[ItemDetailWindow]
        UsbW[UsbPermissionWindow]
        SftpW[SftpInfoWindow]
        InD[InputDialog]
        DiscD[DiscordPopup]
        LbW[LoopbackExemptWindow]
        DelW[DeleteConfirmWindow]
    end
    subgraph Panels["In-Window Panels"]
        NotifP[NotificationsPanel]
        TasksP[TasksPanel]
    end

Dialogs are opened via delegate actions wired in App.axaml.cs (e.g. ShowConnectAction, ShowConfirmAsync, ShowDetailAction).

Note: FileExplorerView (tab 2) is a functional SSH/SFTP file explorer, powered by SftpService, SftpTransferService, and PortalAppFilesService. See SSH/SFTP & Path Handling.

Xbox WDP API Integration

The Xbox services communicate with the Xbox Developer Mode Device Portal:

Base URL: https://{xbox-ip}:11443 · Auth: HTTP Basic

Catalog API

CatalogApiService fetches the Emulation Revival catalog from a single JSON endpoint:

https://emulationrevival.github.io/catalog.json

The JSON is parsed into CatalogItem models covering categories: Emulator, Frontend, GamePort, App, Experimental, Media, Utility. Results are cached by CacheService (6h TTL) with a persistent disk cache and stale-fallback on API failure.

Previously: the catalog was scraped from 7 individual HTML pages using HtmlAgilityPack. That approach was replaced when Emulation Revival published the catalog.json API.

Performance WebSocket

XboxPerformanceService connects to a WebSocket endpoint for real-time performance:

wss://{xbox-ip}:11443/api/resourcemanager/processes

Receives JSON frames with PerformanceSnapshot data (CPU, memory, GPU clock, temperature per core). Rendered by PerformanceViewModel.

Settings Persistence

SettingsService reads/writes %APPDATA%/XBVault/settings.json. Passwords obfuscated by CryptoService (salt + XOR + Base64) — not encryption, just obfuscation to avoid plaintext in JSON.

USB Permission Wizard

UsbPermissionViewModel + UsbDriveDetector implement a Windows-only wizard that:

1. Lists USB drives via WMI (System.Management)
2. Grants ALL APPLICATION PACKAGES NTFS permissions via icacls
3. Includes a spinner, 1-second minimum delay, and skips protected system directories

This allows Xbox Dev Mode to read ROM/media files from USB drives.

Loopback Exempt Wizard

LoopbackExemptViewModel + LoopbackExemptWindow (opened from Tools, in both full and quick mode) automate the X-Files package loopback-exempt workflow over SFTP/package services.

Window Pattern

All dialog windows share a common template:

• WindowDecorations="None" — no OS chrome
• Background="{StaticResource SurfaceBrush}" — dark gray #1A1D23
• Root <Border> with BorderBrush="#447F3E" BorderThickness="2" Margin="1" — green border + 1px gap
• Title bar: LinearGradientBrush from #447F3E → #9ACA3C
• Close button: transparent default, #CC3333 on hover
• Content area: 20px padding
• Drag via PointerPressed="OnTitleBarPointerPressed" + BeginMoveDrag()

See Window Template for the full AXAML template.

Design Decisions & Rationale

Key architectural decisions and the reasoning behind them:

CI / Build

CI runs on every push and PR via GitHub Actions:

Release artifacts: XBVault-{version}-win-x64.zip, XBVault-{version}-win-arm64.zip, XBVault-{version}-linux-x64.zip, XBVault-{version}-linux-arm64.zip, XBVault-{version}-osx-x64.zip, XBVault-{version}-osx-arm64.zip (all self-contained, no client runtime required).

← Home · API Docs →