flower-focus
[READ-ONLY] Mirror of https://github.com/DogPawHat/flower-focus.
Star
Fork
Watch
21 1 0
Files
.agents
.claude
app
assets
docs
scripts
src
.gitignore
AGENTS.md
app.json
CONTEXT.md
IDEA.md
LICENSE
package-lock.json
package.json
README.md
skills-lock.json
tsconfig.json
README.md

Flower Focus #

A personal focus experience built around growing flowers and collecting them in a garden (Android-first, developed through Expo Go).

What the app is #

  • Focus: pick an activity (defaults: Drawing under Creativity, 25 minutes), optionally note what you are working on, and start growing a flower through seed, sprout, bud, and bloom stages.
  • Garden: every completed session is saved as exactly one equally sized flower; the total shows completed focus time only.

Timing is persisted: completion is decided from a stored finish timestamp, so locking the phone, backgrounding, or restarting the app never pauses or loses a session.

Project structure #

  • app/ — Expo Router file routes. app/_layout.tsx wires SQLite, the application provider, and the bloom-reveal overlay; app/(tabs)/ holds the Focus and Garden routes.
  • src/flowerFocus/ — the cohesive application boundary (FlowerFocusApp), the persistence interface with SQLite and in-memory implementations, and the React provider.
  • src/screens/, src/artwork/, src/theme.ts — presentational screens, SVG flower artwork, and the cream/green/pink palette.

Track current work in Flower Focus on Linear. The tracker instructions define the workflow; the migration crosswalk maps legacy tickets to Linear.

See docs/adr/0001-navigation-with-expo-router.md for the navigation decision.

Development setup: USB device + shared view #

The OnePlus 6T (USB) is the development and debugging device; the Tailscale server stays up so other people can open the app themselves.

  • Dev/debug device (6T, USB): npm run android:usb — runs Metro on port 8082, bound to localhost, and forwards the phone's port with adb reverse. Screenshots and UI interaction for verification go through adb on this device.
  • Shared view (anyone on the tailnet): npm run start:tailscale — runs Metro on port 8081, advertising the machine's Tailscale IP (currently dogpawbot = 100.118.180.119). Viewers open in Expo Go: exp://100.118.180.119:8081 (check the printed URL if the IP changes). Keep this server running; it is the standing way to show the app.

Each phone has its own local database in Expo Go — viewers start with the seeded defaults, not the dev device's garden.

Development #

  • npm start — Expo dev server (scan the QR code with Expo Go; same Wi-Fi, or npx expo start --tunnel).
  • npm run start:tailscale — shared view over Tailscale (port 8081, see above).
  • npm test — vitest integration tests through the application boundary (controlled clock).
  • npm run typecheck — strict TypeScript check.
  • npm run android:usb — USB workflow on port 8082 for the dev device (below).
  • npx expo-doctor — project compatibility checks.

A dev: finish now affordance appears on the running session in development builds only: it rewinds the persisted finish timestamp so the normal completion path runs immediately.

Expo Android USB development #

Run on your phone #

  1. Enable Android Developer options (tap Build number seven times in Settings), then enable USB debugging.
  2. Connect a data-capable USB cable and unlock the phone. Accept Allow USB debugging for this computer.
  3. Run npm run android:usb from this directory. Expo CLI can install the matching Expo Go Android app on first launch. After editing route files under app/, reload fully in Expo Go (reopen the link or press r in the CLI); Fast Refresh keeps up with component edits.

The command forwards phone port 8081 to this computer using adb reverse, starts Metro on localhost, and opens Expo Go. The phone and computer do not need to share Wi-Fi. Initial dependency and Expo Go downloads need internet access. Re-run the command after reconnecting the cable. Stop with Ctrl+C.

Android platform-tools are installed at ~/Android/Sdk/platform-tools. The launcher discovers them automatically, or uses ANDROID_HOME / ANDROID_SDK_ROOT if set. A full Android SDK and Java are not required for this Expo Go workflow.

Checks and troubleshooting #

  • npm run typecheck checks TypeScript.
  • npx expo-doctor checks project compatibility.
  • ~/Android/Sdk/platform-tools/adb devices -l lists connected phones.
  • unauthorized: unlock the phone and accept the debugging prompt.
  • After installing or removing packages, restart the dev server with --clear; a server started before an install may fail to bundle new entry points (for example Expo Router's EXPO_ROUTER_APP_ROOT).
  • Expo Go Fast Refresh can log transient Access to closed resource warnings from the old SQLite handle after edits; a full reload clears them. This is development-only.
  • Empty device list: check the cable, USB debugging, and USB connection mode; try File Transfer.
  • no permissions: on Debian, run sudo apt install android-sdk-platform-tools-common, then reconnect the phone. This installs Linux USB permission rules and requires your administrator password.
  • Multiple devices: run ANDROID_SERIAL=your-phone-serial npm run android:usb.
  • Port 8082 occupied: stop the previous Metro server before running the USB command (the Tailscale share uses 8081, so both can run together).
  • Expo Go version mismatch: install the Android version matching the project's Expo SDK from https://expo.dev/go.

Expo Go supports its bundled native libraries. Apps requiring additional native modules will need a development build and additional Android build tooling or EAS Build.

References: Expo setup · Android USB debugging.