Lokale und datenschutzfreundliche Terrarienverwaltung
TerraManager is a cross-platform, local-first application for managing terrarium boxes, animals and feeding records.
The application is developed with Flutter and currently supports Android and Web.
iOS support is planned, but has not yet been validated because no macOS build environment or physical iOS test device is currently available.
Public project information:
The development version is maintained in pubspec.yaml; published versions
are listed in GitHub Releases and CHANGELOG.md.
Validated release platforms:
iOS support remains planned but has not yet been validated.
The current technical compatibility baseline is:
com.codefrog.terramanagerFor authoritative details see:
Published changes are recorded in the CHANGELOG.
TerraManager provides local-first management for Boxes, Animals, feeding, weight and shedding histories, reminders, picture galleries, QR workflows, lifecycle archives and portable backups. The current overview workflows include optional large-picture presentation, while the archive workflows provide sorting, restoration and duplication for both Animals and Boxes. QR scanning supports Box lookup, grouped feeding and confirmed Animal reassignment without sending collection data to a remote service.
The public homepage and user guides describe the current user-facing workflows:
Published feature changes are recorded in the repository CHANGELOG.
Current and planned development work is tracked in the roadmap.
This document intentionally does not maintain a second feature-by-feature specification.
The core concept is based on physical terrarium boxes identified by permanent QR codes.
Each box receives a unique QR identifier when it is created.
The QR code does not contain animal or terrarium data. It contains only the permanent box identifier.
Example:
Physical Box
│
│ QR Code
▼
TM:BOX:<UUID>
│
▼
Database
│
└── Box
│
├── Animal
├── Animal
└── ...
The QR identifier remains stable even when animals or other application data change.
Scanning the QR code resolves the identifier through the local database and opens the corresponding box.
TerraManager is designed as a local-first application.
Core functionality does not require an internet connection.
In standalone mode, application data is stored locally on the current device or browser profile.
UI
│
▼
Repository
│
▼
Drift
│
▼
Local Database
The optional Shared Care Web mode uses a separate Flutter entry point. It authenticates against a self-hosted LAN server, which alone owns the SQLite collection. Shared-mode browsers hold no local collection database and cannot edit while disconnected. Appearance, language and sorting preferences are stored per account on the server. Big Picture Mode is selected in Settings and applies to both overviews and their archives. The Show next feeding switch immediately above it controls the future-feeding summary without hiding due reminders. Overview thumbnails use a bounded in-memory cache for the current overview; unchanged pictures survive scrolling and collection polling, while a new visit, detail return or manual reload refreshes them. Sorting and Animal category grouping remain in the overview toolbars, which follow the standalone action order with Reload as the additional rightmost control. The Android app can open this mode in an external browser; its local collection remains independent.
Shared Care’s active Box overview can scan a physical Box label in a browser with native QR recognition. The camera image stays on the device; only a validated Box QR identifier is sent to the operator’s API. The scanner does not fetch an external decoder. Trusted HTTPS is required on other LAN devices. The deployment guide lists the full two-device, scanning and recovery checks still needed for a new installation.
From v1.14.2, New Animal offers the same QR button beside the Box selector in standalone and Shared Care. Scanning selects an active Box and preserves the draft; cancelling leaves the selection unchanged. It does not create an Animal or move an existing one. Creation still requires an explicit, validated Save. Edit Animal retains the existing confirmed QR rehousing workflow.
Shared Care Box and Animal context menus use Edit for name changes and have no separate Rename entry. Applicable Details, Duplicate, Archive, Feeding and Restore actions retain their existing permissions. Standalone menus are unchanged. Shared Care Edit Animal also exposes the existing independent Weight and Shedding visibility fields. These belong to the Animal and affect all users’ detail views; they are not personal account preferences. Hiding either section preserves its history, and portable backups retain both visibility values.
Shared Care Animal and Box uploads now use the standalone selection/cropping flow, including EXIF orientation normalization, free-form touch/pointer controls and WebP optimization. Cancelling does not upload or change existing pictures. The cropped/optimized result must meet the existing 8 MiB upload limit, and busy/error handling prevents duplicate submissions and false successful entries.
Opening an Animal or Box primary/detail-gallery picture in either mode passes the same ordered gallery to the common fullscreen viewer at the selected index. Visible Previous/Next controls, arrow keys and one-finger horizontal swipes navigate without wrapping at the boundaries; the counter shows the current position. Swipes at normal scale navigate, while zoomed drags pan the current picture. Pinch zoom remains available, explicit navigation resets the new picture to normal scale, and a failed/loading image does not disable navigation. Closing the viewer preserves the underlying detail/gallery state.
Administrators can download the complete shared collection as a portable
.tmbackup and restore a compatible archive after saving a current safety
copy and confirming replacement. Only a genuinely empty server collection may
skip the safety download; the server checks every collection table again under
the restore gate, so intervening writes cannot bypass protection. Shared
archives leave caregiver accounts and personal account preferences outside the
portable collection. A host-volume backup is still needed to protect server
accounts and sessions.
Shared Care administrators manage local users through Settings → Server → Manage accounts. The screen supports username and role changes, optional password reset, deactivation/reactivation and confirmed account removal. Changes revoke the affected user’s sessions; the final active administrator is protected. Account removal retains collection records and previous audit attribution while removing credentials and sessions. Caregivers cannot access these administrator controls.
QR Feeding Mode shows current Animal thumbnails beside the names in both standalone and Shared Care. Missing pictures use the existing placeholder; selection changes reuse already loaded media while the form stays open.
Shared Care records local audit metadata for collection and account changes. Events commit with the change, preserve actor attribution after deactivation or removal, and survive portable restore. They contain no notes, pictures or credentials. Audit entries are retained for 365 days; protected host-volume backups include them and portable backups exclude them. The administrator viewer is available to administrators in Shared server Settings. Browser Back returns through detail, scanner and dialog routes; the standalone database remains separate.
There is no developer-operated cloud synchronization.
In standalone mode, data stored on one device is not automatically available on another. Shared Care browsers signed in to the same self-hosted server see the same collection after refresh.
Portable .tmbackup files can be used to manually transfer TerraManager data
between supported devices and platforms.
Backup transfer is not automatic synchronization. A restore replaces the current local TerraManager state with the selected backup.
The authoritative current database model, entity relationships, lifecycle rules and schema history are maintained in:
Portable backup representation is intentionally documented separately in:
These documents are the technical source of truth for database and backup compatibility.
QR functionality is separated into reusable generation, export, validation and resolution components.
Box.qrId
│
├── BoxQrCode
│
├── QrExporter
│ │
│ ▼
│ PNG / ZIP / PDF bytes
│ │
│ └── Platform save workflow
│
└── QR Scanner
│
▼
QR validation
│
▼
BoxRepository
│
├── Open Box details
├── Start Feeding Mode
└── Resolve an active destination for Rehouse Mode
The QR image itself is not stored in the database. It is generated from the permanent qrId when needed. A Rehouse scan resolves the identifier locally and accepts only an existing active Box. The application asks for confirmation before the repository moves the active Animal. Unknown, archived and current Box identifiers are rejected. The reassignment is transactional and does not require a new permission or network connection.
The project separates presentation, application-facing repositories and persistence.
TerraManagerApp
│
▼
AppShell
│
├── Boxes
├── Animals
└── Settings
│
▼
Repositories
│
▼
Drift
│
▼
Local Persistence
The UI should not contain direct database implementation logic.
Repositories provide the application-facing API for data access and modification.
Platform-specific functionality is isolated behind services where practical.
The project is organized approximately as follows:
lib/
├── main.dart
├── app.dart
│
├── core/
│ ├── theme/
│ │ └── app_theme.dart
│ │
│ ├── database/
│ │ ├── app_database.dart
│ │ ├── app_database.g.dart
│ │ ├── converters/
│ │ ├── enums/
│ │ ├── tables/
│ │ └── repositories/
│ │
│ ├── media/
│ │ ├── image_media_info.dart
│ │ └── legacy_animal_picture_migration_service.dart
│ │
│ └── qr/
│ ├── qr_export_service.dart
│ ├── qr_file_name.dart
│ ├── qr_id_generator.dart
│ ├── qr_storage_service.dart
│ └── qr_validator.dart
│
├── features/
│ ├── navigation/
│ ├── boxes/
│ ├── animals/
│ │ └── presentation/
│ │ └── animal_display_names.dart
│ ├── feedings/
│ ├── media/
│ │ └── presentation/
│ │ ├── picture_selection_flow.dart
│ │ ├── pages/
│ │ │ ├── full_screen_image_page.dart
│ │ │ └── picture_crop_page.dart
│ │ └── widgets/
│ │ └── picture_selection_controls.dart
│ ├── settings/
│ │ ├── app_accent.dart
│ │ ├── app_language.dart
│ │ ├── animal_name_order.dart
│ │ ├── animal_sort_order.dart
│ │ ├── box_sort_order.dart
│ │ ├── app_settings_controller.dart
│ │ └── presentation/
│ │
│ └── backup/
│ ├── application/
│ ├── domain/
│ └── infrastructure/
│
└── l10n/
├── app_en.arb
├── app_de.arb
├── app_localizations_context.dart
└── app_localizations_labels.dart
Generated Drift files such as:
lib/core/database/app_database.g.dart
must not be edited manually.
Installation, update, migration and Web deployment instructions are maintained in the canonical guide:
Android production signing is maintained separately in:
TerraManager stores application data locally and has no TerraManager-operated account, backend, cloud sync, advertising, analytics, telemetry or crash- reporting service. Camera, gallery and file access is requested only for the corresponding user-initiated feature. Feeding reminders remain inside the application and do not request system notification permission.
Portable .tmbackup archives include records, settings and pictures. They can
be exported unprotected or with optional password protection. Protected backups
use an authenticated encrypted container; existing unprotected backups remain
supported. Store backup files and their passwords separately and treat every
backup as sensitive. The complete data and permission description is available
in PRIVACY.md.
Report reproducible problems and feature requests through GitHub Issues, following SUPPORT.md. Do not publish real backups, private notes, pictures, passwords or signing material. Potential vulnerabilities should follow the private-first process in SECURITY.md.
Copyright (C) 2026 Codefrog.
TerraManager is free software licensed under the
GNU General Public License v3.0 or later, identified as
GPL-3.0-or-later. The licence permits private and commercial use,
modification and redistribution subject to its terms. In particular, a
distributed modified version must preserve the recipients’ GPL freedoms and
provide its corresponding source as required by the licence.
The maintainer may separately offer services, official builds, support, custom development or alternative commercial licence terms. Those offerings do not reduce the rights granted for the GPL-licensed project.
Before submitting source code, translations, artwork or substantial documentation, read CONTRIBUTING.md. The current contribution policy deliberately preserves the option of consistent future dual licensing.
Development setup, code generation and issue-level validation are maintained in:
The supported toolchain and automated quality-gate baseline are maintained in:
Release validation is maintained in:
Documentation ownership, localization alignment, screenshot maintenance and release-review responsibilities are defined in:
Key authoritative documents:
TerraManager currently follows a local-first architecture.
There is no cloud synchronization or automatic multi-device synchronization.
Data is stored locally on the current device or browser profile. Portable
.tmbackup files can be used for manual backup, recovery and transfer between
validated platforms.
Web data can still be lost when browser site data is cleared if no external backup exists.
iOS has not yet been validated.
Detailed platform-specific limitations are documented in:
docs/platform-support.md