Archivst - Manual

BackupSet JSON Configuration

Archivst Desktop stores backup configuration under your user profile. This JSON is used to persist folder selections, restore state, and schedule metadata.

File locations

Default: %APPDATA%\ArchivstDesktop\defaultset.json
Debug: %APPDATA%\ArchivstDesktop\debug.defaultset.json
Backup copy: defaultset.json.backup (periodic recovery copy)

Core structure

{
  "ScheduleEnabled": true,
  "TotalFiles": 15234,
  "TotalBytes": 52428800,
  "LastBackup": "2024-01-15T14:30:00Z",
  "Folders": [
    {
      "Name": "Documents",
      "Path": "C:\\Users\\YourName\\Documents",
      "IsCloud": true,
      "IsEncrypted": true,
      "FilesConditions": {
        "Wildcard": {
          "Exclude": ["*.tmp", "*.log"]
        }
      }
    }
  ],
  "Hydration": {
    "Documents/photo.jpg": "Hydrated"
  }
}

Warning: close Archivst Desktop before editing JSON manually and validate syntax before restart.

File deduplication

Deduplication compares content hashes to avoid uploading duplicate data unnecessarily.

Hash index: %APPDATA%\ArchivstDesktop\fileDetail\[FOLDER_ID]\hash_index.txt
Mode Copy: keep duplicate files as separate stored copies.
Mode Ignore: skip files with identical content already stored.
Safety threshold: move-heavy scans can be stopped to prevent accidental mass change handling.

Settings file and DateTime metadata

Application-level settings are stored separately from BackupSet JSON.

User settings: %APPDATA%\ArchivstDesktop\appsettings.json
Important fields: thread counts, upload throttling, environment domains, dark mode, schedule polling.
Date handling: timestamps are stored in UTC and presented in local time in UI.

Version metadata tracks DateStored, LastModified, and destination-specific identifiers used by point-in-time restore.

Image compression and sizing options

Image processing can reduce storage and transfer costs for photo-heavy folders.

AutoCompressImages: enables per-folder compression.
AutoCompressQuality: 0-100 quality scale (typical 80-90).
AutoCompressMaxRes: maximum output resolution; preserves aspect ratio.
AutoCompressIgnoreSize: skip small files already near optimal size.
FallbackCompressionFailure: upload original file if conversion fails.

For quality-sensitive workflows, enable verification settings and test with a small sample set before broad rollout.

BackupSet JSON — full schema

The backup set file is a single JSON document that stores everything the app knows about your selected folders: aggregate counts, schedule state, per-folder configuration, and hydration state. A fully populated document, including FoldersConditions, FilesConditions and a per-folder Schedule, looks like this:

File locations

Default: %APPDATA%\ArchivstDesktop\defaultset.json
Debug builds: %APPDATA%\ArchivstDesktop\debug.defaultset.json
Temporary: defaultset.json.temp (written during a save)
Backup copy: defaultset.json.backup (created automatically when the last backup is more than a week old)
Cloud sync: uploaded to Azure Blob Storage (Archive tier) for recovery

Full example

