# 🛡️ QGIS Ledger v4.0

[![QGIS Version](https://img.shields.io/badge/QGIS-3.0%2B%20%7C%204.0-589632?logo=qgis&logoColor=white)](https://qgis.org/)
[![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
[![PyQt5 / PyQt6](https://img.shields.io/badge/Qt-PyQt5%20%7C%20PyQt6-41cd52?logo=qt&logoColor=white)](https://www.riverbankcomputing.com/software/pyqt/)
[![Code style: flake8](https://img.shields.io/badge/lint-flake8-informational)](https://flake8.pycqa.org/)

**🌐 Lingua / Language:** [🇮🇹 Italiano](#-italiano--descrizione-architetturale) · [🇬🇧 English](#-english--architectural-overview)

> Enterprise-Grade Version Control and Cloud Orchestration for the QGIS Ecosystem.

**QGIS Ledger** (plugin name: `qgis_ledger`) transforms the conventional QGIS desktop environment into a collaborative, fully distributed geospatial platform. Built for absolute data integrity, it seamlessly introduces a Git-like snapshot architecture, semantic differential geometry analysis, deterministic rollbacks, and integrated native Cloud synchronization.

### 🌟 Key Architecture & Principles
- **Zero External Python Dependencies:** Operates exclusively via the Python standard library, utilizing PyQGIS and native SQLite processing. No `pip install` required.
- **Universal Portability:** Employs dynamic relative path resolution, guaranteeing absolute operational fidelity when migrating projects across Windows, Linux, and MacOS environments.
- **Version Agnosticism:** Fully tested and compliant with **QGIS 3.x** and ready for the next-generation **QGIS 4 (Qt6)** framework.

## 🎥 Video Tutorial

<iframe width="640" height="360" frameborder="0" src="https://mega.nz/embed/1vdnCayB#Ep91QMDOu4HBw5PdL8fm9ug87PztME-eBQ1_hNWsN08!1a" allowfullscreen allow="autoplay;"></iframe>


> 🇮🇹 **[Guarda il Video Tutorial Completo e scopri come utilizzare QGIS Ledger in azione](https://me.sinocloud.it/index.php/apps/maps/s/RfSi99EWE6iT9ng)**
>
> 🇬🇧 **[Watch the Full Video Tutorial and discover how to use QGIS Ledger in action](https://me.sinocloud.it/index.php/apps/maps/s/RfSi99EWE6iT9ng)**


---

## 🇮🇹 ITALIANO — Descrizione Architetturale

QGIS Ledger è un motore di tracciamento storico e sincronizzazione cloud progettato per l'integrità dei dati spaziali, operante localmente senza l'ausilio di complessi database server (come PostGIS) o layer applicativi esterni.

### Funzionalità Core (Versionamento)
- **Architettura a Snapshot (Commit):** Salva copie esatte e contestuali dei layer vettoriali, raster, o dell'intero workspace (`.qgz`) all'interno di un database transazionale locale SQLite (`.ledger.db`).
- **Locale / LAN Nativo:** Lo storico e le iterazioni temporali sono memorizzate per impostazione predefinita in una cartella a fianco del file di progetto (`.qgz`). Lavorando su una porzione di rete condivisa (LAN), l'intero ecosistema storico è universalmente accessibile e sincronizzato per tutti i membri del team senza configurazioni aggiuntive.
- **Diff Semantico-Visuale:** Un algoritmo basato su logica a differenza simmetrica esplora topologicamente le entità spaziali, iniettando nella mappa layer temporanei che evidenziano visivamente feature *aggiunte* (🟢), *rimosse* (🔴), o *mutate* (🟡) tra due punti della storia.
- **Rollback Deterministico:** Ripristina l'infrastruttura dei metadati e il payload geometrico a qualsiasi iterazione temporale precedente, ricostruendo contestualmente le simbologie associate.
- **Interfaccia di Merge (Risoluzione Conflitti):** Modulo ad analisi split-screen per l'individuazione e la mitigazione di collisioni scaturite da editing asincrono in scenari network-shared.

### Orchestrazione e Sincronizzazione
- **Pannello Timeline Relazionale:** Interfaccia stile GitKraken per la navigazione intra-database dei commit, con supporto alle preview non-distruttive e log visivi istantanei (tramite snapshot PNG generati contestualmente ad ogni commit).
- **Automazione Trigger-Based (Auto-Commit & Auto-Save):** Polling thread-safe e injection negli eventi del Canvas per storicizzare file e vettori ad intervalli cronometrici, assicurando un paracadute costante contro i crash.

### Integrazione Multi-Cloud & File Browser
- **I/O Trasparente (Zero-Pip):** Pieno supporto nativo per Nextcloud, WebDAV generici (Box, Koofr, pCloud, NAS), Dropbox API v2, Microsoft Graph (OneDrive/SharePoint) e Google Drive API v3 (con rinnovo token automatico).
- **Orologio Cloud Nativo:** Dock-widget interno preposto alle operazioni CRUD direttamente su istanze remote Cloud.
- **GeoPackage Serialization On-the-Fly:** La manipolazione file (drag-and-drop da mappa a cloud) innesca un algoritmo di conversione dinamica e auto-encapsulation del layer in file GeoPackage, pre-caricando la logica di stile direzionale della tabella `layer_styles` per massima fedeltà visiva durante il re-import in altre stazioni.

---

## 🇬🇧 ENGLISH — Architectural Overview

QGIS Ledger is a comprehensive historical tracking and cloud synchronization engine engineered for definitive geospatial data persistence, operating entirely without the complexities of heavyweight server databases (e.g. PostGIS) or external application stacks.

### Core Architecture (Versioning)
- **Snapshot Infrastructure (Commit):** Safely persists atomic checkpoints of vector pipelines, raster topologies, or the entire composite `.qgz` workspace inside a robust transactional SQLite database (`.ledger.db`).
- **Native Local / LAN Tracking:** Versions and history are stored natively inside a `.ledger_history` sidecar folder directly alongside your `.qgz` project file. When operating from a shared network drive (LAN), this ensures the full historical state is universally synced and accessible to all team members out-of-the-box, with strictly zero configuration required.
- **Semantic Visual Diff Engine:** Utilizes advanced symmetric-difference geometry algorithms to isolate and spatialy highlight structural modifications—*added* (🟢), *removed* (🔴), or *mutated* (🟡) features—across diverging history branches.
- **Deterministic Rollback Verification:** Instantaneously reconstructs previous infrastructural data schemas and gracefully re-attaches style payloads to guarantee continuous map rendering limits.
- **Conflict Resolution Telemetry (Merge Wizard):** A real-time split-screen interface designed to mitigate and resolve asynchronous overwrite anomalies within inherently shared persistent storage zones.

### Observability & Automation
- **Relational Timeline Panel:** An intuitive, strictly ordered graphical navigator (akin to GitKraken) exposing the underlying database logic, featuring non-destructive layer preview routines backed by instantaneous map-state screen-capturing logic.
- **Silent Trigger Automation:** Hooks into native QGIS Canvas edit lifecycles to trigger silent foreground auto-commits on data writes, alongside asynchronous background polling auto-saves, completely nullifying data-loss vectors.

### Multi-Cloud I/O Integration
- **Dependency-Free Providers:** Implements raw `stdlib` pipelines seamlessly supporting Nextcloud, Generic WebDAV standards (Box, Koofr, NAS), Dropbox API v2, Microsoft Graph (OneDrive/SharePoint), and Google Drive API v3 implementations (capable of token auto-refresh callbacks).
- **Native Extensible Cloud Browser:** Interoperable dock widget empowering local users with fully-fledged CRUD capability over disparate file systems without engaging external internet browsers.
- **On-the-Fly GeoPackage Serialization:** Dragging and dropping dynamic layers off the local canvas directly onto cloud roots invokes immediate format translation into strictly encapsulated GeoPackages—embedding active `.qml` styling definitions seamlessly into its internal `layer_styles` table metadata payload.

---

## 📁 Repository Structure / Struttura File di Progetto

```text
📂 Project Root/
├── my_qgis_project.qgz          ← The QGIS binary project file
├── my_qgis_project.ledger.db    ← SQLite tracking DB for logs, references and versions
└── .ledger_history/             ← Isolated local version-control directory
    ├── project/                 ← Retained snapshots for `.qgz` project rollbacks
    ├── raster/                  ← Compressed archived states for heavy raster grids
    └── screenshots/             ← Automatically generated PNG tracking history contexts
```

---

## 🚀 Installation & Build

1. Clone or copy the entire repository into your local QGIS user profile plugins catalog:
   ```bash
   cp -r qgis_ledger ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/
   ```
2. Open QGIS $\rightarrow$ **Plugins** $\rightarrow$ **Manage and Install Plugins** $\rightarrow$ enable **QGIS Ledger** (formerly *sketinel*).
3. The integrated toolbar will immediately hook into your GUI. Configure preferred Cloud providers via the `⚙ Settings` dialog module.

---

## 📄 License & Maintenance

Licensed strictly under the **GNU General Public License v2.0 or subsequent versions**.

Maintained by **Dott. Sarino Alfonso Grande**
- ✉️ **Email:** [sino.grande@gmail.com](mailto:sino.grande@gmail.com)
- 🌐 **Sito ufficiale / Official website:** [sinocloud.it](https://sinocloud.it)
- 🐙 **GitHub:** [sag1687](https://github.com/sag1687)

Copyright © 2026 Dott. Sarino Alfonso Grande.

---

## 🎨 Tema e scheda Info / Theme and Info tab

> **IT** · Dalla versione 4.0 QGIS Ledger adotta il tema scuro **"slate blue"** condiviso da tutta la famiglia di plugin SinoCloud (lo stesso di SARIAG e STAC Browser). Il selettore lingua nelle Impostazioni usa le **bandiere** (🇮🇹 Italiano, 🇬🇧 English e altre lingue) e nella scheda **Info Plugin** un **menù a tendina** elenca gli altri plugin dell'autore con descrizione bilingue e link al repository GitHub.
>
> **EN** · Since version 4.0 QGIS Ledger adopts the **"slate blue"** dark theme shared by the whole SinoCloud plugin family (the same as SARIAG and STAC Browser). The language selector in Settings uses **flags** (🇮🇹 Italiano, 🇬🇧 English and more languages) and the **Info Plugin** tab hosts a **drop-down** listing the author's other plugins with bilingual description and GitHub repository link.

### Altri plugin dell'autore / Other plugins by the author

| Plugin | Repository |
|---|---|
| **SARIAG** | [github.com/sag1687/sariag](https://github.com/sag1687/sariag) |
| **STAC Browser** | [github.com/sag1687/stac_browser](https://github.com/sag1687/stac_browser) |
| **GeoBridge** | [github.com/sag1687/geobridge](https://github.com/sag1687/geobridge) |
| **Quick CRS Fixer** | [github.com/sag1687/CRS_FIXER](https://github.com/sag1687/CRS_FIXER) |
| **GeoCSV Mapper** | [github.com/sag1687/GeoCSV-Mapper](https://github.com/sag1687/GeoCSV-Mapper) |
| **Q-Press** | [github.com/sag1687/q_press](https://github.com/sag1687/q_press) |
| **TAF Italia** | [github.com/sag1687/TAF_ITALIA_DOWNLOAD](https://github.com/sag1687/TAF_ITALIA_DOWNLOAD) |
