ADR-0039: First-Run Analytics Policy

Context

• LocusFlow is a privacy-first app with zero telemetry, no network stack (ADR-0005), and fully on-device data processing.
• The onboarding flow (ADR-0034) is a critical first-run experience whose effectiveness determines user retention. Understanding whether users complete it, skip it, or abandon it mid-flow is valuable for improving the product.
• Traditional analytics (Firebase Analytics, Mixpanel, etc.) transmit data to external servers, which conflicts with LocusFlow's privacy principles.
• The user has indicated that analytics are acceptable provided they respect strong privacy constraints. A dedicated analytics ADR covering the app-wide analytics framework is planned for a future phase.
• The onboarding flow is ~10 screens with tiered skippability (ADR-0034). The completion state is tracked as a single boolean (ADR-0037) which does not distinguish between completion and skip.

Constraints:

• No network: analytics data cannot be transmitted off-device (ADR-0005).
• Privacy by design: no personal data in analytics, no behavioral profiling.
• Pre-release: the primary analytics consumer is the developer during testing, not a data team.
• The app-wide analytics framework does not yet exist; this ADR should not build one prematurely.

Decision

We will defer the implementation of first-run analytics to a future app-wide analytics ADR. The onboarding architecture is designed to be analytics-ready without implementing analytics infrastructure now.

1. No Analytics Infrastructure in Phase 7

Phase 7 will not introduce:

• An analytics event bus or logging framework.
• Local event storage (Room table, file-based logs).
• Any analytics SDK or dependency.

2. Analytics-Ready Architecture

The onboarding architecture supports future analytics integration through natural observation points:

When the app-wide analytics ADR is written, it can define event types for these observation points. The OnboardingViewModel can then emit events to whatever analytics sink is chosen, with no structural changes to the onboarding flow.

3. Interim Debugging: Logcat Only

During pre-release testing, developers can observe onboarding behavior through:

• Logcat statements in debug builds (standard Log.d calls in OnboardingViewModel).
• DataStore inspection via Android Studio's App Inspection tool (check flag values).
• Manual tester feedback (qualitative reports on onboarding experience).

These mechanisms require no analytics infrastructure and are sufficient for pre-release iteration.

4. Future Analytics Framework — Guiding Principles

When the app-wide analytics ADR is created, it should adhere to these principles (established here as design intent, not as binding decisions):

• Fully local. Analytics data is stored on-device only, never transmitted.
• Aggregated, not granular. Track completion rates and funnel steps, not per-user behavioral sequences.
• Opt-in or at minimum transparent. The user should know that usage data is being collected, even if it never leaves the device.
• Minimal. Only collect what is needed to answer specific product questions. No "log everything" approach.
• Exportable. If the user requests their data (export feature, ADR-0029), local analytics data should be included or at least acknowledged.

These principles are suggestions for the future ADR author, not binding commitments of this ADR.

Rationale

• Deferral over premature implementation. Building an analytics framework for a ~6-screen onboarding flow in a pre-release app is over-engineering. The existing DataStore flags and Logcat provide sufficient observability for the current testing phase.
• Analytics-ready design costs nothing. The observation points listed above are natural consequences of the onboarding architecture (ADR-0034, ADR-0037). No code changes are needed to make them analytics-friendly — they just need an event emitter added later.
• Privacy alignment. Deferring analytics to a dedicated ADR ensures the analytics framework receives the rigorous privacy analysis it deserves, rather than being bolted on as an afterthought of the onboarding ADR.
• Pre-release pragmatism. With a small number of testers, qualitative feedback (verbal, written) is more valuable than quantitative funnel data. Analytics becomes critical at scale; the app is not at scale yet.

Consequences

• Positive:
  • Zero analytics overhead in Phase 7 — no new dependencies, no new storage, no code.
  • Privacy posture remains clean: zero telemetry, zero local tracking.
  • The future analytics ADR can be designed holistically (covering all features, not just onboarding) with proper privacy analysis.
• Negative:
  • No quantitative data on onboarding completion/skip rates until the analytics ADR is implemented. Mitigated by qualitative tester feedback.
  • If the analytics ADR is delayed significantly, onboarding iteration will rely solely on manual testing observations.
• Follow-up:
  • A future ADR will define the app-wide local analytics framework, including event types, storage, retention, and user-facing transparency.
  • When that ADR is accepted, the onboarding ViewModel should be updated to emit the events documented in §2.

Alternatives Considered

• Local-only analytics now (Room table for events) — rejected. Introduces a new Room table, event types, and retention logic for a use case that is not yet critical. The cost-benefit ratio is poor for pre-release.
• Debug-build-only analytics — considered but unnecessary. Logcat logging achieves the same goal without any persistence layer. If structured debug analytics are needed, they belong in the app-wide analytics ADR.
• SharedPreferences counters (e.g., onboarding_skip_count: Int) — rejected. Fragments analytics data across ad-hoc keys with no schema, no retention policy, and no export path. If analytics are worth doing, they're worth doing properly in a dedicated ADR.

Notes

• Related ADRs: ADR-0034 (onboarding flow), ADR-0037 (completion tracking), ADR-0027 (settings persistence), ADR-0005 (no network stack).
• The guiding principles in §4 are non-binding suggestions. The future analytics ADR may adopt, modify, or reject them based on the app's needs at that time.