{
  "ScheduleEnabled": true,
  "TotalFiles": 15234,
  "TotalBytes": 52428800,
  "TotalFilesOnline": 12000,
  "TotalBytesOnline": 40960000,
  "LastBackup": "2024-01-15T14:30:00Z",
  "Folders": [
    {
      "Name": "Documents",
      "Path": "C:\\Users\\YourName\\Documents",
      "Created": "2024-01-01T10:00:00Z",
      "IsCloud": true,
      "IsLocal": false,
      "IsFtp": false,
      "IsEncrypted": true,
      "LocalDestination": "",
      "FtpDomain": "",
      "FtpPath": "",
      "FtpUser": "",
      "TotalFiles": 5000,
      "TotalFolders": 250,
      "TotalBytes": 10485760,
      "TotalAlteredBytes": 5242880,
      "FilesHydrated": 100,
      "FilesHydrating": 0,
      "AutoSelectFiles": true,
      "AutoSelectDaysAge": 3,
      "AutoCompressImages": true,
      "AutoCompressFormat": 1,
      "AutoCompressQuality": 85,
      "AutoCompressIgnoreSize": 0.5,
      "AutoCompressMaxRes": 2048,
      "AutoCompressVerify": false,
      "AutoCompressMinPsnr": 25.0,
      "AutoCompressMinSimilarity": 0.90,
      "FallbackCompressionFailure": true,
      "OnlyRaw": false,
      "DuplicateFileHandling": "Ignore",
      "UseWildcard": true,
      "UseWildcardVideo": false,
      "UseAlwaysWildcard": false,
      "Wildcards": ["*.tmp", "*.log", "/Temp/**"],
      "WildcardsAlways": [],
      "FoldersConditions": {
        "Wildcard": { "Include": [], "Exclude": [] },
        "Regex": { "Include": [], "Exclude": [] },
        "Exact": { "Include": [], "Exclude": [] }
      },
      "FilesConditions": {
        "Wildcard": { "Include": [], "Exclude": ["*.tmp"] },
        "Regex": { "Include": [], "Exclude": [] },
        "Exact": { "Include": [], "Exclude": ["C:\\Users\\YourName\\Documents\\temp.txt"] }
      },
      "Schedule": {
        "Type": "Daily",
        "Hour": 14,
        "Minute": 30
      },
      "RestoreState": "Archived",
      "SubFolders": [],
      "Files": []
    }
  ],
  "Hydration": {
    "Documents/photo.jpg": "Hydrated",
    "Documents/archive.zip": "Archived",
    "Documents/video.mp4": "Hydrating"
  }
}

Root-level properties

Property	Type	Description
`ScheduleEnabled`	bool	Master switch for all scheduled backups across all folders
`TotalFiles`	long	Aggregate count of all files across all folders
`TotalBytes`	long	Aggregate size in bytes of all files
`TotalFilesOnline`	long	Count of files in Hydrated state (ready to download)
`TotalBytesOnline`	long	Size in bytes of hydrated files
`LastBackup`	DateTime	UTC timestamp of last successful backup (ISO 8601)
`Folders`	Array	List of folder configurations, one entry per top-level folder
`Hydration`	Dictionary	Maps file path to restoration state: Archived, Hydrating or Hydrated

Folder-level properties

Property	Type	Description
`Name`	string	Display name of the folder
`Path`	string	Full local path to the source folder
`Created`	DateTime	When this folder was added to the backup set
`IsCloud`	bool	Back up to Azure Blob Storage
`IsLocal`	bool	Back up to a local/network path (paired with `LocalDestination`)
`IsFtp`	bool	Back up to an FTP server (paired with `FtpDomain`/`FtpPath`/`FtpUser`)
`IsEncrypted`	bool	Encrypt files before storing them at the destination
`DuplicateFileHandling`	enum	Copy (always back up) or Ignore (skip duplicates)
`AutoSelectFiles`	bool	Automatically select files based on age
`AutoSelectDaysAge`	int	Only back up files modified within this many days
`AutoCompressImages`	bool	Enable image compression/resizing before backup (see the image compression reference below)
`AutoCompressQuality`	int	JPEG quality 0-100 (higher = better quality, larger size)
`AutoCompressMaxRes`	int	Maximum resolution in pixels (longest edge); 0 = no resize
`SubFolders`	Array	Nested folder entries (same structure, recursive)
`Files`	Array	Explicitly tracked files in this folder

Saving behaviour

Atomic saves: the updated JSON is written to a .temp file first, then renamed over the .json file, so a crash mid-save cannot corrupt the set.
File locking: saves are thread-safe with retry logic (5-second timeout) so the app and the background service never write at the same time.
Minified save: the SubFolders and Files arrays are cleared before saving to keep the file small; they are rebuilt on the next scan.
Weekly backup copy: when LastBackup is more than 7 days old, a copy is written to defaultset.json.backup.
Cloud sync: the set can be synced to Azure Blob Storage (Archive tier) so it can be recovered on another machine.

Recovery order

On start the app loads the backup set in this order:

Primary load from defaultset.json
Fallback to defaultset.json.backup
Download the cloud copy if both local files are missing or unreadable
Create a fresh empty backup set if all recovery fails

Image compression reference

Image processing is configured per folder. These are the available properties:

