Analytics System

Status: Implemented Crates: crates/application/src/analytics/, crates/infrastructure/supabase/src/analytics/

---

Overview

The Analytics System is a queue-based, offline-first pipeline for tracking pseudonymous usage events. Events are enqueued locally and flushed to the analytics backend when network connectivity is available. The system contains no PII — only pseudonymous identifiers and behavioral event types.

Users can opt out via the analytics_enabled setting. When disabled, no events are enqueued or flushed.

---

Three Distinct Concerns

The analytics system is one of three identity-adjacent concerns that must never be conflated:

Concern	What It Is	Storage
Identity	Offline-permanent local user profile	IdentityStore (local)
Auth	Remote service tokens / JWT	AuthRepository (Supabase)
Analytics	Pseudonymous offline-first event queue	Analytics queue (local + flush)

Each has a separate lifecycle and storage mechanism. Analytics uses the user’s pseudonymous identity, not their auth token or real identity.

---

Diagram

---

Use Cases

Three use cases in crates/application/src/analytics/:

Use Case	Description
EnqueueAnalyticsEventUseCase	Add an event to the local queue. No-op when analytics is disabled.
FlushAnalyticsQueueUseCase	Send pending events to the analytics backend. Called when online.
PendingAnalyticsCountUseCase	Return the count of undelivered events in the local queue.

---

Event Queue Schema

Events are stored locally until flushed:

CREATE TABLE analytics_queue (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    event_type TEXT NOT NULL,        -- Pseudonymous event name
    properties TEXT,                 -- JSON: non-PII event properties
    user_id TEXT,                    -- Pseudonymous identifier (not auth UUID)
    created_at TEXT NOT NULL
        DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now'))
);

---

Integration with WriteEffectCoordinator

Analytics events are triggered as a fire-and-forget side effect via WriteEffectCoordinator. After a mutation use case completes, the coordinator dispatches a bounded set of side effects — embedding queue, event log, sync queue, and analytics. Analytics enqueue is non-blocking and does not affect the outcome of the originating mutation.

---

Opt-Out

The analytics_enabled user setting (default: true) gates all analytics activity. When set to false:

• EnqueueAnalyticsEventUseCase returns Ok(()) immediately without writing to the queue
• FlushAnalyticsQueueUseCase skips without sending
• No existing queue entries are deleted (they age out naturally)

---

Related

• Write-Effect Coordinator — Dispatches analytics as a side effect
• Auth System — Separate concern (remote tokens, not analytics)
• User Settings System — analytics_enabled setting
• crates/application/src/analytics/ — Use case implementations
• crates/infrastructure/supabase/src/analytics/ — Flush transport implementation