Technical Documentation

Architecture Overview

• Frontend: Flutter app targeting Android, iOS, Web, Windows, and Linux.
• Local Storage: Drift (SQLite) for structured data, Hive for preferences and secrets.
• Backend: FastAPI server with PostgreSQL for sync and authentication.
• Encryption: PBKDF2-HMAC-SHA256 key derivation with AES-256-GCM encryption.

Local Data Storage

Tracker uses two complementary storage systems for local data persistence, with platform-specific implementations for mobile and web.

Android / iOS

The database path is determined via getApplicationSupportDirectory() from the path_provider package. Connection is established in lib/data/local/connection/connection_io.dart.

Web Browser

Web storage uses DriftWebStorage.indexedDb('tracker_database') for the main database. Connection is established in lib/data/local/connection/connection_web.dart.

Hive Settings (Key-Value Store)

The Hive box tracker_box stores the following settings:

• preferred_locale — Language preference (en/de/sv)
• preferred_theme_mode — Theme mode (light/dark/system)
• preferred_seed_color — Color scheme seed
• enabled_modules — List of activated app modules
• module_order — Custom module ordering
• journal_pin_hash — SHA-256 hashed PIN for journal security
• journal_pin_salt — Salt for PIN hashing
• encryption_key — Master encryption key for sync
• sync_*_last — Last sync timestamps per data type

Platform Abstraction

The codebase uses conditional imports to support both platforms:

• connection.dart — Platform-agnostic interface
• connection_io.dart — Android/iOS implementation (SQLite file)
• connection_web.dart — Browser implementation (IndexedDB)
• database_deleter_*.dart — Platform-specific database deletion

Database Schema

• greeting_entries — Dashboard messages and onboarding tips.
• note_entries — Markdown and drawing notes with tags.
• task_entries — Tasks with priority, due date, and reminders.
• time_entries — Time tracking sessions with optional task links.
• journal_entries — Daily journal with categories.
• journal_trackers / journal_tracker_values — Custom mood/metric trackers.
• habit_definitions / habit_logs — Habit tracking with streaks.
• ledger_* — Accounts, transactions, budgets, categories, recurring templates.
• sync_tombstones — Tracks deleted items for sync.

Encryption Pipeline

• Master key derived from user password using PBKDF2-HMAC-SHA256 (150k iterations).
• Each sync payload encrypted with AES-256-GCM using unique IVs.
• Per-device salts ensure keys differ across devices.
• Server stores only ciphertext — zero-knowledge architecture.
• Key rotation supported after password changes.

Synchronisation Protocol

• REST/JSON API over TLS 1.3 with short-lived JWT authentication.
• Optimistic locking with version counters per entity.
• Incremental sync using changelog endpoints.
• Conflict detection with revision history (manual resolution).
• Tombstone tracking for deletions across devices.

Data Deletion Implementation

• Local deletion uses platform-specific implementations via conditional imports.
• iOS/Android: Closes database and deletes tracker.sqlite file.
• Web: Closes database and deletes IndexedDB tracker_database.
• Hive preferences box cleared separately if full reset needed.
• App calls main() to reinitialize after deletion.

Backend API Endpoints

• POST /api/auth/register — Create account with email/password.
• POST /api/auth/login — Authenticate and receive JWT.
• POST /api/auth/google — OAuth login with Google.
• GET/POST /api/sync/{collection} — Fetch/push encrypted collection data.
• POST /api/membership/delete_synced_data — Delete all server-side data.

Development Setup

• Flutter SDK 3.8+ required for app development.
• Run flutter pub get to install dependencies.
• Generate Drift code: dart run build_runner build.
• Backend requires Python 3.11+, FastAPI, and PostgreSQL.
• Docker Compose available for full-stack local development.