buzz/mobile

Buzz Mobile

Flutter mobile client for Buzz.

Setup

Use the Flutter SDK pinned by the repository. Activate Hermit from the repo root before resolving packages or running any Flutter command:

cd /path/to/buzz
. ./bin/activate-hermit
./bin/just mobile-install

mobile-build-android intentionally builds with --no-pub. If an IDE or an external Flutter SDK has touched mobile/.dart_tool, rerun mobile-install with the pinned SDK before building so flutter_test, sky_engine, and the engine all come from the same Flutter version.

Run

# From repo root (applies a worktree-isolated debug identity and starts/reuses Simulator):
just mobile-dev

# Direct (uses the app's configured community; apply worktree overrides first):
cd mobile && flutter run

Worktree-aware debug identity

Debug builds produced from a git worktree get a unique app identifier keyed to the worktree directory name (com.buzz.buzzMobile.<slug> on iOS, xyz.block.buzz.mobile.<slug> on Android) plus a display-only branch label in the app name (Buzz (my-branch), or a short SHA when the worktree is detached). Because the identifier follows the directory rather than the branch, one worktree keeps exactly one installed app — and its login state — across branch switches, and builds from multiple worktrees install side by side, mirroring the desktop dev experience. Release and profile builds always keep the production identity and name.

just mobile-dev and just mobile-build-android apply this automatically by running scripts/mobile-worktree-overrides.sh, which writes two gitignored files:

• mobile/ios/Flutter/WorktreeOverrides.xcconfig (included by Debug builds only; a developer's AppOverrides.xcconfig is included after it, so app-specific overrides like a personal BUNDLE_IDENTIFIER for device signing always win)
• mobile/android/worktree.properties (read by the debug build type only)

Android developers can keep a stable local test identity that takes precedence over the generated worktree values by creating the gitignored mobile/android/AppOverrides.properties:

appName=Buzz Pairing
applicationIdSuffix=.device_pairing_e2e1

These values are consumed by the debug build type only. The standard just mobile-build-android command can still be used; regenerating worktree.properties does not overwrite AppOverrides.properties. Release and profile builds keep the production Buzz name and application ID.

For direct Xcode / Android Studio / flutter run development, run ./scripts/mobile-worktree-overrides.sh from the repo root once per branch switch to refresh the display label (the install identity never changes); the persisted files are then picked up by any subsequent build. In the main checkout the script is a no-op that removes stale override files, restoring the plain Buzz identity.

For an Android debug build that must remain installed alongside other Buzz worktree builds, set an explicit launcher name and package suffix when invoking the generator or a recipe that invokes it:

BUZZ_ANDROID_DEBUG_APP_NAME="Buzz Huddles" \
BUZZ_ANDROID_DEBUG_ID_SUFFIX=".huddles_829c" \
./bin/just mobile-build-android

This example produces the debug-only package xyz.block.buzz.mobile.huddles_829c with the launcher label Buzz Huddles. The suffix must start with a dot followed by a lowercase letter and may contain only lowercase letters, digits, and underscores. Release and profile builds ignore these overrides and retain the production package and name.

To remove leftover worktree-suffixed installs from booted iOS simulators and connected Android emulators, run just mobile-clean (add --dry-run via ./scripts/mobile-worktree-clean.sh --dry-run to preview). Production installs are never touched.

Checks

dart format --output=none --set-exit-if-changed .
flutter analyze
flutter test

Or from the repo root: just mobile-check and just mobile-test.

Android release signing

Android release builds fail unless all upload-key inputs are supplied through the environment:

• BUZZ_ANDROID_UPLOAD_KEYSTORE_PATH: path to a CI-vended keystore file
• BUZZ_ANDROID_UPLOAD_KEYSTORE_PASSWORD
• BUZZ_ANDROID_UPLOAD_KEY_ALIAS
• BUZZ_ANDROID_UPLOAD_KEY_PASSWORD

The keystore path must be absolute, and the keystore must remain outside the repository. Development and debug builds do not require these variables.

Release pipelines that sign through the central APK Signer service instead of a local upload keystore must set BUZZ_ANDROID_RELEASE_SIGNING=external. That mode produces an unsigned release bundle and refuses to run if any BUZZ_ANDROID_UPLOAD_* value is also set.

Architecture

lib/
├── main.dart              # Entry point, Riverpod bootstrap
├── app.dart               # MaterialApp with theme
├── shared/
│   └── theme/             # Catppuccin light/dark, spacing tokens, extensions
└── features/
    └── home/              # Placeholder home surface

• State management: Riverpod + Hooks (HookConsumerWidget)
• Theme: Catppuccin Latte (light) / Macchiato (dark) — matches desktop
• Spacing: Grid tokens for consistent spacing
• Linting: flutter_lints + riverpod_lint via custom_lint
• Feature isolation: No cross-feature imports except shared/