TerraManager

Lokale und datenschutzfreundliche Terrarienverwaltung

View the Project on GitHub CodefrogCF/TerraManager

Platform Support

This document describes the current platform validation status of TerraManager.

Status

Platform Status
Android Validated
Web Validated
iOS Planned / not validated

The validated Web entry point is the standalone, browser-local application. The separate Shared Care Web entry point uses the self-hosted LAN API and server-owned database. Its automated client and server tests do not replace deployment and multi-browser validation on the target Pi; follow the Shared Care deployment guide for those checks. On one Raspberry Pi installation, the operator has confirmed shared Box and Feeding updates between mobile and laptop browsers, a Box QR scan over trusted HTTPS, stale-edit conflict handling and portable backup restore in a separate test stack. The operator has also reported successful practical checks of the current parity update, including context actions, the due-Feeding indicator and Box QR exports. These observations apply to that installation; the complete field checklist in the deployment guide still applies to new installations and updates. Shared Care is a separate browser mode, not a network-enabled Android release; Android retains its standalone database and permissions.

The Shared Care interface includes Box and Animal context actions in flat and Big Picture overviews, archived-record restore, in-app Feeding reminders with an Animals navigation badge, and browser downloads of selected Box QR codes as PNG images, ZIP or printable A4 PDF. These client features use server-owned records and the existing HTTPS care API. Their automated coverage does not constitute manual validation on every browser; repeat the field checklist after deploying a new client build.

Permanent Application Identity

Development build 0.14.2+34 adopts com.codefrog.terramanager as the permanent application identifier. Android and Web remain the validated target platforms. Matching identifiers and names in the prepared iOS, macOS, Linux and Windows projects remove Flutter placeholders but do not constitute platform validation.

Android releases through v0.14.1 used com.example.flutter_application_1. Android installs the permanent-ID build as a separate application. Users must create a .tmbackup with the old version, restore it in the new application and verify their data before removing the old installation.

Android Production Signing

Official Android releases use the permanent application identity com.codefrog.terramanager and the established production signing configuration.

The authoritative signing, credential and certificate-verification procedure is maintained in:

Android release signing

User-facing installation and update guidance is maintained in:

Installation and updates

Android

Android support has been validated on physical hardware.

Validated functionality includes:

QR images saved on Android are stored through the platform media/gallery system so they remain accessible to the user outside the application.

QR ZIP archives and A4 PDF sheets are generated completely on-device and use the operating-system save dialog. This does not require unrestricted storage, media-library or network access.

QR Rehouse Mode reuses the existing scanner and camera permission. Box resolution, destination validation and Animal reassignment remain local. The workflow requires no additional storage, media-library, network, notification or background permission.

TerraManager backup files use the Android system file selection interface. The user can therefore choose an accessible destination such as Downloads, Documents or another available storage provider.

Box and Animal pictures are stored persistently through Drift in the MediaAssets table. Animal picturePath values are retained only as a legacy migration fallback.

New and edited Box and Animal forms expose one context-sensitive Add Picture or Change Picture action. It opens a source menu for Camera and Gallery. The Camera option is disabled if the active platform implementation reports that capture is unsupported. Cancelling selection or denying access leaves the existing picture unchanged and keeps the form usable.

After crop confirmation, Android encodes new and replaced pictures as WebP with quality 82 and limits their longest edge to 1920 pixels without upscaling. Existing pictures remain unchanged.

Web

Web support has been validated using a Chromium-based browser.

Validated functionality includes:

WebP optimization for new and replaced pictures uses browser Canvas encoding and has been validated as part of the v0.12.0 Web regression.

QR Rehouse Mode uses the same browser camera access as the existing Box and Feeding Mode scanners. It introduces no additional browser permission and sends no QR identifier or Animal data to a remote service.

Web Database

Web persistence uses Drift with SQLite WASM.

Repository-managed files:

web/sqlite3.wasm
web/drift_worker.dart

The Drift worker is compiled before a Web build using:

