Space Wizard: Architecture & Technical Reference

Space Wizard is a cross-platform desktop application (Electron main process plus an Angular renderer) for measuring disk usage and removing duplicate files. It has no server component and no account system, and scanning makes no network calls whatsoever.

Version 1.0 adds remote sources: any host reachable over SFTP, FTPS or plain FTP can be scanned, browsed, deduplicated and cleaned with the same interface used for a local drive. Duplicate hashing on a remote host executes on that host, so file contents are not transferred for comparison.

This reference describes the implemented behaviour so a reviewer can evaluate the product against what it does rather than against marketing language.

The main process owns all filesystem and network access and exposes a single typed IPC command channel to the renderer; long-running scans stream results back over an asynchronous push channel rather than blocking a request. Scan results are accumulated and rendered in the UI, not persisted — there is no index, database or cache of your filesystem anywhere on disk.

The interface is a single window with a source picker (local drives and saved remote hosts) and three tabs over the selected source: Files, Duplicates and Usage. There is no dual-pane browser and no archive handling; the scope is deliberately narrower than a general file manager.

A local scan is a concurrent breadth-first directory walk implemented in Node.js, reading up to 64 directories at a time. Each directory reports its direct size — the total of the files sitting immediately inside it — and the renderer accumulates subtree totals as results arrive, so the running total climbs while the walk is still in progress. Results are emitted in batches because a full system-drive walk visits on the order of half a million directories and one message each would swamp the renderer.

Two correctness details are worth calling out, because they are the difference between a plausible number and a correct one. First, directories are never de-duplicated by file ID: Windows file identifiers exceed the range JavaScript numbers represent exactly, and keying on them silently drops roughly one directory in twenty. Second, files that the kernel refuses to open — pagefile.sys is the canonical example, which fails with EBUSY — are sized by reading the directory entry through PowerShell instead, recovering around 15 GB on a typical Windows system drive that other scanners lose.

Reparse points are handled explicitly: a symlink or junction resolving inside the scan root is skipped, because its bytes are already counted at their real location; one resolving outside is followed at most once and remembered, so a second link to the same target cannot double-count it. File symlinks are counted at the size of the link, not the target. Depth is capped at 512 as a backstop against pathological link graphs.

Directories that cannot be read are counted and surfaced in the UI with the count and a one-click relaunch as Administrator, rather than being silently omitted from the total. Three scan options are user-controlled: follow symlinks, stay on one filesystem, and include cloud-sync folders.

OneDrive, Dropbox, iCloud Drive, Google Drive, Box, pCloud and MEGA folders are excluded from scans by default. This is not only a noise-reduction measure: these providers use placeholder files whose apparent size does not reflect local disk usage, and walking them can cause the provider to hydrate — that is, actually download — the real files. The exclusion is a toggle, not a hard restriction.

A connection specifies host, port, username and one of three authentication methods — password, private key file with optional passphrase, or a running SSH agent — plus a transport: SFTP, FTPS, plain FTP, or automatic. Automatic dials each transport the supplied credentials permit and keeps the first that answers; private keys and agent authentication are SSH-only, so those cases only ever attempt SFTP. Port 990 is treated as implicit FTPS.

Each session records which transport it actually negotiated and whether that transport is encrypted. Plain FTP sessions are badged as unencrypted in the UI. Accepting an untrusted TLS certificate on FTPS is a separate explicit opt-in, described in the UI as leaving the connection encrypted but unverified.

A session also records whether the account has a usable shell, which determines the scan strategy, and its connection budget: the number of parallel connections a scan may hold open against that host, configurable from 1 to 16 with a default of 5, and reduced automatically if the host caps it lower.

Where the account has a shell and GNU findutils, a scan runs a single `find` invocation that prints a type letter, apparent size and path for every entry, streamed back over one channel. Unreadable directories are tagged by the same command so the UI can report how much of the tree stayed hidden. `-xdev` is applied when the single-filesystem option is on, and cloud-folder pruning is expressed as a `find` prune expression rather than filtered client-side.

Where there is no shell — a locked-down SFTP account, or an FTP server — the scan falls back to a concurrent breadth-first walk performing one directory read per round trip, parallelised across the session's connection budget. This is slower but works against any compliant SFTP or FTP server.

Remote mounts are enumerated with `df -Pk`, filtered to exclude pseudo filesystems (tmpfs, devtmpfs, proc, sysfs, squashfs, overlay and similar) and snap mounts, with the account's home directory listed first. Where no shell is available, the home directory is presented as the single available root.

Duplicate detection is a three-pass pipeline designed to avoid reading bytes it does not have to. The practical consequence: a 4 GB video that differs from another in its opening kilobytes costs 4 KB of I/O rather than 4 GB. Candidates are processed largest-size-first so the findings that matter most appear first, and hashing runs eight files concurrently.

