Split expenses. See the whole picture. Keep control of your data.
A privacy-first Android expense-sharing app backed by private GitHub repositories.
No BranchBalance server, no opaque database, and no mystery export process.
Download the Android APK · Product & docs · Interactive mockups
- Your group owns the data. Every group is a private GitHub repository containing readable JSON and its Git history.
- There is no app backend. The Android app talks directly to GitHub for identity, membership, storage, and sharing.
- The maths is exact. Amounts use integer minor units, shares are deterministic, and settlement suggestions are calculated on-device.
- It goes beyond “who owes whom.” Track budgets, category limits, spending pace, payment methods, funding fairness, and confirmed settlements.
- Concurrent changes are explicit. Expense and settlement writes use GitHub blob SHAs so a stale device cannot silently overwrite newer data.
| Group overview | Spending intelligence | Balances & fairness |
|---|---|---|
![]() |
![]() |
![]() |
These screens are rendered from the repository's interactive HTML mockups, which cover all 12 primary product flows in light and dark themes.
- Connect GitHub through the GitHub App device flow. Rotating credentials stay in secure storage on the phone.
- Create a group. BranchBalance creates a private
branch-balance-<slug>repository under your personal account. - Invite collaborators. GitHub's collaborator list remains the source of truth for group membership.
- Track and settle. Members add expenses, understand spending, and record payments completed outside the app.
BranchBalance records transfers; it does not move money or connect to financial accounts.
| Area | Included in v1.1 |
|---|---|
| 🔑 Authentication | GitHub App device flow, expiring tokens, atomic refresh-token rotation, secure sign-out |
| 👥 Groups | Private repository creation, discovery, collaborator invitations, accepted and pending members |
| 🧾 Expenses | Add, edit, and delete; equal, full-to-one, and Just me splits; categories and payment methods |
| 📊 Spending | Group and category budgets, optional trip dates, daily guidance, pace and mix analytics, combined filters |
| ⚖️ Balances | Exact per-member balances, simplified debts, paid-versus-share analysis, pending and confirmed settlements |
| 🔔 Activity | Foreground-only, on-device inbox for newly observed group changes |
| 🔄 Sync | Refresh on focus, foreground, and pull-to-refresh; cached snapshots remain visible on transient failures |
| 🌓 Experience | System, light, and dark themes; accessible labels, text summaries, and touch targets |
flowchart LR
App[Android app] <-->|GitHub REST API + OAuth| Repo[(Private GitHub repository)]
App --> Secure[SecureStore<br>access + refresh tokens]
App --> Cache[AsyncStorage<br>disposable snapshots]
Repo --> Files[group.json<br>expenses/*.json<br>settlements.json]
GitHub is authoritative. Local storage is limited to credentials and a stale-while-revalidate cache; BranchBalance never presents a cached write as remotely committed.
The app is built with Expo SDK 57, React Native, TypeScript, Expo Router, Octokit, Zod, SecureStore, and AsyncStorage. See the architecture guide for dependency boundaries, schemas, and concurrency decisions.
Download the signed APK and its SHA-256 checksum from the latest GitHub release. Android is the supported runtime; iOS is not currently a release target.
Requirements:
- Node.js 20 or newer
- npm 10 or newer
- Expo Go on an Android device, or an Android emulator
- A GitHub App configured for BranchBalance
git clone https://github.com/BrunoV21/BranchBalance.git
cd BranchBalance
npm ci
cp .env.example .envCreate a GitHub App under GitHub Settings → Developer settings → GitHub Apps, then:
- Enable Device Flow.
- Grant repository Contents and Administration read/write permissions.
- Keep expiring user authorization tokens enabled.
- Allow the installation to cover all repositories so newly created groups are accessible.
- Set
EXPO_PUBLIC_GITHUB_CLIENT_IDandEXPO_PUBLIC_GITHUB_APP_SLUGin.env.
The client ID and slug are public metadata. Never add a GitHub client secret to the app. The GitHub App setup guide explains the installation and authorization flow.
Start Expo:
npm startFor an Android device or emulator on the same network:
npm run androidIf Expo Go reports java.io.IOException: Failed to download remote update, treat it as a device-to-Metro connection problem first. With USB debugging enabled:
adb devices
adb reverse tcp:8081 tcp:8081
npx expo start --localhost --androidRecreate the reverse mapping after reconnecting the cable or device. API errors that appear after the JavaScript bundle loads are separate application-level failures.
npm run validateThe full validation command runs TypeScript, ESLint, the Jest suite, and Expo Doctor. Individual commands are also available:
npm run typecheck
npm run lint
npm test -- --runInBand
npm run doctorTests cover domain money rules, schemas, GitHub/OAuth transport, storage, providers, reconciliation, and screen behaviour. See the testing guide for automated and physical-device acceptance.
npm ci
CI=1 npx expo prebuild --platform android --no-install
node scripts/configure-android-release-signing.mjs
(cd android && NODE_ENV=production ./gradlew :app:assembleRelease)The signing configurator reads ANDROID_KEYSTORE_PATH, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS, and ANDROID_KEY_PASSWORD. The APK is written to android/app/build/outputs/apk/release/app-release.apk. Local release builds require the Android SDK, NDK, and Java 17.
Tagged versions are validated, signed, checksummed, and staged through GitHub Actions. Read the release process before creating a version tag.
Each group repository has a deliberately small structure:
branch-balance-road-trip/
├── group.json
├── settlements.json # created with the first recorded payment
└── expenses/
├── <uuid>.json
└── <uuid>.json
- Group, expense, plan, and settlement data lives in the private repository.
- GitHub collaborators with repository access can read that shared data.
- Access and refresh tokens live in
expo-secure-store. - Non-secret local snapshots are disposable; GitHub remains the source of truth.
- Settlement notes are redacted from persistent device caches, but remain visible to repository members and may remain in Git history.
- Private GitHub repositories are access-controlled by GitHub; BranchBalance does not add end-to-end encryption.
Read how data ownership works, the permissions model, and the credential security guide.
| Resource | What it covers |
|---|---|
| Product website & documentation | Published guides, data ownership, releases, and product overview |
| Product requirements | Implemented scope, product decisions, and acceptance criteria |
| Architecture | System boundaries, models, sync, security, and UI decisions |
| Testing | Automated validation and physical-device scenarios |
| Roadmap | Known limitations and possible future work |
| Interactive mockups | Twelve responsive screens plus the original website prototype |
Current boundaries include Android-only releases, always-online writes, foreground refresh rather than push notifications, and a GitHub App limitation that can hide pending private-repository invitations before acceptance. Receipt images, percentage splits, currency conversion, and organization-owned groups are not yet included.
Issues and pull requests are welcome. Please run npm run validate before submitting code and keep product behaviour aligned with the PRD and architecture guide.
BranchBalance is open-source software available under the MIT License.


