Skip to content

Latest commit

 

History

83 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

ProSync Banner

ProSync

English · Deutsch · Español · User Guide

Intelligent local backup synchronization with automated SQLite WAL database protection.

License: MIT Version Platform: Windows | Linux | macOS Python: 3.10 | 3.11 | 3.12 Tests: 153 passed Privacy: 100% Local | Zero-Egress Security: RunAsInvoker Security SLA: 48h / 5d Third-Party: Audited Ecosystem: file-bricks Umbrella: open-bricks Context: llms.txt Last Checked

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.


Quick Navigation

  1. Features & Core Capabilities
  2. System Architecture & Data Flow
  3. Target Personas & Discoverability
  4. Comparative Matrix vs. Alternatives
  5. Dual Mermaid Diagrams
  6. Governance & Runtime Invariants
  7. Synchronization Modes & Semantics
  8. SQLite WAL Database Protection
  9. Visual Showcase & Feature Gallery
  10. Installation & Dependencies
  11. CLI & Headless Automation
  12. Scheduled Backups & IANA Timezones
  13. Portable Web/PWA Companion
  14. ProSyncReader & ProFiler Search
  15. Windows Store & MSIX Staging
  16. Testing & Quality Checks
  17. Third-Party Licenses & Transparency
  18. Security Policy & Sibling Ecosystem

1. Features & Core Capabilities

  • 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.json for 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).

2. System Architecture & Data Flow

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)              |
+---------------------------------------------------------------------------------+

3. Target Personas & Discoverability

Target Personas

  • [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 on SQLITE_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.

High-Intent Search Queries

  • "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"

4. Comparative Matrix vs. Alternatives

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

5. Dual Mermaid Diagrams

System Architecture Topology (flowchart TD)

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
Loading

End-to-End Backup & WAL Checkpoint Lifecycle (sequenceDiagram)

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
Loading

6. Governance & Runtime Invariants

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.

7. Synchronization Modes & Semantics

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

8. SQLite WAL Database Protection

ProSync proactively detects active SQLite database files and enforces crash-consistent protection mechanisms:

Supported Database Extensions

  • SQLite: .sqlite, .sqlite3, .db, .db3
  • MS Access: .mdb, .accdb

Protection Rules

  1. 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.
  2. Dedicated File Connections: For live databases, users configure a dedicated File Connection with WAL Checkpoint enabled.
  3. 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_BUSY to prevent creating a corrupted partial snapshot.

9. Visual Showcase & Feature Gallery

Main Overview & Connection Manager SQLite WAL Database Safety Portable Profile & PWA Companion
Main Overview Database Backup Portable Profile
Multi-task connection manager with scheduled intervals and batch queue. Automated SQLite WAL detection and pre-copy checkpoint validation. Redacted profile export for offline inspection and mobile PWA reader.

10. Installation & Dependencies

ProSync supports Python 3.10, 3.11, and 3.12 (>=3.10).

pip install -r requirements.txt

Core Runtime Dependencies

  • PySide6 >= 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)

11. CLI & Headless Automation

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.json

12. Scheduled Backups & IANA Timezones

ProSync features a robust scheduling engine with dual trigger modes:

  1. Periodic Interval: Runs every N minutes or hours while ProSync resides in the system tray.
  2. Daily Local Wall-Time: Triggers at an exact local time (e.g., 18:00). ProSync utilizes Python's zoneinfo and tzdata to handle daylight saving time (DST) transitions cleanly without missed backups or duplicate execution cascades.

13. Portable Web/PWA Companion

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 4179

14. ProSyncReader & ProFiler Search

ProSync 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.py

15. Windows Store & MSIX Staging

ProSync includes complete Microsoft Store / MSIX staging materials:

  • AppxManifest: Located at store_package/ProSync/AppxManifest.xml with Desktop Bridge identity Geiger.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.bat creates standalone frozen executables for Windows.

16. Testing & Quality Checks

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.js

17. Third-Party Licenses & Transparency

ProSync 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.

18. Security Policy & Sibling Ecosystem

ProSync is maintained by file-bricks under the open-bricks open-source initiative. For vulnerability reporting, consult SECURITY.md (48-hour response SLA).

Sibling Ecosystem Matrix

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

Releases

Packages

Used by

Contributors

Languages