FloraLock
An app blocker that teaches you botany instead of just saying "no".
You choose the apps that eat your time and how many plants you want to learn a day. Each day's lesson shows
each new plant once (photos, name, a fact), then a short multiple-choice exam. When you open a locked app,
FloraLock shows a photo of one of your plants with four names to choose from.
- Correct: the app unlocks for your chosen window (default 10 minutes).
- Wrong (the Genius Penalty): the screen freezes for 10 seconds and shows the right name plus a fact, then
asks about a different plant, so tapping at random doesn't pay off.
- Escape hatches, so people don't uninstall: "I don't need Instagram right now" (the best outcome), plus a few
emergency unlocks per day (configurable, default 2).
Everything runs offline; nothing leaves the phone (privacy policy).
Status
| Piece | State |
|---|
| First-launch setup: plants per day, apps to lock, the lock | ✅ Built |
| Daily lesson + exam, spaced reviews, lock-screen quiz | ✅ Built and unit-tested |
| Look-alikes, field clues, streaks and milestones | ✅ Built and unit-tested |
| Evening reminder when the lesson isn’t done (can be off) | ✅ Built (expo-notifications), timing unit-tested |
| Plant browser and plant pages (about, edibility, uses, lore) | ✅ All 70 plants |
| Photos | ✅ 3 real iNaturalist photos per plant, CC0 / CC BY / CC BY-SA, bundled |
| Android app lock (UsageStats + foreground service) | ✅ Passes the emulator test on Android 8, 10, 13 and 15; needs real phones |
| Play Store signing and privacy policy | ✅ Ready; see docs/PLAY_STORE.md |
| FloraLock Plus (one-time or monthly, Google Play Billing) | ✅ Built; floralock_plus and floralock_plus_monthly must be created in Play |
| iOS shield (Screen Time API) | ⏳ Not started. See docs/PLATFORM_INTEGRATION.md |
Learning model
Pure rules in src/core/, covered by npm test:
- Lesson (
daily.ts): each day brings the next n plants you haven't learned (1–20, set in setup or
Settings). Each is shown once on a study card (photos, how to recognise it, edibility, and the plants it's
mistaken for), then the exam asks one question per plant.
- Spaced reviews (
daily.ts): a plant comes back 1 day after its lesson, then 3, 7, 14 and 30 days after each
right answer. A miss, in an exam or on the lock screen, starts it over from tomorrow. After the fifth review
it's mastered. A day's exam asks at most 15 reviews, the most overdue first.
- Lock screen: asks about today's exam plants first (those not yet answered right today), then anything
you've learned.
- Look-alikes (
quiz.ts, LOOKALIKE_PAIRS in src/data/plants.ts): wrong choices are a plant's real
look-alikes first (peony, rose, ranunculus…), then the same group. A wrong pick of a look-alike shows how to
tell the two apart.
- Progress (
progress.ts, stats.ts): a streak of days with the exam done; collected and mastered counts;
milestones; and Botany IQ from 60 to 160 (a fifth for meeting a plant, the rest grows with each review).
Run it
npm install
npx expo start # press a / i / w for Android, iOS or web
npm test # core logic tests (vitest)
npm run typecheck
The lock is native code (modules/app-blocker), so it doesn't run in Expo Go. On iOS and the web the lock
isn't available; Preview the lock screen on the Today tab shows the challenge instead.
Android builds
Every push to main or a claude/** branch runs .github/workflows/main.yml on
GitHub Actions:
- build: typecheck and tests, then a signed, R8-optimized AAB for the Play Store (
floralock-aab) and an
APK for the emulator tests.
- lock-test: installs the APK on Android 8, 10, 13 and 15 emulators and runs e2e/lock.yaml:
setup, locking the Settings app, the challenge appearing over it, an emergency unlock, the daily lesson and
the Plus screen. Then it reinstalls the app over itself, as an update does, and checks that the lock
restarts on its own and the user's progress is kept (e2e/update.yaml). When all pass,
the APK is deleted, so the run's only download is the AAB.
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
