Keisuki Architecture & Telemetry

Comprehensive guide to Keisuki's offline-first architecture, Room SQLite persistence, MVI action flows, and cloud sync protocol.

1. Modern Android Architecture

Keisuki strictly follows official Google Android Architecture Guidelines utilizing unidirectional data flow (UDF) with MVI-inspired UI state handling:

UI Layer: 100% Jetpack Compose with Material 3 Expressive shapes and custom Canvas drawings.
Presentation: ViewModel managing immutable StateFlow<UiState> and handling explicit UiAction intents.
Data Layer: Single source of truth managed by CounterRepository and UserPreferencesRepository (DataStore).

2. Room SQLite Schema

All events and tallies are recorded locally in two primary relational tables:

Table: counters

id: String (PK) • title: String • count: Long • step: Long • colorToken: String • syncStatus: String

Table: counter_events

id: String (PK) • counterId: String • delta: Long • timestamp: Long • syncStatus: String

3. Cloud Sync & Debouncing

To prevent excessive write volume to Google Firebase Firestore, all tap mutations pass through an in-memory 1500ms debounce buffer before triggering remote mutations.

When offline, operations are marked PENDING_SYNC and automatically flushed upon network reconnection via Android WorkManager (SyncWorker).

4. Contributing to Keisuki

We welcome contributions! Please follow the CONTRIBUTING.md guidelines and Conventional Commits specification.