Quick Start

PrerequisitesCopy Anchor Link

• Bun 1.4.0 (pinned — an older Bun silently ignores the lockfile)
• Node.js 22.13+ on the 22 line, 24.3+ on the 24 line, or 26+. Node 20, 23, 24.0 to 24.2, and 25 fall outside the engine ranges of Expo SDK 58 and React Native 0.88. apps/mobile/.nvmrc and the shared CI setup action use 22, the same major the EAS build images run. Node 24.12 works locally.
• JDK 17 with JAVA_HOME set, for local Android builds and the Maestro CLI
• Xcode on macOS for local iOS builds. EAS builds iOS with Xcode 26.6 on the pinned macos-tahoe-26.5-xcode-26.6 image (see Releases).
• A Convex account with access to the tipeer:theraw project

Install and verifyCopy Anchor Link

bun install            # one install for all workspaces, from the repo root
bun run check-all      # lint + type-check all three packages
bun run test           # all three test suites

check-all is the gate for any change. If you only touched one package, you can run its slice: bun run check:mobile, check:dashboard, or check:backend.

Run each packageCopy Anchor Link

# Backend — ONLY from packages/backend. Nothing else may run convex dev.
cd packages/backend && bun run dev

# Dashboard — serves on port 3000
cd apps/dashboard && bun run dev

# Mobile — Expo dev server (requires a dev client build, not Expo Go)
cd apps/mobile && bun run start

Dashboard gotchaCopy Anchor Link

Access the dashboard at http://localhost:3000, never 127.0.0.1:3000. On the 127.0.0.1 origin the Better Auth session query never resolves and the sign-in form stays disabled. Local dev points at the staging Convex deployment (or a personal dev deployment via .env.local overrides) — production data is never touched by local runs.

Backend gotchaCopy Anchor Link

convex dev pushes to your logged-in Convex deployment. Make sure packages/backend/.env.local selects the dev deployment (dev:agreeable-canary-738) before running it. Never run it with a production deployment selected.

Branch and commitCopy Anchor Link

Work lands on develop. Maintainers may push there directly; everyone else branches and opens a PR into develop. develop reaches main through a develop → main PR. Commits touching apps/mobile must follow conventional-commit style, which commitlint enforces. Pre-commit hooks run gitleaks and lint-staged, plus the full check-all for mobile. See Conventions for what CI runs on each branch.