KUAN 館

KUAN is an Android workout tracker for people who lift and also train a martial art. Gym sessions, runs, bag rounds and form practice share one log, a progression engine writes the next session's prescription from your history, and a "hall" tracks traditional forms move by move. The look is ink and paper: an OLED-black page, bone-white type, vermillion seals and brush-calligraphy hanzi.

Features

• Today. The active plan's workout for the day, plus one-tap logging for a run or a martial-arts session, and a streak lantern that forgives the odd rest day.
• Gym sessions. Drag-to-adjust weight and reps dials, last session's sets as pills, planned rest with a timer, supersets, per-side holds, per-exercise kg or lb stacks (storage is always kg), and spoken set notes through the phone's own speech recogniser.
• Progression engine. Estimated 1RM (Epley) trends, double progression for hypertrophy work, strength and power schemes, plateau waves, deloads after repeated stalls, and a plain-language reason for every prescription.
• Plans and templates. Weekly or multi-week plans that paint the calendar, reusable workout templates, and an exercise library with roles and muscle groups.
• Runs. Distance, duration and pace, with weekly volume.
• The Hall. Forms as data (Chen Yi Lu, Yang 37, Wing Chun, Xiao Hong Quan, Taegeuk, qigong sets, sun salutations), a move-name wheel for logging how far you got, boxing, Muay Thai and taekwondo combo libraries, and a round timer that calls combos aloud.
• The 36 Chambers. A three-year sample path of twelve seasons with three filmable feats each; measurable feats show progress against the season's clock.
• History. Calendar, day detail, exercise records and charts, muscle balance, goals.
• Your data stays on the phone. Raw SQLite, full-database export and import, optional automatic backups to a folder you choose, and an optional folder ingest that reads exercise, combo, form, workout and schedule definitions written as JSON. The database is excluded from Android cloud backup.

Build and run

Requirements: JDK 17 and the Android SDK (platform 34). Gradle 8.7 is fetched by the wrapper.

export ANDROID_HOME=/path/to/android-sdk   # or put sdk.dir in local.properties
./gradlew assembleDebug                     # -> app/build/outputs/apk/debug/Kuan-R<versionCode>.apk
./gradlew testDebugUnitTest                 # JVM unit tests: engine, parsing, plans, chambers
adb install -r app/build/outputs/apk/debug/Kuan-R*.apk

scripts/build-debug-apk.sh, scripts/run-tests.sh and scripts/install-debug-apk.sh wrap the same commands. A fresh install starts with an empty log, the exercise and combo libraries, the forms catalogue and a sample week (Upper A, Bag & Forms, Lower A, Easy Run, Upper B, Kicks & Conditioning).

The fonts are committed already subset. scripts/fetch-fonts.sh re-downloads the three OFL typefaces from Google Fonts and subsets the CJK faces to the glyphs the app uses; scripts/gen-icon.py carves the 館 launcher glyph into an adaptive vector icon. Both need Python with fontTools (and Pillow for the icon).

Tech stack

• Kotlin 1.9, Jetpack Compose (BOM 2024.09) with Material 3, single activity, no navigation library: one KuanViewModel, a tab enum and an overlay back stack.
• Raw SQLiteOpenHelper with idempotent, additive migrations; WAL journaling.
• AGP 8.5, compile and target SDK 34, min SDK 26.
• Platform TextToSpeech for combo call-outs and SpeechRecognizer for set notes; an AGSL paper-grain shader with a fallback for older devices.
• Fraunces and Ma Shan Zheng, subset (SIL Open Font License; licences in app/src/main/assets/licenses/); the launcher glyph is traced from Noto Serif SC (also OFL).

app/src/main/java/com/greggaynor/kuan/
├── MainActivity · KuanApp (shell, dock, overlays) · KuanViewModel · KuanNav
├── data/      domain, repository (SQLite), formatting, parsing, martial arts, 36 Chambers
├── engine/    WorkoutProgression (e1RM, plateau waves, deloads, goal test days)
├── platform/  TextToSpeech, haptics, voice notes
├── design/    ink theme, typography, paper grain, motion, components, charts
└── ui/        Today, Session, Calendar, Day detail, Scroll, Goals, Hall, Round timer, Library, Plans, Settings

Licence

MIT, see LICENSE. The bundled fonts keep their own SIL Open Font License.