Downloads Flow

NOTE

This document details the Unified Downloads User Flow implemented in PR #443 (feat/downloads-browser, carved from PR #265 feat/ui-downloads), illustrating how user interaction in DownloadsBrowserViewModel connects with discovery, resolution, state tracking via ContentStateService, background download coordination via ContentDownloadCoordinator, and game profile integration.

This flowchart details the complete user journey from browsing publishers to downloading, verifying, and adding content to profiles, including state management, deduplication, and caching.

---

Table of Contents

1. User Browsing Flow
2. Content State Management
3. Publisher Selection
4. Content Acquisition Flow
5. Profile Selection Flow
6. Roadmap & External Web Scraper Pipeline
7. Content Caching Layer
8. Key Components
9. Error Handling

---

User Browsing Flow

---

Content State Management

The ContentStateService centralizes content state determination for UI display, enabling the Downloads browser to show appropriate buttons (Download, Update, Add to Profile) based on local manifest presence.

State Transitions

ContentStateService Mechanics

Location: GenHub/Features/Downloads/Services/ContentStateService.cs

The service uses the 5-segment manifest ID structure to correlate content versions:

Format: schemaVersion.userVersion.publisher.contentType.contentName
Example: 1.20240315.superhackers.patch.generals

Detection Logic:

1. Exact Match: Generates prospective manifest ID using ManifestIdGenerator.GeneratePublisherContentId(publisher, contentType, name, releaseDate) and checks IContentManifestPool.IsManifestAcquiredAsync(id).
2. Update Detection: Searches for local manifests with matching publisher, contentType, and contentName but older userVersion.
3. State Evaluation:
   • Downloaded: Exact match found in manifest pool.
   • UpdateAvailable: Older version found in pool.
   • NotDownloaded: No matching version found.

var state = await contentStateService.GetStateAsync(searchResult);
switch (state)
{
    case ContentState.NotDownloaded:
        // Show Download button
        break;
    case ContentState.UpdateAvailable:
        // Show Update button (orange accent)
        break;
    case ContentState.Downloaded:
        // Show "Add to Profile" button
        break;
}

Content State Sequence Diagram

---

Publisher Selection

---

Content Acquisition Flow

This sequence diagram illustrates the coordinated download pipeline managed by ContentDownloadCoordinator:

---

Profile Selection Flow

The ProfileSelectionViewModel provides compatibility filtering for game profiles, showing compatible profiles first and flagging incompatible profiles with warnings to prevent accidental cross-game attachment.

Profile Selection Sequence Diagram

---

Roadmap & External Web Scraper Pipeline

Web-scraping discoverers for external repositories (ModDB, CNC Labs, AOD Maps) are part of GenHub's content ingestion architecture:

• ModDB Web Ingestion: Uses Playwright for JavaScript rendering and AngleSharp for structured HTML extraction. Supports persistent browser cookies for Cloudflare clearance.
• Section Parsing: Handles separate /downloads and /addons sections with FileSectionType.Downloads vs FileSectionType.Addons.
• Planned Browser Integration: Once scraper sandboxes are finalized, these providers will be added to the downloads browser sidebar alongside static partners.

---

Content Caching Layer

The ContentCacheService provides an in-memory cache for parsed content with a configurable TTL (Time To Live). This reduces redundant network traffic and page parsing.

Cache Architecture

---

Key Components

DownloadsBrowserViewModel

Location: GenHub/Features/Downloads/ViewModels/DownloadsBrowserViewModel.cs

Property / Command	Type	Purpose
Publishers	ObservableCollection<PublisherItemViewModel>	Available content sources
SelectedPublisher	PublisherItemViewModel?	Currently selected publisher
ContentItems	ObservableCollection<ContentGridItemViewModel>	Discovered content items
CurrentFilterViewModel	IFilterPanelViewModel?	Publisher-specific filter model
DownloadContentCommand	IAsyncRelayCommand	Initiates content acquisition
AddContentToProfileCommand	IAsyncRelayCommand	Opens profile selection modal and attaches content
ViewContentCommand	IRelayCommand	Opens content detail view overlay

ContentDownloadCoordinator

Location: GenHub/Features/Downloads/Services/ContentDownloadCoordinator.cs

Method	Return Type	Purpose
DownloadContentAsync	Task<OperationResult<ContentManifest>>	Deduplicates in-flight downloads, multiplexes progress, acquires content via IContentOrchestrator, and updates ContentStateService.
IsDownloading	bool	Checks whether content is actively downloading.
TryGetDownloadProgress	bool	Retrieves current progress percentage and message for in-flight tasks.

ContentGridItemViewModel

Location: GenHub/Features/Downloads/ViewModels/ContentGridItemViewModel.cs

Property	Condition	Purpose
ShowDownloadButton	CurrentState == NotDownloaded	Shows download action
ShowUpdateButton	CurrentState == UpdateAvailable	Shows update action
ShowAddToProfileButton	CurrentState == Downloaded	Shows profile addition action
CanDownload	!IsDownloaded && !IsDownloading	Enables download button

Filter ViewModels

Location: GenHub/Features/Downloads/ViewModels/Filters/

Publisher	Filter ViewModel	Capabilities
GitHub	GitHubFilterViewModel	Sort order (recent, popular), release types
Community Outpost	CommunityOutpostFilterViewModel	Content type (tools vs. patches)
TheSuperHackers	SuperHackersFilterViewModel	Game client vs. patch releases
Static Curated	StaticPublisherFilterViewModel	Content type and target game

ContentStateService

Location: GenHub/Features/Downloads/Services/ContentStateService.cs

Method / Event	Purpose
GetStateAsync(item)	Evaluates state (NotDownloaded, UpdateAvailable, Downloaded)
GetStateByManifestIdAsync(manifestId)	Checks state for a specific manifest ID
NotifyStateChanged(contentId, newState)	Broadcasts state updates to UI subscribers
ContentStateChanged	Event raised when content state changes

---

Error Handling

---

Related Documentation

• Downloads Browser Feature Guide - Complete feature documentation.
• Downloads UI & Views Architecture - UI controls, view models, and styling.
• Content Pipeline Flow - Detailed pipeline architecture.