# msmsrep/parallelscope architecture

> Architecture diagram of the GitHub repository msmsrep/parallelscope, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/msmsrep/parallelscope
- Repository: https://github.com/msmsrep/parallelscope

## Overview

#### Purpose and Runtime
ParallelScope is a Windows WPF desktop file browser for multiple configured root folders. It presents a folder tree and file list, supports navigation and search, and maintains a local SQLite cache for faster listings/searches. It targets `net10.0-windows10.0.19041.0`; startup is defined by `App.xaml` and `App.xaml.cs`.

#### UI Entry Points and Composition
`MainWindow.xaml` is the primary browsing shell, with code-behind in `MainWindow.xaml.cs`. `SettingsWindow.xaml` provides root-folder and display-column configuration, backed by `SettingsWindow.xaml.cs`. UI behavior is predominantly organized through `ViewModels/MainWindowViewModel.cs`, rather than the views themselves.

#### Main Browser State and Navigation
`MainWindowViewModel` is split by responsibility: navigation/history and direct paths in `ViewModels/MainWindowViewModel.Navigation.cs`; file-list state in `ViewModels/MainWindowViewModel.FileItems.cs`; and tree/flat “All Files” presentation in `ViewModels/MainWindowViewModel.FlatView.cs`. Item-level UI representations distinguish files and folders through `ViewModels/FileItemViewModel.cs` and `ViewModels/FolderItemViewModel.cs`.

#### Scan, Cache, and Search Flow
Browsing and search first use the local cache, with live filesystem scanning as fallback when cache search has no matches. Scanning orchestration lives in `ViewModels/MainWindowViewModel.Scanning.cs`; search behavior, including incremental search, is in `ViewModels/MainWindowViewModel.Search.cs`; cache-specific view-model coordination is in `ViewModels/MainWindowViewModel.Cache.cs`. Results cross a boundary from filesystem paths to cached entities, then to file/folder view models for binding.

#### Persistence and Filesystem Boundaries
Settings are persisted as local JSON through `Data/AppSettingsRepository.cs` and modeled by `Data/AppSettings.cs`. Cached filesystem metadata is represented by `Data/FileSystemEntryEntity.cs` and accessed through `Data/FileCacheRepository.cs`. EF Core owns SQLite persistence via `Data/ParallelScopeDbContext.cs`, with schema evolution captured in `Migrations/`. Local-state path resolution is centralized in `Utilities/AppDataPathProvider.cs`; path normalization and availability checks isolate filesystem edge cases in `Utilities/PathNormalizer.cs` and `Utilities/DirectoryAvailabilityChecker.cs`.

#### Platform and Store Integration
The app opens files using Windows-default behavior and obtains shell icons through `Utilities/WindowsShellIconProvider.cs`. Microsoft Store subscription/license state gates the Plus-only display-column customization feature through `Services/StoreLicenseService.cs`; billing and payment remain Microsoft Store responsibilities. Deployment metadata is in `AppxManifest.xml`, while theme/version behavior is encapsulated by `Utilities/AppTheme.cs` and `Utilities/AppVersionProvider.cs`.