AutoCompressImages — compress images before upload/copy.
AutoCompressFormat — output format (e.g., 1 = JPEG/PNG as configured in the app).
AutoCompressQuality — compression quality/level (0–100). Higher = better quality, larger size.
AutoCompressIgnoreSize — skip compression for small images under this size (MB).
AutoCompressMaxRes — resize down to this max resolution (longest edge in pixels). 0 = no resize.
FallbackCompressionFailure — if compression fails, fall back to uploading the original file.
OnlyRaw — for photography workflows, only process RAW images when set.

Quality verification can additionally be tuned with AutoCompressVerify, AutoCompressMinPsnr and AutoCompressMinSimilarity; failed conversions are flagged so you can review them in the Failed Conversions dialog (see the desktop manual).

Examples

# Exclude a temp folder and video files
UseWildcard = true
Wildcards = [ "/Temp/**", "**/*.mp4", "**/*.mkv" ]

# Auto-select 7-day recent files and compress large images
AutoSelectFiles = true
AutoSelectDaysAge = 7
AutoCompressImages = true
AutoCompressQuality = 80
AutoCompressIgnoreSize = 0.5   # MB
AutoCompressMaxRes = 3840      # 4K
FallbackCompressionFailure = true

Deduplication deep dive

Content-based deduplication detects and optionally skips files with identical content, reducing storage costs and transfer time. Here is exactly how it works.

Hash calculation

Algorithm: SHA-256 over the full file content (fast enough for dedup; not a security hash).
Timing: calculated while the file is read, just before upload.
Storage: hex string in the ContentHash property of the file's detail JSON.
Example: 5D41402ABC4B2A76B9719D911017C5921F0E3D4A5B6C7D8E9F0A1B2C3D4E5F60

Hash index file

Each folder keeps a plain-text index of every stored hash, one entry per line in hash|relative path format:

Location: %APPDATA%\ArchivstDesktop\fileDetail\{folder id}\hash_index.txt

5D41402ABC4B2A76B9719D911017C5921F0E3D4A5B6C7D8E9F0A1B2C3D4E5F60|Documents\file1.txt
0F1E2D3C4B5A69788796A5B4C3D2E1F00A1B2C3D4E5F60718293A4B5C6D7E8F9|Photos\image.jpg

Index building

Trigger: start of each backup run.
Source: the folder's existing file-detail JSON files.
Performance: around 10–30 seconds for 100k+ files.
In-memory: the index is searched with streaming reads, not loaded into memory.

Duplicate detection workflow

Calculate the hash of the file to back up.
Search hash_index.txt for a matching hash.
If found and DuplicateFileHandling = Ignore: mark the file as a duplicate (IsDuplicate = true, DuplicateOfPath = the path from the index), skip the upload, and log it as “Skipped (Duplicate)”.
If not found, or DuplicateFileHandling = Copy: proceed with the upload, then add the hash entry to the index after a successful upload.

Move detection

Archivst detects when files are moved (not copied) within a folder so moves update metadata instead of re-uploading:

Detection logic: a file is missing at its old path and appears at a new path with the same hash.
Pre-scan phase: before copying, the previous backup's file list is compared to the current scan.
Safety threshold: if more than 75% of files appear moved, the backup is aborted (configurable via AbortIfMovedPercent; 0 disables it).
Action: when a move is confirmed, the stored metadata paths are updated instead of re-uploading the data.
Verbose logging: enable with BackupSettings.PreScanVerbose = true.

Configuration

Setting	Location	Default	Description
`DuplicateFileHandling`	FolderModel	Copy	Per-folder: Copy or Ignore
`AbortIfMovedPercent`	BackupSettings	75	Abort if >X% of files appear moved (0 = disable)
`PreScanVerbose`	BackupSettings	false	Enable detailed move-detection logging

File metadata storage

Every source file gets its own metadata JSON under the folder's detail directory (the folder id from the next section fills in {folder id}):

Pattern: %APPDATA%\ArchivstDesktop\fileDetail\{folder id}\{relative path}.json
Example: %APPDATA%\ArchivstDesktop\fileDetail\3f2a9c4e-7b1d-4e5a-9c6b-2d8e4f1a0b3c\Documents\photo.jpg.json

