Native Android client for Cosmonaut AI, an AI-powered interactive storytelling platform.
Cosmonaut is split across several public repositories:
cosmonaut-web: SvelteKit frontend.cosmonaut-api: Backend API and workers.cosmonaut-infra: Terraform infrastructure.cosmonaut-android: Native Android client.
- Kotlin and Jetpack Compose
- Single-activity architecture with Navigation Compose
- Hilt for dependency injection
- Retrofit and kotlinx.serialization for API calls
- AWS Amplify Cognito authentication
- Store5 planning for cache/source-of-truth patterns
- Sentry crash reporting and PostHog product analytics
Prerequisites:
- Android Studio
- Android SDK at
~/Library/Android/sdk - Java 17. For local Gradle commands on this machine, use the Android Studio bundled JDK:
export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"Build the dev APK:
./gradlew app:assembleDevDebugThe dev flavor uses application id com.cosmonaut.app.dev and points at the development Cosmonaut API.
Run the current local verification workflow before merging Android code changes:
export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"
./gradlew app:lintDevDebug app:assembleDevDebugFor UI changes, install and inspect the app on an emulator or device:
adb install -r app/build/outputs/apk/dev/debug/app-dev-debug.apk
adb shell am force-stop com.cosmonaut.app.dev
adb shell am start -n com.cosmonaut.app.dev/com.cosmonaut.app.MainActivityRelease builds read signing configuration from environment variables or GitHub Actions secrets:
SIGNING_KEYSIGNING_KEY_ALIASSIGNING_KEY_PASSWORDSIGNING_STORE_PASSWORDSIGNING_STORE_FILESENTRY_AUTH_TOKENSENTRY_ORGSENTRY_PROJECTPOSTHOG_API_KEYPOSTHOG_HOST
Do not commit keystores, local signing files, generated APKs, generated AABs, or verification screenshots.
Cognito IDs, Cognito domains, Sentry DSNs, and PostHog project tokens in the app build config are client-visible public configuration, not server-side secrets. Runtime signing material and Sentry upload tokens must stay in GitHub Actions secrets or local environment variables.
Start with docs/README.md. The most useful references are:
docs/planning/00-master-plan.md: Android roadmap and feature sequencing.docs/planning/01-web-app-feature-catalog.md: web feature reference for Android parity.docs/planning/02-android-technology-stack.md: technology choices and implementation notes.docs/play-store-listing.md: Play Store copy and data-safety notes.docs/assetlinks-setup.md: Android App Links setup.
GitHub Actions builds dev APKs from develop and production release artifacts from main. Artifact upload is disabled when the repository is public.
See SECURITY.md for disclosure and secret-handling guidance.
Issues and pull requests are welcome. Include emulator/device verification for UI behavior changes and keep generated build outputs out of commits.
Apache-2.0. See LICENSE.