Technical Documentation

Detailed technical information about Tracker's architecture, data models, and implementation.

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.

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.