What RecoverLand does

• Captures every committed edit on monitored editable layers (attributes, geometry, INSERT, UPDATE, DELETE)
• Delta storage: only the attributes that actually changed are recorded (10–50x volume reduction versus full-row snapshots)
• Smart edit buffer: merges multiple changes on the same feature into one net event before writing
• Automatically filters layer audit fields (date_modif, updated_by, etc.) so metadata-only changes are not recorded
• Paginated history search by layer, operation type, time window, and user
• Selective restore with schema compatibility report before applying
• Schema drift detection between the saved state and the current layer structure
• Datasource alias resolver: reconcile fingerprints after a project path move without losing history
• Writer lock: refuses to open the journal when another live QGIS instance is already writing to it (PID-based, Windows and POSIX)
• Asynchronous batch writes in a dedicated thread (zero UI blocking)
• Startup integrity check (WAL checkpoint, pending-event recovery, schema version validation)
• Automatic user identification from: plugin config → env variable RECOVERLAND_USER → OS login → QGIS profile name
• Live health monitoring with thresholds on journal size (50 MB / 200 MB / 500 MB) and event count
• Disk space monitoring: auto-disable tracking at critical threshold (100 MB free), warning at 500 MB
• Maintenance dialog: retention policy, purge by age or session, async VACUUM, integrity check, journal export
• Orphan journal cleanup: unsaved-project journals older than 30 days are automatically removed
• Works with all editable formats: GeoPackage, Shapefile, PostGIS, SpatiaLite, GeoJSON, CSV, FlatGeobuf, MS SQL Server, Oracle Spatial

What RecoverLand does not do

• Does not replace a versioning system (Git, GeoGig)
• Does not back up source files, only feature-level changes
• Does not work on non-editable layers (WMS, rasters, virtual layers)
• Does not capture changes made outside QGIS (direct file editing, external scripts)
• Does not synchronize between workstations
• Cannot guarantee restore on weak-identity formats (CSV, repacked shapefiles)

Architecture

The plugin is organized in independent layers. Each layer has a single responsibility and communicates with others through defined interfaces.

Main components

Local trust boundary

The design goal is simple: make the recovery system visible, local, and bounded. Users can understand where data lives, who writes it, and what RecoverLand does not touch.

SQLite Journal

The journal is a single SQLite file per QGIS project. It uses WAL mode (Write-Ahead Logging) to allow concurrent reads and writes without blocking.

Journal location

Unsaved-project journals older than 30 days that no longer correspond to an open project are automatically removed at startup (orphan cleanup).

Schema of the audit_event table

Each row represents a single committed change on one feature.

Simplified schema. The real table also contains: layer_id_snapshot, layer_name_snapshot, provider_type, geometry_type, crs_authid, field_schema_json, and session_id.

Local data model

The local database is intentionally compact. A few tables cover settings, datasource registry, edit sessions, and the event stream. The center of gravity is audit_event, which stores the history at feature level.

Automatic capture

Capture is transparent. The user edits layers normally in QGIS. RecoverLand intercepts edit signals at commit time.

When capture triggers

Smart edit buffer

The edit buffer (EditSessionBuffer) is the working memory of RecoverLand. It captures the initial state of every modified feature at the start of the edit session and computes the real net effect at commit time.

Why a buffer?

A user may edit the same feature multiple times before saving. Without a buffer, each micro-change would generate a separate event. The buffer merges everything into one event representing the actual delta between the initial state and the final state.

Special cases handled by the buffer

Audit field filtering

Layer metadata fields (date_modif, updated_by, updated_at, etc.) are automatically excluded from the delta by the AuditFieldPolicy module. If a commit only touches these fields, it is treated as a no-change and nothing is written. This filtering is applied at three levels: recording, reading, and restore.

Delta storage

A naive audit would store the entire row on every change. On a 50-column table, changing one field would store 50 values. RecoverLand uses a differentiated strategy:

Storage saving

Delta format

The attributes_json field changes semantics depending on the operation:

DELETE: {"all_attributes": {"name": "Dupont", "age": 42, "city": "Paris"}}
UPDATE: {"changed_only": {"city": {"old": "Paris", "new": "Lyon"}}}
INSERT: {"all_attributes": {"name": "Martin", "age": 35, "city": "Lyon"}}

Identification system

The system uses three levels of identification to precisely locate each feature in each layer of each project.

Layer fingerprint

The fingerprint is the core piece of the identification system. It distinguishes two layers that share the same name but come from different sources.

How it is computed

Format: provider::normalized_source

Smart restore without actor multiplication

RecoverLand does not restore "by name" and does not create a new actor for every historical row. It restores against the current entity stream, grouped by entity_fingerprint, and writes only lightweight trace records for auditability.

Identity strength

Not all formats offer the same reliability for identifying a feature. RecoverLand qualifies each format with an identity strength level defined in support_policy.py.

Schema drift

Between the time a change is recorded and the time a user tries to restore it, the layer structure may have changed. The schema_drift.py module detects these drifts before any restore.

What the module compares

Each event stores the field schema at capture time (field_schema_json). Before restore, this historical schema is compared against the current layer schema:

Integrity and recovery

The integrity.py module verifies journal health at plugin startup and after any incident.

Startup checks

Asynchronous writes

Events are written to SQLite by a dedicated thread (WriteQueue). The UI thread never waits for the write to complete. The queue uses batches of 500 events per transaction to maximize throughput.

Retention and purge

The journal grows over time. The retention.py module provides four mechanisms to control its size:

Health monitoring

RecoverLand continuously evaluates journal health and disk space. Alerts appear in the info bar at the top of the main dialog and can be clicked to open the maintenance panel.

Journal health thresholds

Disk space thresholds

Memory management

RecoverLand is designed to operate safely even on large datasets.

Edit buffer cap

The EditSessionBuffer holds feature snapshots in RAM during an edit session. Beyond 10,000 features or 200 MB of snapshot data, snapshots are flushed to a temporary SQLite staging table to avoid memory overflow. This is transparent to the user.

Paginated search

Search results are never fully loaded into memory. The SearchService uses paginated SQL queries (up to 500 events per page) to keep RAM usage flat regardless of journal size.

Write queue

The WriteQueue is bounded. If the writer thread cannot keep up (e.g., very intensive editing), back-pressure is applied to prevent unbounded memory growth.

Restore isolation

Restore operations process features in isolated batches. If one feature fails, the others are still processed. No single large transaction locks the database for a long time.

Event lifecycle

If the user rolls back instead of committing, the in-RAM snapshot is simply discarded. Nothing is written to the journal.

User identification

Every event carries a user_name resolved automatically by the user_identity.py module. Sources are tested in order:

The first non-empty source is used. No event is ever written with an empty user_name.

Project saving and journal relocation

If a QGIS project transitions from unsaved to saved, the journal is relocated from the QGIS profile directory to the .recoverland/ subfolder next to the .qgz file. Events captured before saving are migrated automatically.