SunZones/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build Commands

Requires Java 17 — the system default may be Java 25 which Gradle 8.11.1 doesn't support:

export JAVA_HOME="/opt/homebrew/Cellar/openjdk@17/17.0.18/libexec/openjdk.jdk/Contents/Home"
./gradlew assembleDebug

Clean build:

./gradlew clean assembleDebug

Android SDK is at ~/Library/Android/sdk (set in local.properties).

Architecture

Clean MVVM with Hilt DI. Single-activity Compose app — no navigation library, just one screen with a modal bottom sheet.

Data flow:

Room DB (Flow) → LocationDao → LocationRepository → GetLocationsUseCase
  → maps each LocationEntity through CalculateSunTimesUseCase → SunLocation
    → MainViewModel (StateFlow<MainUiState>) → Compose (collectAsState)

Layer responsibilities:

• data/local/ — Room entity, DAO, database. LocationEntity stores lat/lng, timezone ID string, display order
• data/repository/ — Thin wrapper over DAO, adds replaceCurrentLocation (delete old + insert)
• domain/usecase/ — CalculateSunTimesUseCase uses commons-suncalc library to compute sunrise/sunset/progress for a given entity and its stored timezone. GetLocationsUseCase maps the Room Flow through calculations
• domain/model/ — SunLocation is the UI-ready model with computed fields (dayLengthFormatted, sunProgress 0–1, isDaytime)
• ui/main/ — MainViewModel collects locations flow + refreshes every 60s. MainScreen is a HorizontalPager of SunCard composables with a FAB
• ui/addlocation/ — AddLocationViewModel handles Geocoder search and GPS via FusedLocationProviderClient. Timezone is resolved using android.icu.util.TimeZone.getAvailableIDs(countryCode) from the Geocoder's Address
• di/AppModule.kt — Provides Room DB, DAO, Geocoder, FusedLocationProviderClient as Hilt singletons

Key design decisions:

• Timezone stored per location as IANA string (e.g. "Asia/Tokyo"). Resolved at save time via Android ICU + Geocoder country code (NOT timezonemap library — that crashes on Android due to missing zstd-jni native libs)
• Sun progress (0–1 float) calculated against the location's local time, not device time
• SunCard gradient background changes by time-of-day bucket (sunrise/morning/midday/afternoon/sunset/twilight/night)
• Long-press on card to delete (avoids gesture conflict with HorizontalPager swipe)

Key Dependencies

• org.shredzone.commons:commons-suncalc:3.11 — sunrise/sunset/sun position calculations
• com.google.android.gms:play-services-location — FusedLocationProviderClient for GPS
• Android Geocoder — forward search (city name → lat/lng) and reverse geocode (lat/lng → city name + country code)
• android.icu.util.TimeZone — built-in Android API for country code → timezone ID lookup (no extra dependency)

i18n

English default in res/values/strings.xml, Polish translations in res/values-pl/strings.xml. All user-visible strings use stringResource(R.string.*).