p24-infra Docs

whatsapp-android-delta-uploader-plan

3 min read

WhatsApp Android Delta Uploader — plan techniczny

Cel

Celem jest aplikacja na Androida, która monitoruje foldery WhatsApp, wykrywa zmiany, buduje paczki delta, wysyła je do Wasabi przez interfejs zgodny z S3, a następnie zapisuje rekord zadania do kolejki w Supabase przez REST API.[cite:46][cite:45][cite:60][cite:72]

Architektura

Aplikacja składa się z czterech głównych modułów:

  • Watcher — monitoruje katalogi przez FileObserver i zapisuje zdarzenia zmian do lokalnej kolejki.[cite:46]
  • Snapshot engine — okresowo wykonuje pełny rescan metadanych plików, aby potwierdzić stan i skorygować ewentualnie pominięte eventy obserwatora.[cite:46][cite:45]
  • Packager — buduje paczkę delta, np. ZIP oraz manifest.json, zawierający listę zmienionych i usuniętych plików.
  • Uploader — wysyła paczkę do bucketu Wasabi i po sukcesie dodaje wpis do kolejki w Supabase przez endpoint REST.[cite:60][cite:72]

Harmonogram pracy

Do uruchamiania zadań w tle należy użyć WorkManager, ponieważ jest to zalecany mechanizm do trwałej pracy w tle na Androidzie.[cite:45] PeriodicWorkRequest wspiera zadania cykliczne, a minimalny interwał dla pracy okresowej wynosi 15 minut, więc interwał godzinny mieści się w tym modelu.[cite:45]

Rekomendowany model działania:

  • FileObserver działa stale i zapisuje zdarzenia do lokalnej bazy.[cite:46]
  • WorkManager co 60 minut uruchamia batch: rescan, delta, ZIP, upload, enqueue job.[cite:45]
  • Po większej liczbie zmian można dodatkowo użyć OneTimeWorkRequest, aby przyspieszyć wysyłkę bez czekania do pełnej godziny.[cite:45]

Format paczki

Każda paczka delta powinna zawierać:

  • manifest.json
  • katalog files/ ze zmienionymi plikami
  • listę usuniętych plików
  • metadane wersji schematu

Przykładowy manifest:

{
  "schema_version": 1,
  "device_id": "android-01",
  "snapshot_id": "2026-06-25T09:00:00Z",
  "previous_snapshot_id": "2026-06-25T08:00:00Z",
  "created_at": "2026-06-25T09:00:08Z",
  "files": [
    {
      "path": "WhatsApp Images/IMG-20260625-WA0001.jpg",
      "size": 248392,
      "mtime": "2026-06-25T08:57:14Z",
      "sha256": "..."
    }
  ],
  "deleted": [
    "Voice Notes/old-note.opus"
  ]
}

Upload do Wasabi

Wasabi udostępnia interfejs zgodny z S3, więc warstwa uploadu powinna działać jak standardowy klient S3. Paczki powinny trafiać do uporządkowanej ścieżki, np.:

delta/YYYY/MM/DD/<snapshot_id>.zip

Po poprawnym uploadzie aplikacja powinna oznaczyć lokalny batch jako uploaded i dopiero wtedy zgłosić zadanie do kolejki.

Kolejka na Supabase

Supabase wystawia Data REST API pod ścieżką /rest/v1/, a insert nowego wiersza do tabeli realizuje się przez POST na endpoint tabeli.[cite:60][cite:72] Dla kolejki rekomendowana jest tabela ingest_queue oraz endpoint:

POST https://<project_ref>.supabase.co/rest/v1/ingest_queue[cite:60][cite:72]

Wymagane nagłówki:

  • apikey: <SUPABASE_KEY>
  • Authorization: Bearer <SUPABASE_KEY>
  • Content-Type: application/json
  • Prefer: return=representation[cite:62][cite:70]

Przykładowe body:

{
  "device_id": "android-01",
  "snapshot_id": "2026-06-25T09:00:00Z",
  "bucket": "whatsapp-archive",
  "object_key": "delta/2026/06/25/2026-06-25T09-00-00Z.zip",
  "status": "uploaded",
  "payload_hash": "sha256:...",
  "source": "android-whatsapp-uploader"
}

Przepływ end-to-end

  1. Android monitoruje foldery WhatsApp przez FileObserver.[cite:46]
  2. WorkManager uruchamia zadanie godzinowe.[cite:45]
  3. Worker wykonuje rescan i wylicza deltę względem poprzedniego snapshotu.
  4. Paczka ZIP trafia do Wasabi.
  5. Po udanym uploadzie aplikacja wykonuje POST do Supabase ingest_queue.[cite:60][cite:72]
  6. Backend lub automatyzacja nasłuchuje kolejki i pobiera obiekt z Wasabi do dalszego przetwarzania.

Klasy aplikacji

Proponowany podział klas w Kotlinie:

  • WhatsAppPathProvider
  • ChangeEventRepository
  • FolderObserverService
  • SnapshotScanner
  • DeltaBuilder
  • ZipPackager
  • WasabiUploader
  • SupabaseQueueClient
  • HourlyIngestWorker
  • UploadRetryWorker

Dane lokalne

Lokalnie warto trzymać lekką bazę Room z tabelami:

  • file_snapshot
  • change_event
  • upload_batch
  • upload_batch_item

To pozwoli bezpiecznie obsłużyć retry, tryb offline i idempotencję uploadów.

Ryzyka

FileObserver nadaje się do monitoringu katalogów, ale nie powinien być jedynym źródłem prawdy; dlatego potrzebny jest okresowy rescan.[cite:46] WorkManager nie gwarantuje uruchomienia dokładnie o wybranej minucie, bo Android stosuje ograniczenia pracy w tle i optymalizacje baterii.[cite:45]

Drugim ryzykiem są ograniczenia dostępu do folderów WhatsApp na nowych wersjach Androida. W praktyce trzeba potwierdzić na docelowym urządzeniu, które ścieżki są rzeczywiście dostępne dla aplikacji.

MVP

Pierwsza wersja powinna obejmować:

  • ręcznie skonfigurowane ścieżki katalogów,
  • monitoring zmian,
  • godzinowy batch przez WorkManager,
  • ZIP delta,
  • upload do Wasabi,
  • insert do ingest_queue w Supabase,[cite:60][cite:72]
  • prosty ekran statusu: ostatni scan, ostatni upload, liczba plików, ostatni błąd.

Kolejny krok

Po MVP warto dodać szyfrowanie paczek, hashowanie plików dla deduplikacji, podpisywanie webhooków oraz dashboard stanu urządzeń.

Graph View