TapLearn

An Android vocabulary learning app for Vietnamese learners of English. Look up any word you encounter in any app via a floating bubble, then reinforce it with spaced-repetition flashcards and a virtual pet that grows as you learn.

Highlights

• Floating dictionary bubble — select text in any app, get instant definitions, IPA, examples, and Vietnamese translations via the Free Dictionary API
• Spaced repetition — 5-level mastery system with intervals of 1 / 3 / 7 / 14 / 30 days
• Virtual pet (12 Chinese zodiac animals) — earn coins per word learned, unlock pets, equip accessories
• Scheduled review reminders — daily evening quiz, weekend intensive mode
• AI shortcuts — one-tap deep links into ChatGPT and Gemini for richer explanations
• Offline-first — Room database, JSON export/import for backup
• Freemium — Google Play Billing integration for one-time premium unlock

See FEATURES.md for the full feature list.

Tech stack

Layer	Choice
Language	Kotlin
Min SDK	26 (Android 8.0)
Target SDK	34
JDK	17
Persistence	Room
Networking	Retrofit + OkHttp
Async	Coroutines
UI	Material Design 3, ViewBinding
Billing	Google Play Billing 6.x
Build	Gradle (Kotlin DSL)

Build

# Debug APK
./gradlew assembleDebug

# Release APK (unsigned)
./gradlew assembleRelease

# Run unit tests
./gradlew test

Output: app/build/outputs/apk/{debug,release}/.

Signed release build

The release build is automatically signed when keystore credentials are present as environment variables; otherwise it produces an unsigned APK. Required env vars:

Variable	Purpose
KEYSTORE_PATH	Absolute path to .keystore file
KEYSTORE_PASSWORD	Keystore password
KEY_ALIAS	Key alias inside the keystore
KEY_PASSWORD	Key password

CI signs via the matching GitHub Actions secrets (KEYSTORE_BASE64, KEYSTORE_PASSWORD, KEY_ALIAS, KEY_PASSWORD).

Project layout

app/                    Android app module
  src/main/java/        Kotlin source (com.scrolllearning.app)
  src/main/assets/      Shipped word packs (Longman 9000, Van Helsing S1, bonus)
  src/test/java/        JVM unit tests
assets/word_packs/      Source word-pack JSON (pre-enrichment)
scripts/                Python helpers: word extraction, level classification,
                        Longman enrichment, Van Helsing word extraction
wordpack-builder/       Python pipeline: subtitle → transcript → vocab pack
.github/workflows/      CI: test + APK build

Word-pack pipeline

Word packs shipped in app/src/main/assets/ are pre-generated. To rebuild from source:

# Build word packs from a subtitle/transcript corpus
python wordpack-builder/extract_subtitles.py
python wordpack-builder/make_word_pack.py
python wordpack-builder/build_bonus_asset.py

# Enrich the Longman 9000 pack with definitions / examples
python scripts/enrich_longman.py

Source subtitle files are not included in the repository for copyright reasons. Provide your own.

Permissions

The app requests:

• SYSTEM_ALERT_WINDOW — floating bubble overlay
• POST_NOTIFICATIONS — review reminders
• RECEIVE_BOOT_COMPLETED — reschedule alarms after device boot
• BILLING — premium upgrade (Google Play Billing)
• INTERNET — dictionary API lookups

License

MIT — see LICENSE.