Skip to content

README.md

Latest commit

 

History

History
230 lines (164 loc) · 7.7 KB

README.md

File metadata and controls

230 lines (164 loc) · 7.7 KB

Smoke Analytics

Integration Android Release Web Release Quality Gate Coverage Bugs Code Smells Security Rating

Smoke Analytics is a Kotlin Multiplatform smoking journal focused on one thing: making patterns visible without turning the product into noise.

The current 0.12.0 product is organized around four core destinations:

  • The Pulse: today, the last cigarette, pace, goals, and short status cues
  • Analytics & Map: smoking frequency and geographic clustering from one destination
  • The Archive: list and calendar views for the detailed smoking log
  • You: account, preferences, goals, and product actions in one place

Platforms

  • apps/mobile: Android app, the visual source of truth for the product
  • apps/web: Compose for Web version aligned to the same product model
  • apps/wear: Wear OS surface for quick status and lightweight interaction

Current Product Surface

The Pulse

  • time since last cigarette and last-smoked clock time
  • today count, current pace, weekly and monthly averages
  • active goal state and progress
  • quick access into the main smoking flow

Analytics & Map

  • smoking frequency trends
  • period switching
  • map clusters for repeated smoking areas
  • location-disabled, no-data, loading, and error states

The Archive

  • day-based log review
  • list and calendar modes
  • add, edit, and delete entries
  • date navigation and archive scanning

You

  • authentication state
  • goals
  • personal preferences such as custom day start, price, and pack size
  • product actions such as share, support, and bug reporting

Repository Structure

The repository is organized as a Kotlin Multiplatform product, not as a single Android app with extras bolted on later.

apps/
  mobile/     Android application shell
  web/        Compose Web application shell
  wear/       Wear OS app / tile surface

features/
  authentication/
  goals/
  history/
  home/
  settings/
  stats/

libraries/
  architecture/
  authentication/
  design/
  logging/
  preferences/
  smokes/
  wear/

docs/
  releases/
  discovery/

Each feature or library follows the same general split when needed:

  • domain: shared business logic and contracts
  • data: implementation details and platform integration
  • presentation: UI, view state, stores, process holders, and navigation

Tech Baseline

  • Kotlin 2.2.20
  • Jetpack Compose / Compose Multiplatform
  • Android Gradle Plugin 8.13.2
  • Java 17 toolchain
  • Hilt
  • Firebase
  • Kotlin Coroutines / Flow
  • Compose for Web

Local Setup

Requirements

  • Java 17
  • Android Studio with Android SDK installed
  • Node.js available for web deploy tooling

Android / shared app configuration

Local Android and product-specific keys live in local.properties. Typical entries include:

  • google.auth.server.client.id for production
  • google.auth.server.client.id.staging for staging
  • google.maps.android.api.key.staging
  • google.maps.android.api.key.production

The mobile Firebase configs used by the current repo live at:

  • apps/mobile/src/staging/google-services.json
  • apps/mobile/src/production/google-services.json

Build And Run

Mobile

./gradlew :apps:mobile:assembleStagingDebug

Web

./gradlew :apps:web:jsBrowserDevelopmentWebpack

Wear

./gradlew :apps:wear:assembleDebug

If you want to install the Wear build on a connected Wear OS device or emulator:

adb install -r apps/wear/build/outputs/apk/debug/apps-wear-debug.apk

Verification Defaults

These are the repository-default validation paths used for most product work:

  • Web work: ./gradlew :apps:web:jsBrowserDevelopmentWebpack
  • Mobile work: the closest feature compile/test path plus an app-level mobile build when the shell changes materially
  • Release or CI work: validate the nearest real workflow/build path, not only a lightweight compile

Branch And Release Flow

The repository uses:

master <- develop <- feature branch

Rules:

  • start new work from develop
  • open feature PRs into develop
  • merge develop into master only for a release
  • deploy Android and web from master
  • bump develop to the next version only after the release is merged and deployed

Current product version:

  • product.version=0.12.0

CI And Automation

GitHub Actions drive the main repository automation:

  • integration.yml: validation on PRs
  • deployment_playstore.yml: Android release path
  • deploy-web-hosting.yml: production web deploy path

Wear OS Play setup is documented in docs/play-store-wear-os.md.

Release notes are expected in GitHub Releases, not as a growing set of historical markdown files in the repo.

Contributor Notes

  • mobile is the visual source of truth unless a task explicitly needs platform divergence
  • prefer shared domain logic and shared presentation models over platform-specific duplication
  • keep issue state and project board state aligned
  • do not widen product scope inside maintenance tickets

Companion docs:

Screenshots

The old screenshots previously referenced by this README were removed because they no longer represented the current product. The next README asset pass should add refreshed captures from the current 0.12 app surfaces instead of reusing pre-revamp images.

Support

License

Copyright 2025 feragusper

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.