Skip to content

ADR-0058: Onboarding capture setup is optional

  • Status: Accepted
  • Date: 2026-10-17
  • Deciders: maintainers
  • Related: ADR-0008, ADR-0016

Context

Onboarding required the system notification-access grant before Continue unlocked, even though the app can already record a transaction manually from the Activity editor. A user who only wanted manual tracking — or whose device would not grant access — could not finish setup at all, and the empty Home screen offered automatic-capture guidance with no way to add the first entry. Capture access is genuinely optional: every transaction row, total and report works without a bank notification ever arriving.

Decision

Capture setup is optional and never blocks first use.

  • The notification-access step offers Use manual tracking for now, which completes onboarding while access stays off. It records onboarding_complete = true and capture_location = false and writes an empty tracked_packages list, so nothing falsely claims capture is configured. It requests no runtime permission.
  • The consent checkbox stays mandatory; the listener-grant route and the Finish-time POST_NOTIFICATIONS request are unchanged.
  • Empty Home exposes a named Add transaction action that opens the existing manual-transaction editor (Routes.manualTransaction); Save/Back/Cancel behave exactly as the Activity flow.
  • Capture status stays truthful: the Home banner states automatic capture is off and offers Turn on, which opens the system notification-access settings. Later activation happens in Settings → Banks & capture (tick the apps, switch on the permission) and adds captured rows without resetting the manually entered ledger.

Consequences

  • A user can install, consent, and log a first transaction without granting notification access; automatic capture is opt-in.
  • Manual-only installs leave tracked_packages empty, so the capture pipeline consumes nothing until the user configures and grants access later.
  • There is exactly one manual editor; Home's action reuses it rather than adding a second entry point.

Verification

OnboardingViewModelManualTest and ManualOnlyJourneyTest prove manual completion persists without the grant, the first manual row survives a relaunch, later capture activation keeps that ledger and stays deduplicated, and normal onboarding still completes. HomeManualEntryTest proves the empty Home action exists and routes to the editor.

Amendment (2026-10-19): Home capture notice reflects configured capture

Home derives a capture status from the tracked-package setting plus notification access instead of treating every disabled listener as revoked:

  • no tracked packages → MANUAL_ONLY: neutral optional-setup guidance, no warning and no permission request (a manual-only user is not told to fix a listener they never enabled);
  • tracked packages + access granted → ACTIVE: no notice;
  • tracked packages + access denied → REVOKED: the repair warning with Turn on, opening the notification-listener settings.

Tracked-package changes arrive through the observed settings flow and the permission is rechecked on lifecycle resume, so a change in Settings or Android settings refreshes Home without a restart. Capture is never enabled automatically.