Main entry points: [`ViewModels/MainWindowViewModel.cs`](https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.cs) (Main window view model), [`ViewModels/MainWindowViewModel.Scanning.cs`](https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.Scanning.cs) (Scan orchestration), [`Data/FileCacheRepository.cs`](https://github.com/msmsrep/parallelscope/blob/main/Data/FileCacheRepository.cs) (File cache repository), [`ViewModels/MainWindowViewModel.Search.cs`](https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.Search.cs) (Incremental search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["WPF UI"]
  node_app["Application startup<br/>WPF app<br/>[App.xaml]"]
  node_main_window["Browser shell<br/>WPF window<br/>[MainWindow.xaml]"]
  node_settings_window["Settings window<br/>WPF window"]
end

subgraph group_browser["Browser state"]
  node_main_vm["Main window view model"]
  node_navigation["Navigation and history<br/>view-model module"]
  node_file_list["File-list state<br/>view-model module"]
  node_flat_view["All Files view<br/>view-model module"]
  node_scan["Scan orchestration<br/>view-model module"]
  node_search["Incremental search<br/>view-model module"]
  node_cache_vm["Cache coordination<br/>view-model module"]
  node_item_models["File and folder items<br/>UI item models"]
end

subgraph group_storage["Local persistence"]
  node_settings_repo["Settings repository<br/>JSON repository"]
  node_app_settings["Application settings<br/>settings model<br/>[AppSettings.cs]"]
  node_cache_repo["File cache repository<br/>EF repository"]
  node_cache_entity["Filesystem cache entry<br/>EF entity"]
  node_db_context[("SQLite cache database<br/>EF Core context")]
end

subgraph group_platform["Windows and Store"]
  node_paths["Filesystem path boundary<br/>path utilities"]
  node_shell_icons["Windows shell integration<br/>shell icon provider"]
  node_store_license["Store license gate<br/>license service"]
  node_app_manifest["Package manifest<br/>deployment metadata<br/>[AppxManifest.xml]"]
end

node_app -->|"opens"| node_main_window
node_app -->|"packaged by"| node_app_manifest
node_main_window -->|"binds to"| node_main_vm
node_settings_window -->|"loads and saves"| node_settings_repo
node_settings_window -->|"checks Plus feature"| node_store_license
node_main_vm -->|"composes"| node_navigation
node_main_vm -->|"composes"| node_file_list
node_main_vm -->|"composes"| node_flat_view
node_main_vm -->|"orchestrates"| node_scan
node_main_vm -->|"orchestrates"| node_search
node_main_vm -->|"coordinates"| node_cache_vm
node_navigation -->|"selects location"| node_file_list
node_search -->|"queries first"| node_cache_vm
node_search -.->|"falls back on no matches"| node_scan
node_cache_vm -->|"reads and writes"| node_cache_repo
node_scan -->|"enumerates validated paths"| node_paths
node_scan -->|"caches metadata"| node_cache_repo
node_cache_repo -->|"maps"| node_cache_entity
node_cache_repo -->|"persists through"| node_db_context
node_db_context -->|"uses local data path"| node_paths
node_settings_repo -->|"serializes"| node_app_settings
node_settings_repo -->|"uses local data path"| node_paths
node_file_list -->|"presents"| node_item_models
node_flat_view -->|"presents"| node_item_models
node_item_models -->|"gets icons"| node_shell_icons

click node_app "https://github.com/msmsrep/parallelscope/blob/main/App.xaml"
click node_main_window "https://github.com/msmsrep/parallelscope/blob/main/MainWindow.xaml"
click node_settings_window "https://github.com/msmsrep/parallelscope/blob/main/SettingsWindow.xaml"
click node_main_vm "https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.cs"
click node_navigation "https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.Navigation.cs"
click node_file_list "https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.FileItems.cs"
click node_flat_view "https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.FlatView.cs"
click node_scan "https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.Scanning.cs"
click node_search "https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.Search.cs"
click node_cache_vm "https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.Cache.cs"
click node_item_models "https://github.com/msmsrep/parallelscope/blob/main/ViewModels/FileItemViewModel.cs"
click node_settings_repo "https://github.com/msmsrep/parallelscope/blob/main/Data/AppSettingsRepository.cs"
click node_app_settings "https://github.com/msmsrep/parallelscope/blob/main/Data/AppSettings.cs"
click node_cache_repo "https://github.com/msmsrep/parallelscope/blob/main/Data/FileCacheRepository.cs"
click node_cache_entity "https://github.com/msmsrep/parallelscope/blob/main/Data/FileSystemEntryEntity.cs"
click node_db_context "https://github.com/msmsrep/parallelscope/blob/main/Data/ParallelScopeDbContext.cs"
click node_paths "https://github.com/msmsrep/parallelscope/blob/main/Utilities/AppDataPathProvider.cs"
click node_shell_icons "https://github.com/msmsrep/parallelscope/blob/main/Utilities/WindowsShellIconProvider.cs"
click node_store_license "https://github.com/msmsrep/parallelscope/blob/main/Services/StoreLicenseService.cs"
click node_app_manifest "https://github.com/msmsrep/parallelscope/blob/main/AppxManifest.xml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_main_window,node_settings_window toneBlue
class node_main_vm,node_navigation,node_file_list,node_flat_view,node_scan,node_search,node_cache_vm,node_item_models toneAmber
class node_settings_repo,node_app_settings,node_cache_repo,node_cache_entity,node_db_context toneMint
class node_paths,node_shell_icons,node_store_license,node_app_manifest toneRose
```

## Components

### WPF UI

- [Application startup](https://github.com/msmsrep/parallelscope/blob/main/App.xaml): WPF app · Initializes the Windows desktop runtime. · `App.xaml`
- [Browser shell](https://github.com/msmsrep/parallelscope/blob/main/MainWindow.xaml): WPF window · `MainWindow.xaml`
- [Settings window](https://github.com/msmsrep/parallelscope/blob/main/SettingsWindow.xaml): WPF window · `SettingsWindow.xaml`

### Browser state

- [Main window view model](https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.cs): view model · Coordinates browsing, scanning, cache, and search behavior. · `ViewModels/MainWindowViewModel.cs`
- [Navigation and history](https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.Navigation.cs): view-model module · `ViewModels/MainWindowViewModel.Navigation.cs`
- [File-list state](https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.FileItems.cs): view-model module · `ViewModels/MainWindowViewModel.FileItems.cs`
- [All Files view](https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.FlatView.cs): view-model module · `ViewModels/MainWindowViewModel.FlatView.cs`
- [Scan orchestration](https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.Scanning.cs): view-model module · Falls back to live filesystem enumeration. · `ViewModels/MainWindowViewModel.Scanning.cs`
- [Incremental search](https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.Search.cs): view-model module · Queries cache before triggering a scan fallback. · `ViewModels/MainWindowViewModel.Search.cs`
- [Cache coordination](https://github.com/msmsrep/parallelscope/blob/main/ViewModels/MainWindowViewModel.Cache.cs): view-model module · `ViewModels/MainWindowViewModel.Cache.cs`
- [File and folder items](https://github.com/msmsrep/parallelscope/blob/main/ViewModels/FileItemViewModel.cs): UI item models · Binding representations for files and folders. · `ViewModels/FileItemViewModel.cs`

### Local persistence

- [Settings repository](https://github.com/msmsrep/parallelscope/blob/main/Data/AppSettingsRepository.cs): JSON repository · `Data/AppSettingsRepository.cs`
- [Application settings](https://github.com/msmsrep/parallelscope/blob/main/Data/AppSettings.cs): settings model · Configured roots and display-column preferences. · `Data/AppSettings.cs`
- [File cache repository](https://github.com/msmsrep/parallelscope/blob/main/Data/FileCacheRepository.cs): EF repository · `Data/FileCacheRepository.cs`
- [Filesystem cache entry](https://github.com/msmsrep/parallelscope/blob/main/Data/FileSystemEntryEntity.cs): EF entity · `Data/FileSystemEntryEntity.cs`
- [SQLite cache database](https://github.com/msmsrep/parallelscope/blob/main/Data/ParallelScopeDbContext.cs): EF Core context · Schema changes are maintained in Migrations/. · `Data/ParallelScopeDbContext.cs`

### Windows and Store

- [Filesystem path boundary](https://github.com/msmsrep/parallelscope/blob/main/Utilities/AppDataPathProvider.cs): path utilities · Resolves local state and normalizes or validates filesystem paths. · `Utilities/AppDataPathProvider.cs`
- [Windows shell integration](https://github.com/msmsrep/parallelscope/blob/main/Utilities/WindowsShellIconProvider.cs): shell icon provider · Supplies shell icons while Windows opens files by default association. · `Utilities/WindowsShellIconProvider.cs`
- [Store license gate](https://github.com/msmsrep/parallelscope/blob/main/Services/StoreLicenseService.cs): license service · Controls Plus-only display-column customization. · `Services/StoreLicenseService.cs`
- [Package manifest](https://github.com/msmsrep/parallelscope/blob/main/AppxManifest.xml): deployment metadata · `AppxManifest.xml`

## Connections

- Application startup → Browser shell: opens
- Application startup → Package manifest: packaged by
- Browser shell → Main window view model: binds to
- Settings window → Settings repository: loads and saves
- Settings window → Store license gate: checks Plus feature
- Main window view model → Navigation and history: composes
- Main window view model → File-list state: composes
- Main window view model → All Files view: composes
- Main window view model → Scan orchestration: orchestrates
- Main window view model → Incremental search: orchestrates
- Main window view model → Cache coordination: coordinates
- Navigation and history → File-list state: selects location
- Incremental search → Cache coordination: queries first
- Incremental search → Scan orchestration: falls back on no matches
- Cache coordination → File cache repository: reads and writes
- Scan orchestration → Filesystem path boundary: enumerates validated paths
- Scan orchestration → File cache repository: caches metadata
- File cache repository → Filesystem cache entry: maps
- File cache repository → SQLite cache database: persists through
- SQLite cache database → Filesystem path boundary: uses local data path
- Settings repository → Application settings: serializes
- Settings repository → Filesystem path boundary: uses local data path
- File-list state → File and folder items: presents
- All Files view → File and folder items: presents
- File and folder items → Windows shell integration: gets icons