Example (FileDetailsModel)

{
  "Name": "photo.jpg",
  "DestinationName": "photo.webp",
  "Parent": "C:\\Users\\YourName\\Documents",
  "RelativePathAndFileName": "Documents\\photo.jpg",
  "OriginalSize": 5242880,
  "DestinationSize": 1048576,
  "LastModified": "2024-01-15T10:30:00Z",
  "Created": "2024-01-01T08:00:00Z",
  "ContentHash": "A8B3F2C1D5E6F709B4C5D6A7E8F90123456789ABCDEF0123456789ABCDEF01",
  "IsDuplicate": false,
  "DuplicateOfPath": null,
  "ConversionFailedUploadedOriginal": false,
  "Outcome": "Success",
  "Reason": "",
  "RestoreState": "Archived",
  "Versions": [
    {
      "DateStored": "2024-01-15T14:30:00Z",
      "LastModified": "2024-01-15T10:30:00Z",
      "Location": "https://account.blob.core.windows.net",
      "AccountHost": "https://account.blob.core.windows.net",
      "Container": "user-backup",
      "BlobName": "Documents/photo.jpg",
      "VersionId": "2024-01-15T14:30:00.0000000Z",
      "AccessTier": "Archive"
    }
  ]
}

Key properties

Property	Type	Description
`ContentHash`	string	SHA-256 hash (hex) used for deduplication and move detection
`OriginalSize`	long	Source file size in bytes
`DestinationSize`	long	Size after compression (if enabled)
`LastModified`	DateTime	Source file's last write time (UTC, ISO 8601)
`Created`	DateTime	Source file's creation time
`IsDuplicate`	bool	True if the file has identical content to another stored file
`DuplicateOfPath`	string	Path of the original file, when this file is a duplicate
`Outcome`	enum	Last backup result: Success, Skipped, FailureFile and other failure states
`Versions[]`	Array	Version history (one entry per backup of this file)

Version metadata

Each Versions entry tracks a single backup operation:

DateStored: UTC timestamp when the version was uploaded.
LastModified: source file modification time for this version.
VersionId: Azure Blob version identifier (immutable).
AccountHost: storage endpoint URL.
Container: blob container or folder name.
BlobName: relative path within the container.
AccessTier: Hot, Cool, or Archive (Azure storage tier).

Point-in-time restore

The versions array enables restoring any previous backup:

The UI shows the version list with DateStored timestamps.
You select a target version (or datetime).
The restore downloads that specific VersionId from Azure.
The file is restored with its original LastModified timestamp.

Settings file (appsettings.json) reference

Location

User settings: %APPDATA%\ArchivstDesktop\appsettings.json
CLI mode: a local appsettings.json next to the executable is preferred when present; otherwise the user settings are used.
Priority: user settings override the application's built-in defaults.

Structure

{
  "backupsettings": {
    "CopyThreads": 8,
    "CopyCalmThreads": 2,
    "RestoreThreads": 2,
    "RestoreExistingFiles": false,
    "VideoRegex": "^.*\\.(webm|mkv|flv|vob|ogv|mp4|m4v|avi|wmv|mov)$",
    "RawRegex": "^.*\\.(3fr|arw|cr2|cr3|dng|nef|orf|raf|rw2)$",
    "FtpSslSessionLengthMinutes": 5,
    "FtpTimeout": 0,
    "FtpAlwaysCheckRemoteFileExists": true,
    "AbortIfMovedPercent": 75,
    "PreScanVerbose": false
  },
  "cloudsettings": {
    "CopyThreads": 2,
    "LimitUploadKbps": 0,
    "RestoreThreads": 2,
    "RestoreExistingFiles": false
  },
  "appsettings": {
    "Env": "live",
    "WebDomain": "https://www.archivst.com",
    "FunctionDomain": "https://apis.archivst.com/",
    "UpdateStorageContainer": "https://archivst.blob.core.windows.net/archivst-desktop/",
    "AutoUpdate": true,
    "DarkMode": true,
    "StartWithWindows": false,
    "ScheduleDisabledPollMinutes": 60,
    "DefaultBackupSetDirectory": null
  }
}

Settings reference

