English · Deutsch · Español · User Guide
Intelligent local backup synchronization with automated SQLite WAL database protection.
Note
Disambiguation: file-bricks/ProSync is an open-source Windows desktop and background application built with Python (PySide6) for local file/folder synchronization with automated SQLite WAL database protection. It is completely independent of enterprise database replication products (e.g., Tibero ProSync) or third-party macOS utilities.
Machine-readable index: Specification available at llms.txt. Last checked: 2026-09-18.
- Features & Core Capabilities
- System Architecture & Data Flow
- Target Personas & Discoverability
- Comparative Matrix vs. Alternatives
- Dual Mermaid Diagrams
- Governance & Runtime Invariants
- Synchronization Modes & Semantics
- SQLite WAL Database Protection
- Visual Showcase & Feature Gallery
- Installation & Dependencies
- CLI & Headless Automation
- Scheduled Backups & IANA Timezones
- Portable Web/PWA Companion
- ProSyncReader & ProFiler Search
- Windows Store & MSIX Staging
- Testing & Quality Checks
- Third-Party Licenses & Transparency
- Security Policy & Sibling Ecosystem
- Folder Synchronization: Flexible one-way, two-way, update, mirror, and index-only synchronization.
- File Synchronization: Dedicated single-file backup connections for mission-critical assets.
- Automatic Database Detection: Proactively identifies SQLite (
.db,.sqlite,.sqlite3,.db3) and MS Access databases. - WAL Checkpoint Guard: Safely executes
PRAGMA wal_checkpoint(TRUNCATE)before copying active SQLite databases, aborting fail-closed on lock contention (SQLITE_BUSY) to prevent corruption. - System Tray Integration: Runs unobtrusively in the background on Windows with auto-start and tray menu controls.
- Scheduled Backups & Daily Triggers: Configurable interval timers or explicit IANA-timezone-aware daily local execution across DST transitions.
- Batch Sync Queue: Select and launch multiple connections sequentially in one coordinated batch with granular progress feedback.
- Atomic File Operations: Staged temporary writes (
.tmp) prior to atomic replacement, preventing partial or corrupted targets during power loss. - Database Indexing & ProFiler Companion: Optional full-text indexing and instant search via the companion reader.
- Portable Web/PWA Companion: Exports redacted
prosync-profile-v1.jsonfor offline mobile and browser inspection. - Cross-Platform Ready: Standardized 8-point platform smoke suites for Linux and macOS.
- Windows Store Staged: Complete MSIX packaging, AppxManifest declarations, and tile asset sets (Policy 10.1.3 compliant).
ProSync separates user interaction, synchronization scheduling, database integrity validation, and storage targets into modular decoupled layers:
+---------------------------------------------------------------------------------+
| USER INTERFACE |
| +------------------------------------+ +--------------------------------+ |
| | PySide6 Desktop GUI (Main Window) | | System Tray Background Monitor | |
| +------------------------------------+ +--------------------------------+ |
| +------------------------------------+ +--------------------------------+ |
| | Headless CLI (--run / --all) | | ProSyncReader Search Companion | |
| +------------------------------------+ +--------------------------------+ |
+---------------------------------------------------------------------------------+
|
v
+---------------------------------------------------------------------------------+
| SCHEDULER & BATCH ENGINE |
| ├── IANA Timezone Evaluator (DST Safe) ├── Batch Sync Execution Queue |
| └── Configuration Manager └── Instance Lock Coordinator |
+---------------------------------------------------------------------------------+
|
v
+---------------------------------------------------------------------------------+
| SYNC & INTEGRITY ENGINE (CORE) |
| ├── SQLite WAL Checkpoint Guard (PRAGMA wal_checkpoint(TRUNCATE)) |
| ├── Lock Contention Sentinel (SQLITE_BUSY Fail-Closed Abort) |
| ├── Atomic Staging & Temporary File Copier (.tmp Safe Replace) |
| └── Mode Logic: mirror | update | two_way | one_way | index_only |
+---------------------------------------------------------------------------------+
|
v
+---------------------------------------------------------------------------------+
| STORAGE DESTINATIONS |
| ├── Local Drives (NTFS, exFAT, APFS, Ext4) |
| ├── Network Attached Storage (NAS / SMB / CIFS UNC paths) |
| └── SFTP Remote Endpoints (Hardened Paramiko with Host Key TOFU) |
+---------------------------------------------------------------------------------+
-
[PERSONA-01] Desktop Power Users & Windows Sysadmins:
- Context: Automating regular backups of vital working directories, NAS shares, and external NVMe/USB drives.
- Pain Point: Generic sync utilities either lack background tray operation, lack resilient scheduling, or corrupt open SQLite databases during live copies.
- How ProSync Solves It: Unobtrusive system-tray automation, IANA-timezone-aware daily triggers, batch queues, and atomic folder synchronization with fail-closed safety.
-
[PERSONA-02] SQLite & Database Application Developers:
- Context: Development and production desktop environments utilizing SQLite in WAL (Write-Ahead Logging) mode.
- Pain Point: Standard copy tools copy active database files while WAL transactions are uncommitted, producing inconsistent, corrupt, or unusable backup copies.
- How ProSync Solves It: Automated pre-sync SQLite WAL checkpointing (
PRAGMA wal_checkpoint(TRUNCATE)), defensive lock contention detection (fail-closed onSQLITE_BUSY), and automated WAL auxiliary file exclusion (.db-wal,.db-shm).
-
[PERSONA-03] Privacy & Compliance Officers / DSGVO & Enterprise Auditors:
- Context: Regulated industries, legal/medical records, and sensitive local file archives requiring strict confidentiality.
- Pain Point: Cloud storage clients and commercial SaaS synchronization tools continuously exfiltrate telemetry, analytics, and metadata.
- How ProSync Solves It: Uncompromising 100% Local-First & Zero-Egress architecture; zero external telemetry sockets; fully unprivileged user-mode execution (
RunAsInvoker).
-
[PERSONA-04] Automation Engineers & Multi-Agent Framework Architects:
- Context: Headless script execution, CI validation pipelines, batch scripts, and LLM-assisted toolchains.
- Pain Point: Inflexible GUI-only tools that cannot be scripted without window managers or user clicks.
- How ProSync Solves It: Full-featured headless CLI (
--list,--run <id|name>,--all,--quiet), redacted portable profile export format (prosync-profile-v1.json), and comprehensive automated contract test suites.
- "python desktop backup synchronization tool"
- "pyside6 file sync folder backup windows tray"
- "sqlite wal database safe backup python"
- "local-first file synchronization zero egress"
- "offline two-way folder sync python"
- "sqlite wal checkpoint backup automation"
- "scheduled folder backup iana timezone python"
- "sftp atomic upload backup desktop app"
- "windows store msix backup sync utility"
- "open source backup sync tool mit license"
| Technical Dimension / Invariant | ProSync (file-bricks) |
FreeFileSync | Robocopy / Rsync | Syncthing | Commercial Cloud SaaS Sync |
|---|---|---|---|---|---|
| INV-LOCAL-01 Local-First & Zero Egress | 100% Local & Offline | 100% Local | 100% Local | P2P Network Protocol | Cloud Relay / Telemetry |
| INV-RUNAS-02 RunAsInvoker User Mode | Strictly Unprivileged | Native Installer | OS Built-in | User / Daemon | System Service / Elevation |
| INV-WAL-03 SQLite WAL Checkpoint Guard | Automated PRAGMA wal_checkpoint |
None (Raw Copy) | None (Raw Copy) | None (File Watcher) | None (Locked File Error) |
| INV-INTEG-04 Atomic Staging & Replacement | Staged .tmp Safe Replace |
Direct Stream | Direct Stream | Temp Staging | Chunk Upload Staging |
| INV-SCHED-05 DST-Aware IANA Scheduling | Built-in IANA Timezone Engine | Windows Task Scheduler | Task Scheduler / Cron | Continuous Watcher | Cloud Schedule / Poll |
| INV-PWA-06 Redacted Offline Companion | Export prosync-profile-v1.json |
None | None | Web GUI (Localhost) | Web Dashboard (Online) |
| INV-PLAT-07 Cross-Platform Smoke Parity | Windows, Linux & macOS Matrix | Windows, macOS, Linux | OS-specific | Go Cross-Platform | Platform-specific Apps |
| INV-STORE-08 Windows Store / MSIX Staging | AppxManifest & Policy 10.1.3 | Standalone Setup | None | Chocolatey / Scoop | Windows Store App |
| INV-DOCS-09 1:1 Bilingual Docs & LLM Index | 18-Point EN/DE + llms.txt |
English Docs | Man Pages / Docs | English Docs | Online Help Center |
| INV-SLA-10 Open Source Governance & SLA | MIT License, 48h Response SLA | GPL v3 | OS Proprietary / GPL | MPL 2.0 | Proprietary Commercial |
flowchart TD
subgraph Layer1 ["Layer 1: User Interface & Entry Points"]
UI_GUI["PySide6 Desktop Window<br/>(Main Workspace & Connection Tree)"]
UI_TRAY["Windows System Tray Launcher<br/>(Background Minimize & Status Indication)"]
UI_CLI["Headless CLI Engine<br/>(--run, --list, --all, --quiet)"]
end
subgraph Layer2 ["Layer 2: Scheduling & Execution Orchestration"]
SCHED["IANA Timezone Daily Scheduler<br/>(DST-Resilient Wall Time Evaluation)"]
QUEUE["Batch Execution Queue<br/>(Sequential Multi-Connection Dispatcher)"]
CONF["Configuration Store<br/>(ProSync_config.json with Runtime Lock)"]
end
subgraph Layer3 ["Layer 3: SQLite WAL Checkpoint & Integrity Engine"]
WAL_GUARD["SQLite WAL Checkpoint Guard<br/>(PRAGMA wal_checkpoint(TRUNCATE))"]
ATOMIC_COPY["Atomic File Transfer Engine<br/>(Staged .tmp Write with Safe Replacement)"]
LOCK_CHECK["Lock Contention Sentinel<br/>(Fail-Closed Abort on SQLITE_BUSY)"]
end
subgraph Layer4 ["Layer 4: Storage Destinations & Adapters"]
DEST_LOCAL["Local & Removable Disks<br/>(NTFS / exFAT / ReFS / Ext4 / APFS)"]
DEST_NAS["Network Shares & UNC Paths<br/>(SMB / CIFS / NFS Shares)"]
DEST_SFTP["Hardened SFTP Target<br/>(paramiko SSHv2 with Host Key TOFU)"]
end
subgraph Layer5 ["Layer 5: Offline Companion & Indexing"]
EXP_PWA["Profile Redactor & JSON Exporter<br/>(prosync-profile-v1.json Without Secrets)"]
APP_PWA["Offline PWA Web Companion<br/>(Static HTML5 / Web Worker / LocalStorage)"]
SEARCH_PRO["ProSyncReader & ProFiler Hub<br/>(FTS5 SQLite Indexing & Document Preview)"]
end
UI_GUI --> QUEUE
UI_TRAY --> SCHED
UI_CLI --> QUEUE
SCHED --> QUEUE
CONF -.-> QUEUE
QUEUE --> WAL_GUARD
WAL_GUARD --> ATOMIC_COPY
LOCK_CHECK -.->|"Guard Interrupt"| WAL_GUARD
ATOMIC_COPY --> DEST_LOCAL
ATOMIC_COPY --> DEST_NAS
ATOMIC_COPY --> DEST_SFTP
UI_GUI -.->|"Redacted Export"| EXP_PWA
EXP_PWA --> APP_PWA
DEST_LOCAL -.-> SEARCH_PRO
sequenceDiagram
autonumber
participant U as User / Scheduler / CLI
participant Q as Batch Queue Dispatcher
participant W as Sync Worker Engine
participant G as SQLite WAL Checkpoint Guard
participant D as Target Storage (Disk / NAS / SFTP)
participant E as Redacted Profile Exporter
U->>Q: Trigger Synchronization (Manual / Schedule / CLI)
Q->>W: Dispatch Active Connection Task
alt SQLite Database Connection (.sqlite, .db, .sqlite3)
W->>G: Execute PRAGMA wal_checkpoint(TRUNCATE)
alt Checkpoint Succeeded (status = 0)
G-->>W: Checkpoint Confirmed (WAL Flushed to Main DB)
W->>D: Stream Main Database File (Atomic .tmp Staging)
D-->>W: Atomic Rename & Transfer Complete
W-->>Q: Task Succeeded (Status: OK)
else Database Locked / Busy (SQLITE_BUSY)
G-->>W: Checkpoint Contention Detected
W-->>Q: Fail-Closed Abort (Prevent Corrupted Inconsistent Copy)
Q-->>U: Alert: Backup Skipped Due to Active Lock
end
else Standard File / Directory Connection
W->>D: Execute Sync Algorithm (mirror / update / two_way / one_way)
D-->>W: Transfer Summary (copied, updated, deleted, errors)
W-->>Q: Task Completed
end
opt Redacted PWA Profile Export
U->>E: Request Profile Export (prosync-profile-v1.json)
E-->>U: Generate Sanitized Profile (No Private Paths, No Secrets)
end
ProSync strictly enforces ten foundational governance and runtime invariants:
| Invariant | Title | Enforcement & Description |
|---|---|---|
INV-LOCAL-01 |
Local-First & Zero Egress | Pure local runtime. Zero network sockets opened to telemetry, tracking, or analytics endpoints. Verified in tests/test_security_license_contract.py. |
INV-RUNAS-02 |
Unprivileged RunAsInvoker | Runs purely in unprivileged user space. Never prompts for UAC elevation or root credentials. Documented in SECURITY.md and pyproject.toml. |
INV-WAL-03 |
SQLite WAL Crash Safety | Automated PRAGMA wal_checkpoint(TRUNCATE) prior to copying active SQLite databases; aborts fail-closed on lock contention (SQLITE_BUSY). |
INV-INTEG-04 |
Atomic File Copy Staging | File writes stage to .tmp files before atomic replacement, guaranteeing target files are never left in a corrupted state. |
INV-SCHED-05 |
DST-Aware Daily Scheduling | Built-in IANA timezone engine calculates exact wall time, eliminating drift and catch-up storms during daylight saving time shifts. |
INV-PWA-06 |
Redacted Companion Export | Exported prosync-profile-v1.json strips absolute file paths, private server endpoints, passwords, and tokens for safe offline companion viewing. |
INV-PLAT-07 |
Cross-Platform Smoke Parity | 8-point smoke test suites for Linux and macOS verify system opener commands, offscreen UI lifecycles, and POSIX path safety. |
INV-STORE-08 |
Windows Store & MSIX Staging | Verified Desktop Bridge AppxManifest (Geiger.ProSync), Policy 10.1.3 compliant search keywords, and full tile icon suites. |
INV-DOCS-09 |
1:1 Bilingual Documentation | Exact reciprocal quick navigation parity across English (README.md) and German (README_de.md), synchronized with llms.txt. |
INV-SLA-10 |
Open Source Governance & SLA | Permissive MIT License, public issue triage, and committed 48-hour response / 5-day triage security SLA in SECURITY.md. |
ProSync provides five deterministic synchronization modes to suit various backup and archival workflows:
| Mode | Semantic Behavior | Primary Use Case |
|---|---|---|
mirror |
Target is maintained as an exact replica of source (deleting orphaned target files) | Full system & repository backups |
update |
Transfers only newer and missing files from source to target (no target deletions) | Incremental day-to-day backups |
two_way |
Bidirectional synchronization resolving conflicts by newest timestamp | Active sync between laptop and workstation |
one_way |
Source files copied to target without ever deleting files from target | Safe non-destructive archival |
index_only |
Indexes metadata and file structure without moving payload bytes | Cataloging & ProFiler search preparation |
ProSync proactively detects active SQLite database files and enforces crash-consistent protection mechanisms:
- SQLite:
.sqlite,.sqlite3,.db,.db3 - MS Access:
.mdb,.accdb
- Automatic Exclusion in Folder Sync: When syncing folders containing live databases, WAL auxiliary files (
.db-wal,.db-shm,.db-journal) are automatically excluded from generic file copying to prevent inconsistent target states. - Dedicated File Connections: For live databases, users configure a dedicated File Connection with WAL Checkpoint enabled.
- Automated Checkpoint: Before copying, ProSync issues
PRAGMA wal_checkpoint(TRUNCATE):- Success (0): The WAL journal is completely integrated into the main database file, which is then copied atomically.
- Contention / Busy: If another process holds an active write lock, ProSync aborts the copy operation immediately, logging
SQLITE_BUSYto prevent creating a corrupted partial snapshot.
ProSync supports Python 3.10, 3.11, and 3.12 (>=3.10).
pip install -r requirements.txtPySide6 >= 6.5.0(GUI & system tray integration)paramiko >= 3.4.0(Hardened SFTP network transport)tzdata >= 2025.2(IANA timezone database for Windows scheduling)pypdf >= 4.0.0(Pure-Python document preview in ProSyncReader)(Optional) python-docx(Word document search preview)
ProSync includes a complete headless command-line interface for scheduled tasks and headless servers:
# List all configured connections and their status
python ProSyncStart_V3.1.py --list
# Execute a specific connection by ID or exact name
python ProSyncStart_V3.1.py --run "Daily Project Mirror"
# Execute all enabled connections sequentially
python ProSyncStart_V3.1.py --all
# Run quietly in automated environments
python ProSyncStart_V3.1.py --all --quiet --config path/to/config.jsonProSync features a robust scheduling engine with dual trigger modes:
- Periodic Interval: Runs every
Nminutes or hours while ProSync resides in the system tray. - Daily Local Wall-Time: Triggers at an exact local time (e.g.,
18:00). ProSync utilizes Python'szoneinfoandtzdatato handle daylight saving time (DST) transitions cleanly without missed backups or duplicate execution cascades.
The desktop client exports a sanitized configuration file (prosync-profile-v1.json) via ⇄ Profil austauschen. The companion reader in web_companion/ provides offline inspection:
- Completely offline: static HTML5, CSS, and Service Worker.
- Zero secrets: local filesystem paths and credentials are automatically redacted.
- Accessible on mobile devices or local tablets via local HTTP preview:
cd web_companion
python -m http.server 4179ProSync integrates seamlessly with the ProFiler companion search utility (ProSyncReader.py):
- Full-text search across synchronized files and SQLite metadata catalogs.
- Instant preview for PDF and text documents.
- Direct launch integration from the ProSync main interface.
python ProSyncReader.pyProSync includes complete Microsoft Store / MSIX staging materials:
- AppxManifest: Located at
store_package/ProSync/AppxManifest.xmlwith Desktop Bridge identityGeiger.ProSync. - Policy 10.1.3 Compliance: Rigorously curated keywords (max 7 high-intent terms).
- Automated Verification:
python scripts/check_store_readiness.py
- Local Executable Build:
build_exe.batcreates standalone frozen executables for Windows.
Last verified on 2026-09-18: 124 Python tests and 29 Web/PWA tests passed (153 total tests).
# Compile check across all core modules
python -m compileall -q ProSyncStart_V3.1.py ProSyncReader.py prosync_utils.py schedule_time.py logger.py run_tests.py
# Run comprehensive test suite
python -m pytest -ra -v
# Run local orchestrator
python run_tests.py
# Lint with Ruff
python -m ruff check .
# Verify web companion test suite
cd web_companion
npm test
node --check app.js
node --check library.js
node --check sw.jsProSync is licensed under the permissive MIT License.
- Dynamic Linking Isolation: PySide6 (LGPL-3.0) and Paramiko (LGPL-2.1) are dynamically linked via standard CPython wheels. In standalone distributions, Qt shared objects remain separate in compliance with LGPL-3.0 Section 4.
- Unprivileged User Mode (
RunAsInvoker): Strictly executes in unprivileged user space without administrative prompts. - Detailed Software Inventory: Refer to THIRD_PARTY_LICENSES.md and THIRD_PARTY_LICENSES.txt for complete SPDX identifiers, URLs, and upstream notices.
ProSync is maintained by file-bricks under the open-bricks open-source initiative. For vulnerability reporting, consult SECURITY.md (48-hour response SLA).
| Repository | Org | Description | Focus Area |
|---|---|---|---|
| ProSync | file-bricks |
Intelligent backup sync & SQLite WAL database protection | Backup & Database Safety |
| ExplorerPro | file-bricks |
Advanced multi-tab desktop file manager & workspace organizer | File Management |
| CloudLockFixer | file-bricks |
Cloud sync lock resolver, offline cache validator & unblocker | Cloud Sync Hygiene |
| ProFiler | file-bricks |
Deep file indexing, metadata tagging & search companion | File Indexing & Search |
| NoteSpaceLLM | file-bricks |
Local desktop notes workspace with AI augmentations | Local Notes & Knowledge |
| WinStorePackager | file-bricks |
Automated MSIX & Windows Store packaging toolchain | App Store Tooling |
| UniversalDocsGrabber | doc-bricks |
Universal document acquisition, OCR, and redacted PWA reader | Document Processing |
| MediaBrain | doc-bricks |
Intelligent media cataloging and asset indexing | Media Management |
| CleanMarkdown | doc-bricks |
Markdown sanitization, link validation, and typography linter | Markdown Hygiene |
| ellmos-filecommander-mcp | ellmos-ai |
Local-first 47-tool MCP server for files, search & diagnostics | Agent Tooling |
| lock-master | ellmos-ai |
Distributed agent file-claim coordination & lock arbitration | Agent Concurrency |
| WikiStub-Seed | dev-bricks |
Automated documentation generator & multilingual stub creator | Developer Tooling |
| open-bricks | open-bricks |
Umbrella organization for privacy-first developer tools | Open-Source Umbrella |