• Pass 1 — group candidate files by exact byte size; any file with a unique size cannot have a duplicate and is dropped without being read
• Pass 2 — hash the first 4,096 bytes of each remaining candidate with SHA-1, eliminating files that merely share a size
• Pass 3 — compute a full SHA-1 only over what survived pass 2, confirming byte-for-byte identity

On a remote source the same pipeline runs, but the hash functions are injected: the prefix pass executes `dd if=<path> bs=4096 count=1 | sha1sum` and the full pass executes `sha1sum`, both on the remote host, returning one line of hash per file. Only where the account has no shell at all does the client read bytes over the connection — and even then the prefix pass transfers 4 KB per candidate, not the whole file. Remote duplicate detection therefore costs kilobytes of terminal output rather than a full download of every candidate.

SHA-1 is used here as a content fingerprint over files the user already holds on their own storage, in a pipeline where a match is confirmed by a full-file digest and then reviewed by a human before anything is deleted. It is not used as a signature or authentication mechanism. Where an adversarially-constructed collision is part of the threat model, DuplicateDuster's SHA-256 pipeline is the appropriate tool.

Local deletions — a single file or a bulk duplicate clear — are routed through the operating system's trash or recycle bin API, not a raw unlink, and are recoverable through the normal OS mechanism until the user empties it.

Remote filesystems have no equivalent, so a remote deletion is a direct removal and is permanent. The UI reflects the difference: the action reads "Move to trash" on a local source and "Delete" on a remote one.

In the duplicates view, marking every copy in a group is blocked and flagged. There is no path through that view that removes the last remaining copy of a file.

SSH host keys are verified during key exchange, before authentication: the presented key is fingerprinted as SHA-256 in OpenSSH's printed format and compared against the fingerprint previously accepted for that host and port. An unknown host is presented to the user with the fingerprint and the command to verify it server-side, defaulting to Cancel. A host presenting a different key than the one previously accepted causes the connection to be refused outright; recovering from that requires explicitly clearing the stored fingerprint for that connection. Because the check happens before authentication, a host that fails it never receives a credential.

Saved passwords and passphrases are held in the platform keyring via Electron's safeStorage, encrypted to the machine and user account. When the keyring is unavailable, the application reports that and refuses to persist secrets rather than falling back to plain-text storage; the connection is saved without credentials.

Two gates are enforced in the main process, not the UI. Scan scope: on the free tier, `getDrives` marks every drive that does not contain the user's home directory as locked, and a scan whose root is outside the home directory is refused before it starts. Scan size: a free-tier scan halts once 100 GB has been measured and emits an explicit limit notice with the figures. Both gates are evaluated against the licence state resolved once per scan, and neither applies to remote sources.

Activation posts the licence key and a machine fingerprint — a SHA-256 over hostname, platform, CPU model and total memory — to the licensing service, which validates it and consumes a seat. Revalidation at startup is a check-only call, so a device deactivated in the licensing dashboard drops to the free tier while an unreachable server changes nothing: a licence is revoked only on a definitive negative verdict, never on a network failure. Air-gapped machines can activate from a cryptographically signed licence file bound to that device fingerprint, verified locally with no network involved.

The application checks a static release feed once, twenty seconds after launch, and never again on its own; a manual check is available in Settings. Downloads never start automatically, and a running scan is never interrupted by an update prompt. Where the packaging format permits in-place replacement — Windows NSIS installers, signed macOS builds, Linux AppImages — updates install themselves; where it does not (unsigned macOS builds, distribution-managed .deb packages), the dialog offers the download page instead.

A release can declare itself required, in which case the usual dismissal routes are removed. Even then there is a documented override behind a second screen that explains the risk, recorded against that specific version, because a block with no way past it is a block people work around by downgrading.

No file content, path, name or scan result is transmitted anywhere. There is no telemetry, no analytics and no crash reporting. Scanning a local drive touches no network interface at all; scanning a remote host communicates only with that host, using the credentials you supplied.

The application makes exactly two categories of outbound request in its lifetime, both to Royal Softworks infrastructure and both optional: licence activation or revalidation, and the update check. A machine with no network connection can run the application, activate Pro from a licence file, and scan indefinitely.

Windows, macOS (Intel and Apple silicon) and Linux builds are produced from one codebase. The 1.0 beta is not code-signed on any platform, so SmartScreen and Gatekeeper will warn on first launch and macOS in-place updates remain manual until signing is in place.

Stated explicitly so nobody has to discover it during an evaluation: there is no comparison between historical scans, no continuous filesystem monitor, no scheduled or unattended scanning, no fleet management console and no server-side audit log. Scans are on-demand and results live only in the running application.