dart compile js -O4 web/drift_worker.dart -o web/drift_worker.dart.js

The generated worker JavaScript, dependency list and source map are ignored by Git and are included in the generated Web build output by this step.

The sqlite3.wasm version must remain compatible with the sqlite3 Dart package resolved by the project.

Persistent Box and Animal pictures are stored as MediaAssets through the same Drift database abstraction used by the rest of the application.

Schema Version 12 stores ordered Animal and Box picture histories through owner-specific association tables. Gallery viewing, primary selection and individual deletion are local database operations. Adding an image reuses the existing explicit Camera or Gallery selection flow and introduces no additional storage, media, network or background permission.

New picture bytes are normalized before persistence. Backup restore deliberately does not recompress restored media, preserving compatibility and avoiding generation loss.

Backup Portability

TerraManager Backup Format Version 2 is the current portable format and avoids platform-specific storage identifiers. Version 1 remains supported for legacy restore.

Portable backups contain:

manifest.json
data.json
settings.json
media/
├── animals/
└── boxes/

Backups do not depend on:

Box and Animal pictures are exported as portable media files and restored into the local MediaAssets persistence layer.

settings.json preserves theme mode, accent color, application language, preferred Animal name order and the Animal and Box Overview sort orders. Backups without the newer settings fields remain compatible and restore their documented defaults.

The following transfers have been manually validated:

Android backup → Android restore
Web backup     → Web restore
Android backup → Web restore
Web backup     → Android restore

Current Version 2 backups also preserve timestamped shedding history, per-Animal Weight and Shedding detail visibility, category-view presentation, Big Picture Mode and the optional next-feeding summary.

Missing visibility fields from older backups default to enabled. Missing Big Picture Mode and next-feeding-summary settings default to disabled. Animal and Box archive sort preferences remain local to the current installation and are not replaced during restore.

Known Web Limitations

Large password-protected backups

Password protection is optional. Encryption and authentication can take several minutes for media-rich backups. Current browser selection, validation, upload and download fallback paths may use memory proportional to the complete archive. A protected backup close to the 256 MiB import limit can therefore fail on a device with insufficient available memory. TerraManager validates and authenticates the backup before collection replacement; a failed or cancelled attempt leaves the existing collection unchanged.

Browser-managed storage

Application data is stored in browser-managed local storage.

Clearing site data may remove the TerraManager database, persistent Box and Animal pictures and local appearance and language settings.

Portable .tmbackup files stored outside the browser can be used to restore data after such a loss.

Private/incognito browser modes may not provide reliable long-term persistence.

Camera

QR scanning requires:

The scanner camera-light control is available only when the active camera and platform report torch support. It remains hidden otherwise. The current Web scanner dependency reports the torch as unavailable, so Web scanning continues without this control.

Camera access generally requires:

https://

or:

localhost

Behavior may vary between browsers and devices.

The Shared Care scanner requires trusted HTTPS on the LAN and a browser with the native BarcodeDetector API. It scans Box labels locally and sends only the validated QR identifier to the operator’s server for lookup. It does not load a decoder from an external CDN. Browsers without the native reader can still use Shared Care record and history pages but cannot scan Box labels. The Android app’s external-browser link does not add Android network or camera permissions beyond the standalone app’s existing permissions.

Camera-based picture capture also depends on browser and device support. When the browser does not expose it through the image picker, TerraManager disables the Camera option in the source menu while keeping Gallery selection available.

Downloads

QR images, QR ZIP archives, A4 QR PDF sheets and TerraManager backup files are saved through browser and operating-system facilities.

The final download location therefore depends on browser and operating-system settings.

Application preferences

Appearance and language settings are stored locally through shared_preferences.

Clearing browser site data may therefore reset both the TerraManager database and locally stored application preferences.

Appearance and language settings are included in portable TerraManager backups.

iOS

TerraManager is intended to support iOS in the future.

iOS has not yet been validated because no macOS build environment or physical iOS test device is currently available.

The following therefore remain unverified:

iOS must not currently be described as a validated platform.