Guide for coding agents (and humans) working on Pulse Mobile: an Android app (Expo) where every byte lives on the phone. It reads the owner's Fitbit data from Health Connect, keeps it in SQLite, and turns it into recovery, strain, sleep, Pulse Age, stress, Energy Bank and journal insights. There is no server, no account and no Google sign-in: one install is one person. The one exception to "nothing leaves the phone" is error telemetry: coded error reports to Sentry with no health data, on by default and off in Settings (docs/telemetry.md).
The engine (Health Connect source, storage, scoring, view models) comes from halo, a fork of the same pulse app, at ~/personal/halo. halo is the reference for engine code: read it beside every change to src/health, src/data, src/core, src/pipeline and src/queries, and do things the way it does. The UI is Pulse's own and keeps the look of the pulse PWA. The move and its phases are in docs/rewrite-plan.md.
Expo ships breaking changes every SDK release. APIs you remember are likely renamed, moved, or removed. Before writing any code that touches an Expo, EAS, or React Native API:
- Read the major version of the
expopackage inpackage.json(SDK 57 today, React Native 0.86). - Fetch the matching versioned docs:
https://docs.expo.dev/versions/v<major>.0.0/ - For anything else, fetch https://docs.expo.dev/llms.txt, an index of all Expo docs with corrections to common LLM misconceptions. Follow its links to the specific page you need. Never answer from memory.
| Command | What it does |
|---|---|
pnpm install |
Install dependencies |
pnpm start |
Dev server (expo start) |
pnpm android |
expo run:android: build and run a development build on an emulator or a device (needs Android Studio) |
pnpm typecheck |
tsc --noEmit |
pnpm lint |
ESLint |
pnpm test |
Vitest in Node (src/**/*.test.ts, scripts/**/*.test.ts) |
npx expo install <pkg> |
Add a dependency. Always use this instead of pnpm add for anything native: it picks the version that matches the SDK |
npx expo install --fix |
Fix package versions that do not match the SDK |
npx expo-doctor |
Diagnose dependency and config issues |
npx expo export --platform android --output-dir <tmp dir> |
Bundle check: Metro builds the Android bundle. Use a directory outside the repo and delete it after |
npx eas-cli@latest build --profile development |
Cloud development build (profiles in eas.json: development, preview, production) |
Run pnpm typecheck && pnpm lint && pnpm test before every commit. Run the bundle check when you change babel.config.js, metro.config.js, app.json, or add a dependency.
app/ Expo Router routes: one file per screen, _layout.tsx files are navigators. Routes live in the root app/, not in src/.
src/
health/ Health Connect: permissions, record → row mapping, sync, data check (halo)
data/ the Store interface, the async expo-sqlite store, the in-memory store for tests, the demo seed (halo)
core/ pure TypeScript: engine/ (the Pulse engine, from the reference study: every score the screens show), scoring and algorithms (halo's, kept for the extras listed in docs/engine-plan.md Phase 7)
pipeline/ stage 1 and stage 2: imported rows to stored scores (halo)
queries/ view models (halo), plus Pulse-only extras the screens need (trendView, homeExtras, mobileExtras, journalExtras, shell)
lib/ time, yield (time slicing), format, bands, reasons, url and the UI catalogues
state/ app.ts: boot, status, the sync run, the data version, the query and action contexts
background/ runSync.ts (the shared sync + scoring run) and lock.ts; the background task comes later
actions/ writes: journal, log, dashboard, profile, preferences, export, calendar
screens/ the screens, built from src/ui; useScreen.ts is the view-model cache
ui/ tokens, shells, kit, charts
dev/ development screens (kit); the routes in app/dev/ load them in development builds only
plugins/ config plugins (withHighRefreshRate)
scripts/ release tooling
docs/ rewrite-plan.md, plan.md, design/spec.md, learning.md, onboarding.md, runbooks
- Health Connect only, Android only. No Google sign-in, no network source, no iOS config. The app reads Health Connect and writes exactly one thing back: the exercise session of a workout recorded in Pulse (
WRITE_EXERCISE,saveExerciseinsrc/health/connect.ts), so it reaches Google Health and returns through the import like any other workout. It writes no other type. - No auth. No accounts, no login screen, no user ids.
- Owner's own name and photo are fine. The rule against storing a Google account's email, name or picture is about Google accounts. A display name and photo the owner types or picks (Settings › Profile) stay in the profile, the photo as a file in the app's document directory; neither leaves the phone.
- Only
src/datatouches SQLite. Everything else goes through theStoreinterface (src/data/store.ts). Tests use the in-memory store (src/data/memory.ts). - No I/O in
src/core. Pure TypeScript only: no database, no network, no clock reads, no React. - The reference study is the reference for
src/core/engine. The Pulse engine's kernels follow the study at~/personal/pulse/docs/research/bevel/(start atpulse-gaps.md), with the fixes indocs/engine-plan.md. Code, comments, copy, commits and docs call it the Pulse engine and never name the app the study describes; comments cite it as "reference study,<doc>.md§<section>". - halo is the reference elsewhere. Engine code outside
src/core/engine(src/health,src/data,src/pipeline,src/queries, the oldsrc/core/scoringandsrc/core/algorithms) follows halo. Copy its code and its way of doing things; it is the same pulse code under the same license and copyright owner. Pulse-only additions live in their own files (the*Extras.tsqueries) so the copies stay comparable. - No secrets in logs. Never log health-record bodies or keys. Secrets (the coach key, later) live only in
expo-secure-store. - Telemetry carries codes, never data. Report failures through
src/lib/telemetry.ts(report,reportError) with a stable dotted code and tags that are enums or small counts: a record type, an HTTP status, a reason code. Never a health value, a URL, a key, a model id or free text. Add each new code todocs/telemetry.md. Slow steps gettraced(name, tags, fn)and a few codedlog()lines per run, under the same rules. Breadcrumbs and HTTP spans stay off, and the scrubbers stay allowlists. - Honest states. Every nullable metric is
{ value, reason, provisional }, using the reason codes insrc/lib/reasons.ts. Never show a fabricated number. Where a source has no data for a card, hide the card or show its reason; never invent a value. - Scales. Strain is a percent: 0 to 100 on most days, up to about 129; rings fill at 100 and labels show the real value. Recovery is 1 to 100, Stress and the Sleep Score 0 to 100, Energy Bank 1 to 100. Halo's Effort (0 to 100) still feeds halo's extras only. Recovery's
sleepPerfis on [0, 1]. - Causality. A day's scores depend only on that day and earlier days. Baselines fold from earlier nights only. Never let a later night change history.
- Scoring version. A change to what the pipeline stores bumps
SCORING_VERSION(src/pipeline/types.ts), which rescores the history. A change to the import mapping bumpsIMPORT_VERSION(src/health/sync.ts), which re-imports the history window. - Long loops yield. The import and the pipeline await
slice()(src/lib/yield.ts) in long loops so taps and frames get through. - UI. The look is the pulse PWA's. Build from the shells and kit in
src/ui, using NativeWind classes and the tokens. Spec decisions and deviations live indocs/design/spec.md. A screen that needs a changed view-model field adapts its code, not its look. - Copy. User-facing text goes through i18n keys (docs/i18n.md); no literal copy in components. It says Pulse, Pulse Age and Health Connect. Where the reference study and WHOOP (noop,
~/personal/noop) name the same feature differently, the screens use WHOOP's name: Sleep Performance (the study's Sleep Score), Sleep Debt (Sleep Bank), Sleep Need (Sleep Needed), Strain Target (Target Strain), Training Load (Cardio Load), Stress Monitor (Stress). Biological Age is Pulse Age; Energy Bank keeps its name (WHOOP has none). - Shared files. The
Storeinterface, the UI tokens and the kit's exports change only in the orchestrating session, between waves. A stream that needs a change asks for it in its report. - No native edits.
android/is generated (Continuous Native Generation) and git-ignored. Never create or edit it by hand. Configure native behavior inapp.jsonand config plugins. - Development builds. Health Connect is a native module, so the app needs a development build (
pnpm androidornpx eas-cli@latest build --profile development), not Expo Go. - Prefer Expo modules over third-party libraries. Docs: https://docs.expo.dev/versions/latest/index.md
- Use the
gitCLI only, nevergh. - Commit as
adityaongit, email74150665+adityaongit@users.noreply.github.com. Checkgit config user.emailbefore committing. - Conventional commit messages, signed off (
git commit -s). - Once typecheck, lint, test and the bundle check pass and the change has been tried on the phone, fast-forward
origin/main. Never force-push.
- Vitest runs in Node. Store, pipeline, health and query tests run on the in-memory store (
MemoryStore), most over halo's 180-day demo seed (seedDemo) scored byrunPipeline. - Algorithms get golden-value or property tests beside the file. Queries and actions get tests on the in-memory store.
- No local e2e and no device automation. The owner checks on a phone. CI is the gate.
- Explanations, runbooks and guides are markdown in
docs/. Use mermaid flowcharts for flows and architecture. - Keep
docs/learning.mdcurrent: when you make an Expo or React Native choice, add one short section. docs/onboarding.mddescribes the first run;docs/rewrite-plan.mdthe move to Health Connect and halo's engine.