Skip to main content

Overview

r2Vault is a ~4,700 line Swift codebase organized into a clean, modular structure following MVVM principles.

Application Entry Point

FiaxeApp.swift

The main app structure that:
  • Creates the single AppViewModel instance
  • Initializes the menu bar manager
  • Configures the main window and settings
  • Sets up app-level commands (About, Check for Updates)
FiaxeApp.swift
Menu bar-only app: The AppDelegate prevents the app from quitting when the window closes, and LSUIElement = YES in Info.plist keeps it out of the Dock.

ContentView.swift

The root view that provides:
  • Sidebar navigation (Buckets, History, Settings)
  • Main content area with detail views
  • Upload HUD overlay
  • File importer sheets
  • Error alerts

Models Layer

R2Credentials.swift

Encapsulates all information needed to connect to an R2 bucket:
Models/R2Credentials.swift
Supports both R2’s default domain and custom domains for public URLs.

R2Object.swift

Represents a file or folder in R2:
Models/R2Object.swift

UploadTask.swift

Tracks the state of a single file upload:
Models/UploadTask.swift
Security-scoped bookmarks: macOS sandboxing requires storing bookmarks to access files selected via the file picker or dropped from Finder.

UploadItem.swift

Persisted history record of completed uploads:
Models/UploadItem.swift

Services Layer

AWSV4Signer.swift

Implements AWS Signature Version 4 for S3-compatible APIs:
Services/AWSV4Signer.swift

CryptoKit

Uses HMAC<SHA256> for signing

Nonisolated

Can be called from any actor

R2UploadService.swift

Handles file uploads to R2:
Services/R2UploadService.swift

R2BrowseService.swift

Provides S3 ListObjectsV2, create folder, and delete operations:
Services/R2BrowseService.swift
Includes custom XML parsers (ListBucketResultParser, FlatListParser) for S3 API responses.
Manages the menu bar icon and popover:
Services/MenuBarManager.swift

ThumbnailCache.swift

Actor-based caching layer for image/video thumbnails:
Services/ThumbnailCache.swift
Uses AVAssetImageGenerator for video thumbnails and NSImage resizing for images.

KeychainService.swift

Persists credentials to UserDefaults:
Services/KeychainService.swift
Security note: For a personal single-user tool, credentials are stored in UserDefaults. For multi-user or enterprise apps, use the actual macOS Keychain.

UploadHistoryStore.swift

Persists upload history:
Services/UploadHistoryStore.swift

UpdateService.swift & AppUpdater.swift

Check GitHub releases for app updates:

ViewModels Layer

AppViewModel.swift

The single, central view model (~700 lines) that:
  • Manages credentials (load, save, select, delete)
  • Controls browser navigation (folders, back/forward, breadcrumbs)
  • Handles file uploads (queue, progress, completion)
  • Coordinates deletions (single, batch, recursive)
  • Manages upload history
  • Tracks UI state (alerts, sheets, loading states)

688 lines

The largest file in the project

@Observable

Automatic change tracking

MainActor

All properties safe for UI

Single instance

Created once at app launch
Key responsibilities:

Views Layer

All SwiftUI views are lightweight, focusing on presentation:

BrowserView.swift

Main file/folder browser with:
  • Toolbar (view mode, sort, filter, new folder, upload)
  • Object grid/list
  • Drag-and-drop handling
  • Context menus
  • Quick Look preview
Breadcrumb navigation for current folder path

R2ObjectRow.swift

Single row in the browser (thumbnail, name, size, date)

UploadQueueView.swift

List of pending/active uploads with progress bars

UploadHUDView.swift

Floating HUD showing active upload count

UploadHistoryView.swift

Persistent history of completed uploads

SettingsView.swift

Credential management and app preferences Quick upload interface in the menu bar popover

Module Boundaries

Views read models directly for rendering but call view model methods for mutations.

Next Steps

Architecture

Learn about MVVM, concurrency, and state management

Tech Stack

Explore the frameworks and tools used