Section	Property	Default	Description
backupsettings	`CopyThreads`	8	Concurrent file transfers during backup
	`CopyCalmThreads`	2	Throttled threads during calm periods
	`RestoreThreads`	2	Concurrent downloads during restore
	`RestoreExistingFiles`	false	Overwrite existing files during restore
	`VideoRegex`	…	Regular expression identifying video files
	`RawRegex`	…	Regular expression identifying RAW photo formats
	`FtpSslSessionLengthMinutes`	5	FTP/FTPS control session length in minutes
	`FtpTimeout`	0	FTP operation timeout in seconds (0 = default)
	`FtpAlwaysCheckRemoteFileExists`	true	Re-verify remote file presence on unstable FTP links
`AbortIfMovedPercent`	75	Abort backup if >X% of files appear moved (safety)
`PreScanVerbose`	false	Enable detailed move-detection logging
cloudsettings	`CopyThreads`	2	Cloud-specific concurrent uploads
	`LimitUploadKbps`	0	Bandwidth limit in KB/s (0 = unlimited)
	`RestoreThreads`	2	Cloud-specific concurrent downloads
`RestoreExistingFiles`	false	Overwrite existing files during cloud restore
appsettings	`Env`	live	Target environment for API endpoints (e.g. staging or live)
	`WebDomain`	see sample	Site domain used for links and sign-in
	`FunctionDomain`	see sample	Base URL of the Azure Functions API
	`UpdateStorageContainer`	see sample	Container the desktop app checks for updates
	`AutoUpdate`	true	Automatically download and install updates
	`DarkMode`	null	Use the dark theme (null = system default)
	`StartWithWindows`	false	Launch the app on Windows startup
	`ScheduleDisabledPollMinutes`	60	How often to re-check for re-enabled schedules (minutes)
	`DefaultBackupSetDirectory`	null	Custom backup set storage location (null = default roaming profile location)

VideoRegex and RawRegex defaults are long extension lists in the shipped configuration; only override them if you know you need to.

DateTime handling

Format: ISO 8601 UTC (yyyy-MM-ddTHH:mm:ssZ).
Precision: second-level (fractional seconds are truncated).
Timezone: all timestamps are stored as UTC and displayed in local time in the UI.
Comparison: timestamps are compared as universal strings for consistent matching.
File matching: a file is treated as unchanged when OriginalSize and LastModified match exactly.

Folder ID and metadata directories

Each folder in a backup set is assigned a stable unique id when it is created, and that id namespaces its local metadata:

UniqueId: a GUID string generated once when the folder is added. It is never re-derived from the path, so renaming or rearranging folders in the backup set does not change ids or orphan existing metadata.
Metadata directory: file-detail JSONs and the hash index live under %APPDATA%\ArchivstDesktop\fileDetail\{UniqueId}\.
UniqueName: a derived, human-derivable name built from the alphanumeric rendering of the folder path plus the storage destination (appended for Local and FTP folders). It distinguishes the same source path backed up to different destinations.

Older documentation described the id as a SHA-256 hash of the path plus destination; that was never the runtime behaviour — the GUID UniqueId is the only identifier used in metadata paths.

Best practices

Backup the JSON files: before manually editing defaultset.json, copy it to a safe location.
Close the app first: always exit Archivst Desktop before editing configuration files.
Validate JSON: check your edits with a JSON validator before restarting the app.
Monitor logs: after configuration changes, check the Logs panel for errors.
Test incrementally: change one setting at a time, run a backup, and verify before moving on.
Document changes: keep notes on custom settings so you can troubleshoot later.

Archivst Desktop Technical Details

BackupSet JSON Configuration

File locations

Core structure

File deduplication

Settings file and DateTime metadata

Image compression and sizing options

BackupSet JSON — full schema

File locations

Full example

Root-level properties

Folder-level properties

Saving behaviour

Recovery order

Image compression reference

Examples

Deduplication deep dive

Hash calculation

Hash index file

Index building

Duplicate detection workflow

Move detection

Configuration

File metadata storage

Example (FileDetailsModel)

Key properties

Version metadata

Point-in-time restore

Settings file (appsettings.json) reference

Location

Structure

Settings reference

DateTime handling

Folder ID and metadata directories

Best practices