Split the bill, settle up, move on. An expense-splitting app for people everywhere: unlimited free ledger, link-based guest joining, multi-currency from the first expense, deep-link settlement with partial and per-expense payments (UPI in India, PayPal / PayID and more worldwide), and AI receipt itemization that is free within a monthly scan quota (metered beyond it, since each scan has a real API cost — see ADR-008).
Built for a global audience. India is the first launch market — so the settlement rails, receipt scripts and pricing lead there — but nothing in the ledger, currency handling or growth loop is India-only. Every amount is stored in ISO-4217 minor units from M0, and opening a new market is a settlement rail and a price tier, not a rewrite.
This project is tested with BrowserStack.
The two binding specs live in this repo: waves-adr.md (14
accepted architecture decisions) and waves-tdr.md (how to
build them, milestone by milestone). The ADRs are constraints, not
suggestions — if code and ADR disagree, the ADR wins.
Current state, as of 2026-09-08. TDR §10 carries the evidence for each line; this is the summary.
| Milestone | State |
|---|---|
| M0 Foundations | Complete |
| M1 Core ledger | Complete, verified against the live project |
| M2 Offline sync | Built — SQLite mirror, mutation queue, /sync, draft autosave |
| M3 Growth loop | Complete. 56 live checks across three harnesses, all against the deployed project |
| M4 UPI + notifications | Not complete, and the shortfall is bigger than the ✓ suggests — see below |
| M5 AI receipts + export | Complete. All four parts of the criterion have a proof behind them |
M4 is still the largest incomplete block, but the shortfall has halved since this line was first written. The settle/confirm state machine, the 7-day auto-confirm, trip nudges, disputes, the push fan-out and the email half are all built and tested against a real database. Of the two things that had never reached anybody, one now has:
- Mail leaves the building.
wavs.co.inwas verified in Resend on 2026-09-07 and auth mail is live — the sign-in code, the sign-up confirmation and an address change go out as GoTrue SMTP through the same Resend account, from the five templates insupabase/templates/, and a send was watched through todelivered. Product mail — the notifications the app raises itself — has its secrets set and its cron behind it, and no first delivery is recorded here. The two halves are configured in completely different places and neither reaches the other: see "Turning on email". - No push has ever reached a device. Android's half of the credentials was
finished on 2026-08-09 — Firebase project
baaki-43455, its service account key uploaded to EAS, and that key proved live against FCM v1 rather than assumed to be. iOS still has no APNs key at all. And no build has yet been made that containsgoogle-services.json, so no phone has been able to ask for a token, which is what reaching a device would take.push_tokensis empty in consequence, which is also why the fan-out's clean runs prove nothing about delivery.
account-delete is no longer outstanding: the erasure RPC runs as the caller and
the edge function beside it removes the auth.users row with the service key
(TDR A22).
apps/mobile/ Expo (SDK 57, React 19, Expo Router, TypeScript strict)
apps/web/ The app in a browser, and the guest invite view (Next)
apps/admin/ The operator console (Next)
apps/api/ The public developer API — tokens, OAuth 2.1, /v1 (Next + Hono)
apps/docs/ Docusaurus help + API reference — help.wavs.co.in
apps/agent-mcp/ An MCP server that acts as a signed-in Waves user
packages/core/ Pure money/split/balance/simplify/settlement logic — no deps
packages/api-client/ The framework-free client the browser and the API share
packages/db/ Prisma schema + migrations (RLS, triggers, derived balances)
packages/ui/ Design tokens and components
supabase/ Local stack config + edge functions (M2+)
website/ The marketing site
e2e/ Maestro flows
apps/api is the newest of these and the only one a stranger's program can
reach. It holds no service-role key: a token resolves to a person, the API signs
a one-minute session for them, and every read and write goes through the RLS
policies and edge functions the phone already uses. docs/developer-api.md is
the design; apps/api/openapi.yaml is the contract.
packages/core has zero runtime dependencies on React or Supabase. That is
deliberate: the app, the web client and the Deno edge functions all import
the same module, so three runtimes can never disagree about what someone owes.
pnpm install
# money engine: 927 tests across 59 files, the money ones property-based
pnpm test:core
# database: throwaway Postgres, migrations, RLS + invariant tests
pnpm db:pg:up
cp .env.example packages/db/.env # defaults already point at the container
pnpm db:migrate
pnpm test:dbRequires Node 24+, pnpm 11+, and Docker.
The front door, spl 8000 it (TDR A55): welcome · sign in · sign up · phone code · verify email · language · guest welcome. Then the five destinations — Home · Activity · Friends · Me (the private personal ledger, biometrically gated, A56) · Account — with a raised mic between them that opens voice quick-add (A41).
Group (expenses / balances / activity) · Expense detail with its version history, comment thread and image audit · Add or edit expense · Split by item · Spending and the month drill · Settle up · Who pays whom · Pending settlements · Members · Member detail · Person profile across every shared group · Group settings · Invite and its QR · Join from a link · Scan a code · Capture (an expense with no group yet) and the captures inbox · Trip plan, places and recap · twenty-five settings screens, of which export, import, notifications, lock, tags, packs, archived groups, devices, image storage, backup, discovery and blocked people are the ones most often looked for.
TDR §9 is the authoritative list and says which amendment each
screen arrived under. The notification Inbox was removed (#565) — the
notifications table stayed, because it is the delivery queue and not a screen.
They run under pg_cron, take their clock as an argument so they can be tested
without waiting a week, and are idempotent — notifications.dedupe_key is what
makes a retried run a no-op rather than a second buzz.
| Job | What it resolves |
|---|---|
waves_auto_confirm_settlements() |
A settlement nobody answered for 7 days (ADR-007). A dispute still reopens it. |
waves_claim_push_notifications() |
Hands unsent inbox rows to the fanout. An UPDATE, not a SELECT — two overlapping runs cannot both send the same reminder. |
waves_trip_nudges() |
Twice a day during a group's dates: at breakfast about yesterday, at the end of the day about today. Skips anybody who already recorded that day, and asks in the group's timezone rather than the server's. |
waves_enqueue_weekly_digest() |
Monday 03:30 UTC (09:00 Asia/Kolkata). One row per account with activity in the last seven days, and none for the rest (TDR A63). |
waves_auto_archive_stale_groups() |
Archives a group nothing has touched in eighteen months. A tombstone it is not — archiving is reversible from Settings (TDR A35). |
waves_storage_expire_pending() |
Releases a storage reservation an upload never committed, so the free-tier cap frees itself with no R2 credential involved (TDR A44). |
Only one of these schedules itself. 20260907090000_device_alert_and_weekly_digest
registers waves-weekly-digest from inside the migration, and guards it on
pg_cron being installed so a bare CI Postgres still applies. Every other
schedule — including the five-minute notify-fanout call that is the delivery
path for all of the above — is a cron.schedule run against the project by hand,
because it needs a URL and a Vault secret that are properties of a deployment and
not of the schema. docs/notify-fanout-scheduling.md is the recipe, and it exists
because the fanout was once deployed with no cron behind it: a pipeline that
passes every test and delivers nothing.
| Function | What it owns |
|---|---|
sync |
Batch mutation replay and the change feed (TDR §4) |
expense-write |
Recomputes every share with @waves/core and writes the expense atomically |
invite-mint |
Signed, expiring, revocable invite links (only a hash is stored) |
invite-accept |
Preview without an account, join, and asking to claim a ghost |
receipt-parse |
Vision-model itemization, metered against the monthly quota |
fx-rate |
One upstream rate, cached, never an open proxy |
export-data |
Lossless JSON and CSV export |
notify-fanout |
Claims unsent inbox rows, pushes them via Expo and mails the few that merit it |
email-events |
Resend's delivery reports, signature-checked; bounces and complaints suppress |
email-unsubscribe |
One click, no account, signed address (RFC 8058) |
otp-send |
GoTrue's Send SMS Hook: the sign-in code, carried over WhatsApp (TDR A61) |
r2-sign |
The client's only door to object storage — presigned PUT/GET, never a key |
storage-sweep |
Reclaims R2 bytes nothing points at, and expires abandoned reservations |
storage-recount |
Re-reads an object's true size after the image worker transcoded it |
account-delete |
The half of erasure a database role cannot do — removes the auth.users row |
contact-unlink |
Takes a phone or email off an account — not within 7 days, never the last one |
campaign-broadcast |
Mails a campaign to its cohort, holdout excluded (TDR A21) |
Eighteen in all; supabase/functions/ is the list, and the table names the ones a
reader needs to place.
email-events, email-unsubscribe and otp-send are the three functions that do
not verify a Supabase JWT, because none of their callers can hold one — Resend has
no account, a mail client pressing "unsubscribe" has no session, and otp-send is
called by GoTrue itself before anybody has signed in. All three are named in
supabase/config.toml; what stands in for the JWT is a signature — Svix over the
webhook body, an HMAC over the address, and standardwebhooks over the hook's exact
body bytes.
Four of them answer only to the service role rather than to any signed-in caller:
notify-fanout, campaign-broadcast, storage-sweep and storage-recount. The
rest take a rate limit before doing the expensive or revealing part of
their work. The allowances live in supabase/functions/_shared/rateLimit.ts and
are counted in Postgres, because Supabase discards edge isolates between
requests and a counter held in one limits nothing. invite-accept is the reason
the file exists: its preview answers before anybody signs in, which makes it an
oracle for guessing invite tokens, and it is the one bucket keyed on the client
address rather than on a profile.
The app talks to Supabase, so it needs the local stack rather than the bare Postgres container above:
pnpm supabase:start # Postgres + Auth + PostgREST + Realtime + Edge runtime
pnpm db:migrate # point DIRECT_URL at the stack's db port first (54322)
pnpm edge:build # bundles @waves/core for the Deno runtime
pnpm edge:serve # serves supabase/functions locally
# apps/mobile/.env — take the values printed by `supabase start`
# EXPO_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
# EXPO_PUBLIC_SUPABASE_ANON_KEY=<anon key>
pnpm mobilesupabase start pulls ~10 container images the first time; on a slow or
proxied network that can take a while. To work against a hosted project
instead, point packages/db/.env at it and deploy the functions with
pnpm edge:deploy.
These talk to a real Supabase project and are the reason M1 is called done:
ANON_KEY=... SERVICE_KEY=... node e2e/m1-acceptance.mjs # 26 checks
ANON_KEY=... SERVICE_KEY=... node e2e/m3-invites.mjs # 20 checksThese are the product promise, so they are tests, and CI blocks a merge if any of them break:
| Invariant | Where |
|---|---|
| Σ shares === expense total, for every split type | packages/core/test/split.property.test.ts |
| Σ balances === 0, per group per currency | packages/core/test/balances.property.test.ts |
| Simplification never changes anyone's net position | packages/core/test/simplify.property.test.ts |
| FX conversions are exactly reproducible | packages/core/test/money.test.ts |
| Stored balances === the ground-truth aggregate | packages/db/test/invariants.test.ts |
| Non-members can read nothing; guests only their group | packages/db/test/rls.test.ts |
| Expense history cannot be rewritten or hard-deleted | packages/db/test/invariants.test.ts |
| Only a group member can create, delete or settle in it | packages/db/test/m1-rpcs.test.ts |
| Only the payee can confirm a settlement | packages/db/test/m1-rpcs.test.ts |
| Replaying a mutation id never double-posts | packages/db/test/m1-rpcs.test.ts |
| A crash report carries no ledger | apps/web/test/reporting.test.ts |
The client also recomputes each group's balances with @waves/core and compares
them against the server's group_balances. If they ever disagree, the group
screen says so rather than showing a number that might be wrong.
Sentry, on all three surfaces — the app, the web client and the edge functions. TDR §11 asks for crash-free sessions above 99.5%, and a 500 from an edge function is otherwise a line in a log nobody reads.
Everything reported goes through scrub in
packages/core/src/observability/scrub.ts first. One policy, shared by all
three, because a crash report from an expense splitter would otherwise carry
who ate with whom, the number they were invited on, and the handle they pay
from. What survives is the diagnosis: amounts, ids, stack frames, and the
platform it happened on.
It has a limit and the limit is written down: the scrubber catches shapes (emails, numbers, UPI handles, tokens) and known fields. A bare name under a key nobody anticipated matches nothing. So the rule for anything that reports an error is attach ids, never rows.
Nothing is reported unless a DSN is set, so a clone with no Sentry account builds and runs unchanged:
| Variable | Where | What it does |
|---|---|---|
EXPO_PUBLIC_SENTRY_DSN |
apps/mobile/.env |
turns reporting on in the app |
NEXT_PUBLIC_SENTRY_DSN |
apps/web/.env.local |
same, for the web client |
SENTRY_DSN |
edge function env | same, for the functions |
SENTRY_ORG / SENTRY_PROJECT |
build env | adds source-map upload; without them, minified |
SENTRY_AUTH_TOKEN |
build env only | write token — never in a bundle, never committed |
A DSN is public by design: it can only write events, which is why it ships in
the binary. SENTRY_AUTH_TOKEN is the one that reads, and it stays in CI.
The mic beside "What was it for?" is the platform's own recogniser —
SFSpeechRecognizer on iOS, SpeechRecognizer on Android, via
expo-speech-recognition. On-device whenever the phone has a model for the
language, so what somebody says across a restaurant table is not sent anywhere;
where it has none, the OS falls back to the same network recogniser its own
keyboard mic uses.
Three decisions worth knowing:
- It recognises in the language the app is showing, and keeps the phone's
own region when the two agree —
en-GBstaysen-GB, a baretabecomesta-IN.speechLocaleinapps/mobile/src/lib/dictation.ts. - Member names are passed as
contextualStrings. A general model guesses at Indian names and gets them wrong, and the note is where they turn up. - Dictation adds to the field, never replaces it. Interim results arrive in
full each time, so the text is recomputed from what was there when the mic was
tapped rather than appended —
mergeTranscript, and the test that pins it.
Native module, so it needs a new dev build or store build: npx expo prebuild
then eas build. The mic does not render on web, and an existing binary will
not grow it from an over-the-air change.
That last point cost an app launch once. requireNativeModule throws at the
top of the module's own file, and expo-router loads every route file to build
the route tree — so on a binary that predates the module, the throw is not a
missing microphone, it is a red screen at launch naming a screen nobody had
opened. The import therefore lives in DictateVoice.tsx and is reached from
DictateButton.tsx through a require inside a try. Any native module
added from here on wants the same treatment, unless every binary that will
ever run the bundle is guaranteed to contain it.
The camera on the add-expense screen is the platform's document scanner —
VNDocumentCameraViewController on iOS, ML Kit's document scanner on Android,
via react-native-document-scanner-plugin. It finds the page edges and
corrects the perspective, which matters more than it sounds: what follows is
OCR, and OCR reads characters without knowing which ones are on the receipt. A
flat crop of the bill is a different proposition from a photograph of a table.
Capture is one function, captureReceipt in apps/mobile/src/lib/image.ts,
used by both the add-expense screen and Split by item. It falls back to the
plain camera on a build with no scanner, so the screen asking for a receipt
never has to know which one it got.
What a scan does depends on where it was started:
- Add expense takes the grand total and the merchant's name, and leaves the splitting alone. Most bills are split some way that has nothing to do with what each line cost, and dropping somebody into claiming items because they photographed a bill would be worse than letting them type a total.
- Split by item fills the lines, as it always has.
A scan started on one and finished on the other is not re-taken. The parsed
receipt is handed over through the draft store — apps/mobile/src/lib/handover.ts
— keyed per group, consumed once, cleared immediately, and ignored after ten
minutes. A scan costs the group one of its free scans (ADR-011), so asking for
the same bill twice is a real cost; a receipt left lying in the store to
pre-fill somebody's screen days later is a real bug.
Native module, so it needs npx expo prebuild and a new build, and it gets the
lazy-require treatment described above — TurboModuleRegistry.get answers
"is it in this binary" without throwing, and the package is only required once
the answer is yes.
cd apps/mobile
npx expo prebuild --platform android # ios needs macOS; Expo refuses on Windows
cd android && ./gradlew assembleDebug -PreactNativeArchitectures=arm64-v8aNeeds JDK 17, and an Android SDK with platform-tools, platforms;android-36
and build-tools;36.0.0. The APK lands in
android/app/build/outputs/apk/debug/.
Two things in this repo exist only because of pnpm, and both fail in ways that name a file nobody here wrote:
plugins/withShortNativeBuildPath.jsmoves the CMake staging directory toC:\cxx\<module>on Windows. Five dependencies compile C++, and CMake refuses an object path over 250 characters — pnpm's store spends 192 of them before the object is named. What you see is not a path error: ninja regenerates its manifest in a loop and dies withmanifest 'build.ninja' still dirty after 100 tries, ten minutes in, blamingreact-native-screens. Windows long paths do not help; the limit is CMake's.packageExtensionsinpnpm-workspace.yamldeclares@expo/config-pluginsforreact-native-document-scanner-plugin, whose config plugin requires it without depending on it. Always present under npm's flat layout; absent under pnpm's, where the build dies inexpo-constants:createExpoConfig.
The Spending screen (group/[id]/insights) draws two charts over
waves_group_spending(group_id) — what each category cost, and month by month,
for the whole group or for you alone. The function returns the finest grain it
can (member × category × month × currency) and the screen adds up whichever way
it is being asked; summing server-side would answer only one of the two
questions.
Three things it will not do, all of them inherited from the ledger:
- No currency conversion. An expense carries the rate that was used (ADR-003). Multiplying it out for a chart would print a rounded, unreproducible number next to exact ones, so each currency gets its own section.
- No re-dividing. The per-person figures are the shares the ledger stored, odd paisa and all.
- No history. Only the current version of a live expense counts, the same rule the balances use.
The category comes from a guess, not a menu: guessCategory in
packages/core/src/category matches whole tokens against an India-first keyword
table — auto, chai, Swiggy, Zepto, IRCTC, kirana — and the chip it picks can be
changed with one tap. Whole tokens, never substrings: ola is a cab company and
also the middle of "chocolate". The guess stops the moment somebody taps a chip,
and opening an old expense never re-guesses.
The charts are plain views, not victory-native. That library renders through Skia now, which is another native module and another prebuild, to animate a list of bars and a row of columns.
Export is JSON (lossless) or CSV, for one group or all of them, free forever
(ADR-012). The import screen reads three things: a Splitwise CSV, and Waves's own
JSON export, through one RPC — waves_import_ledger, of which
waves_import_splitwise is n
8BD0
ow a thin wrapper.
What comes back from our own file is every balance, to the paisa, in every
currency, settlements included. What does not: ids, edit history, and settlement
allocations. None of the three changes what anybody owes, and the screen says so
in those words before the import runs. packages/db/test/m5-import-export.test.ts
proves the round trip against a real database rather than in the abstract.
The "Me" tab — solo expenses, income, recurring rules, loans, budgets — can be
copied to the person's own Google Drive, WhatsApp-style: back up now, an
Off/Daily/Weekly/Monthly schedule, Wi‑Fi-only or Wi‑Fi-and-data, a "last backup"
line, and a restore for the new phone. apps/mobile/src/app/settings/backup.tsx
is the screen; apps/mobile/src/lib/backup is the machinery and
apps/mobile/src/lib/cloud is the provider seam it sits on.
Three decisions worth knowing:
-
The narrowest scope Google offers.
drive.appdata, notdrive.fileand never fulldrive. The backup lives in the hidden per-application folder: the app cannot see, list or read anything else in the user's Drive, because the token was never issued for it. The file does not appear in their Drive either — Drive's storage settings are where they can see and delete it. -
Two tiers, and the default asks for nothing. The file is sealed with XChaCha20-Poly1305 under a 256-bit key, the same
seal/openthe offline mirror uses. What differs is where that key lives.Standard, the default: the key is minted silently and a copy is written into the same hidden
appDataFolderas the backup, so signing into the same Google account on a new phone finds both and restores with no ceremony. The honest trade, which the screen states plainly rather than dressing up: whoever reaches the Google account can read the backup.Extra protection, opt-in: the key is shown once as 64 hexadecimal characters, lives only in this device's keystore, and is never escrowed, so Waves and Google are both locked out and a lost key is a lost backup. That is what the previous build made everybody do before they could have a backup at all, which is why it is now a choice instead of a toll-gate.
Upgrading re-seals the blob under a key Drive does not hold and only then deletes the escrowed copy. There is no downgrade — the way back is to unlink the account and link it again. The reasoning is in the headers of
apps/mobile/src/lib/backup/tier.tsandrecoveryKey.ts. -
A restore only adds. Records carry client-chosen ids that are already the idempotency key for
personal.upsert, so a restore re-queues what this device is missing and touches nothing it already has — including things it has deleted on purpose. Running it twice does nothing the second time. -
Everything is per-account, on a phone that is not always one person's. The keystore slots for the Drive tokens and the recovery key, the schedule and last-backup preferences, and the remote filename all carry the owner id, and signing out wipes the departing account's set (
clearBackupState, called fromclearLocalPrivateData). The Drive file itself is left alone: it is the user's, and outliving the app's state is the whole point of it. On Extra protection it is unreadable without the key the person kept; on Standard the key is still in their Google account, which is what makes signing in on a new phone enough.
Drive needs its own OAuth clients, which the app does not otherwise have: sign-in goes through Supabase's hosted Google flow and holds no Google client id of its own.
Consent is asked for by Play services, not by a browser tab. Google
withdrew custom URI schemes
for Android clients — any app can claim a scheme and catch the redirect — so
there is no waves:// redirect left to register, and no Android client id to put
in the bundle either: Android apps are identified by their package name and
signing certificate. That is also why a debug-signed build and a release-signed
build need one client each.
In the Google Cloud console, on a project with the Drive API enabled:
- Create an Android OAuth client per signing key, bound to
app.waves.mobileplus that key's SHA-1 (keytool -list -v -keystore ~/.android/debug.keystore -storepass androidfor the debug one). Nothing references its id; registering it is the point. - Create an iOS client bound to the bundle id, if you build for iOS.
- Add
.../auth/drive.appdatato the consent screen. - Set the two ids the SDK does need:
| Variable | Where | What it does |
|---|---|---|
EXPO_PUBLIC_GOOGLE_DRIVE_CLIENT_ID_WEB |
apps/mobile/.env |
names the Cloud project — required on both |
EXPO_PUBLIC_GOOGLE_DRIVE_CLIENT_ID_IOS |
apps/mobile/.env |
the iOS client, and its URL scheme |
These are not secrets — none of these flows has a client secret, which is the whole reason they are usable on a phone — but they name a Google project, so they are read from the environment rather than committed. Both are read at build time, so changing one means rebuilding the app, not restarting it. With neither set the app builds and runs; the backup screen says the destination is unavailable in this build rather than opening a consent page Google would reject.
Play services keeps the grant and issues an access token about an hour long, so there is no refresh token on the phone: a renewal asks it again, silently, for as long as the person leaves the access granted in their Google account.
A drive.appdata app stays in testing until the consent screen is verified;
until then only accounts added as test users can link one.
Everything between the inbox row and the phone is built and tested — the claim, the fan-out, the language, the dead-device revocation. The one part that is not in this repository is the credential that lets a phone have a push token at all, because it is issued by a console and belongs to whoever owns the app.
The path is Waves → Expo → FCM (Android) or APNs (iOS) → the phone. Expo is a relay; the credentials at the far end are still yours to supply.
Android, once:
-
Create a Firebase project and add an Android app to it with the package name
app.waves.mobile. It must match, exactly — a mismatch is the errorMismatchSenderIdon every notification, months later. -
Download
google-services.jsonand put it atapps/mobile/google-services.json. It is gitignored: this repository is public, and the file names the Firebase project builds get pointed at. -
Give the same file to EAS, so cloud builds have it too:
# from apps/mobile. `env:create` still works but is deprecated. eas env:set --name GOOGLE_SERVICES_JSON --type file \ --value ./google-services.json --scope project --visibility secret \ --environment production --environment preview --environment developmentEvery environment, because a preview build that cannot register for push is a preview build that cannot be used to test push.
-
In the Firebase console, under Project settings → Service accounts, generate a new private key, then hand it to Expo — this is what lets Expo's servers send on your behalf:
eas credentials # Android → production → Google Service Account → Push NotificationsThat command is an interactive menu with no flags behind it, so it cannot be scripted. The same upload is available on expo.dev under the project's credentials, and both end up in the same place: the key is stored on Expo's servers, not compiled into anything, and takes effect the moment it lands.
-
Rebuild — for
google-services.json, which is compiled in. An existing build has no idea the Firebase project exists, and no service account key changes that.
apps/mobile/app.config.ts finds the file from the EAS secret or the local copy,
and leaves the key off entirely when there is neither — so a checkout without
a Firebase account still builds and runs. What does not work then is registering
for push, and the notifications screen says so in those words rather than sending
somebody to their phone settings over a problem that is ours.
iOS push does not go through Firebase. Expo talks to APNs directly. What it
needs is an APNs key: a Key with the Apple Push Notifications service enabled,
from the Apple Developer portal, uploaded with eas credentials → iOS → Push
Notifications. The .p8 is downloadable exactly once.
That needs a paid Apple Developer membership. It does not need a Mac — EAS builds in the cloud and the key comes from a web portal; a Mac is only required for local builds and the simulator. Not done either way.
iOS still needs a Firebase file, for a different reason. Phone-number
sign-in is Firebase Auth (apps/mobile/src/lib/firebaseModule.ts), and
@react-native-firebase/app's iOS config plugin throws when
ios.googleServicesFile is unset — "Path to GoogleService-Info.plist is not
defined" — which fails the prebuild before anything is compiled. So iOS does get
an app in the Firebase project, with the bundle id app.wavs.mobile (the iOS
spelling, not Android's app.waves.mobile — see "The two app identifiers").
Download GoogleService-Info.plist, put it at
apps/mobile/GoogleService-Info.plist, which is gitignored like its Android
twin, and give the same file to EAS:
# from apps/mobile
eas env:set --name GOOGLE_SERVICES_INFO_PLIST --type file \
--value ./GoogleService-Info.plist --scope project --visibility secret \
--environment production --environment preview --environment developmentEvery environment, for the same reason as the Android file. app.config.ts
resolves it the same way — the EAS secret, then a local copy, then nothing — but
"nothing" is not survivable on iOS the way it is on Android: a missing
google-services.json only costs push, while a missing plist costs the build
itself, and a build made without it has no phone sign-in.
When it is set up and still silent, read the fanout's reply before suspecting
the phones. It reports problems by Expo's error code, and misconfigured: true
when those codes are MismatchSenderId or InvalidCredentials — the two that
mean the credentials are wrong rather than the devices. Without that, a wrong key
looks exactly like a country with its phones switched off: rows go out, failures
climb, and nothing anywhere names the cause.
The service account key can also be tested on its own, with no phone and no
build: sign a JWT with it, exchange that for an OAuth token against
https://oauth2.googleapis.com/token, and POST to
https://fcm.googleapis.com/v1/projects/<project>/messages:send with
validate_only: true and any nonsense string as the device token. A 400 INVALID_ARGUMENT complaining about the registration token is the answer you
want — it means the key is live, the Firebase Cloud Messaging API is enabled and
the account is allowed to send, and the only thing wrong was the token you made
up. 403 SERVICE_DISABLED and 403 PERMISSION_DENIED name a real problem
instead, and name it now rather than after a build and a device.
Same shape as push: everything between the inbox row and the mailbox is built and tested, and the part that is not in this repository is the part a console issues.
The pipeline is notify-fanout → Resend → email-events. Nothing is sent
without a verified sending domain, and nothing is sent at all while
RESEND_API_KEY or EMAIL_UNSUBSCRIBE_SECRET is unset — the fanout checks for
both before it claims a row, so a half-configured deployment strands nothing.
In the Resend dashboard, once:
- Add the domain
wavs.co.inand publish the SPF, DKIM and DMARC records it gives you. Until it says verified, every send is refused outright — this is not a deliverability problem that shows up as spam, it is a 4xx. - Add a webhook pointing at
https://ywojpnfyxxltvihqmcni.supabase.co/functions/v1/email-events, subscribed toemail.delivered,email.bounced,email.complainedandemail.opened. Copy its signing secret — it startswhsec_.
Then, once:
supabase secrets set RESEND_WEBHOOK_SECRET=whsec_...
supabase secrets set RESEND_API_KEY=re_...
supabase secrets set EMAIL_FROM='Waves <hello@wavs.co.in>' # optional; this is the default
supabase secrets set EMAIL_WEB_URL=https://app.wavs.co.in # optional; this is the default
pnpm edge:deployThat covers product mail — the notifications the app sends itself. Auth
mail (the sign-in code, the sign-up confirmation, an address change) is sent by
GoTrue, which secrets set does not reach. It needs the same key written into
supabase/.env and then pushed:
echo "RESEND_SMTP_PASSWORD=re_..." >> supabase/.env # gitignored
supabase config pushconfig push uploads [auth.email.smtp] and the five templates in
supabase/templates/. Push it before the key is in .env and you get SMTP
enabled with an empty password, which sends nothing at all — read the note above
that block in config.toml.
EMAIL_UNSUBSCRIBE_SECRET is what signs the one-click unsubscribe URL. Changing
it invalidates every unsubscribe link already sitting in somebody's mailbox, so
it is set once and left alone.
EMAIL_WEB_URL is where the button in an email points — defaults to the web
app, https://app.wavs.co.in, because the button lands on a group page that
only that deployment serves. A fork or a self-host pointing at a
different domain (or nothing at all, deliberately) should set this explicitly;
with it unset the button falls back to the waves:// deep link,
which works on a phone and does nothing in desktop webmail. That fallback is
deliberate: an https:// URL that 404s looks like it should have worked.
What can be seen without sending anything: email_status on notifications
tells you what happened to each one — suppressed means we chose not to mail it
(no confirmed address, email turned off, or the address is on the suppression
list), failed means Resend refused it, and NULL after a run means it will be
retried. email_events is the trail, one row per send plus one per report.
Tapping Google or Apple used to send somebody out of the app: Waves asked
Supabase for an /authorize URL, a browser tab opened on <project-ref>.supabase.co,
Supabase bounced it on to the provider, and a redirect came back through
waves://auth. It works, and it is still the fallback — but it shows a domain
that is neither ours nor Google's on the way to somebody's own account.
The native path (apps/mobile/src/lib/nativeIdentity.ts) presents the sheet the
OS already has — Play services on Android, expo-apple-authentication on iOS —
and hands the identity token it issues to signInWithIdToken. Same
mechanism the Drive link uses (lib/cloud/nativeGoogle.ts), asking who you are
instead of for your files.
It applies to a fresh sign-in only. Supabase has no id-token form of
linkIdentity, so a guest upgrading in place (ADR-006, the common path here)
still goes out through the browser. So does every case the sheet cannot serve:
no Play services, no native module in the binary, Apple off iOS, the web app,
and a build with no OAuth client registered for its signature. None of those
surfaces as an error — the browser flow runs and the person signs in.
Google's client ids are the Drive ones, because they are the same ids: Google allows one iOS client per bundle id, and identifies an Android build by its package name and signing certificate rather than by anything in the bundle. Set the neutral names instead if a build offers sign-in but no backup; either works.
| Variable | Where | What it does |
|---|---|---|
EXPO_PUBLIC_GOOGLE_CLIENT_ID_WEB |
apps/mobile/.env |
names the Cloud project; falls back to the Drive one |
EXPO_PUBLIC_GOOGLE_CLIENT_ID_IOS |
apps/mobile/.env |
the iOS client and its URL scheme; same fallback |
What the consoles need. Google, per signing key:
- An Android OAuth client bound to
app.waves.mobileplus that key's SHA-1 — the debug keystore's and the release keystore's are different clients. Nothing reads its id; registering it is the point. Without one Play services refuses withDEVELOPER_ERROR(status 10) before Google ever sees the request, and Waves quietly uses the browser instead. - An iOS client bound to the bundle id, for iOS builds.
- In Supabase → Authentication → Providers → Google, put the Web client id
in Client ID and list every id whose tokens should be accepted under
Authorized Client IDs — the web one (the audience of an Android native
token) and the iOS one. A token whose
audis not listed is rejected, which is the only check standing in for the nonce Google's SDK does not let us set.
Apple needs nothing new: the native iOS path already ran before this change, and its provider config is the section below — including the client-id order, which is load-bearing.
Back, and live since 2026-09-05. This section previously said it had been
removed; that was true for a while and stopped being true when the entitlement,
expo-apple-authentication and the native sheet came back. App Store guideline
4.8 is why it is not optional: an app offering a third-party social login must
offer an equivalent private one, and this app offers Google.
Two audiences share one Supabase provider, and the order they are listed in is load-bearing:
app.wavs.web,app.wavs.mobile
GoTrue accepts every id here as a valid audience when it verifies an identity
token, but it sends only the first to Apple as client_id when it starts a
browser round trip. A bundle id is not a valid web client. Put it first and
Apple answers invalid_request on every Android and web sign-in while native
iOS keeps working — which looks like a platform bug rather than like one field
in the wrong order.
So: the Services ID (app.wavs.web) first, for the browser fallback used on
Android and web; the bundle id (app.wavs.mobile) second, for the iOS
id-token flow.
The secret expires. Apple issues no static one — what Supabase stores is an
ES256 JWT signed with the Sign in with Apple .p8, and six months is the
maximum lifetime Apple accepts. Apple sign-in fails on the day it lapses and
nothing else does. Regenerating it needs the .p8, the Key ID, the Team ID and
the Services ID; the signature must be raw R||S (dsaEncoding: 'ieee-p1363' in
Node), because the DER encoding Node produces by default yields a token Apple
rejects as malformed, which reads like a wrong key.
Testing either provider without a device. Ask the hosted project for an authorize URL and follow it:
curl -s -o /dev/null -w '%{redirect_url}\n' \
"https://<project-ref>.supabase.co/auth/v1/authorize?provider=apple&redirect_to=waves://auth"The Location carries the exact client_id and redirect_uri being sent,
which is what makes a mismatch obvious. Follow it: a working client returns
Apple's full sign-in page, a rejected one a bare shell. The same probe against
provider=google returns a plain Error 400: redirect_uri_mismatch page when
the console is wrong. Both providers were broken in exactly these two ways on
2026-09-05, and this is how it was found.
The app was called baaki before it was called Waves, and the old name is now
gone from the source, the database, the local stack and these docs. What is left
lives in somebody's console rather than in this repository:
- The OAuth redirect. The app asks for
waves://authand registers only thewavesscheme. Addwaves://authto the hosted project's Auth → URL Configuration → Redirect URLs, and to the redirect URIs of the Google OAuth client (and Apple's Services ID, if that ever comes back). Until it is listed, Google sign-in completes at the provider and lands nowhere. - The three hosts. The marketing site keeps the apex,
wavs.co.in; the product moved toapp.wavs.co.inand the console toadmin.wavs.co.in. Point both subdomains at their Vercel projects, and put the console's host inADMIN_ALLOWED_ORIGIN— its CSRF check compares against exactly that name. The app's invite links and the button in every email now resolve againstapp.wavs.co.in, so a join link is dead until that host answers. - The edge functions. They call
waves_*now. A deployed function still calling the old names answers "function does not exist" on every write, so they redeploy with this. - The two app identifiers, which are not the same string. iOS is
app.wavs.mobileand Android isapp.waves.mobile— note the spelling.app.waves.mobilewas already registered under somebody else's Apple developer account, and Apple bundle ids are globally unique, so the iOS half took the product domain's own spelling. Android was left alone: its package is whatgoogle-services.json, the Play listing and everyappId:ine2e/key off, and none of them can see the iOS id. Nothing reads across the two, so the divergence is harmless — but it is the sort of thing a later reader "corrects". Both are right.
The database was rebuilt, not migrated. The whole migration history is one
file — 20260904000000_waves_baseline — that builds the schema already named
waves_*, and the hosted database was dropped and recreated from it on
2026-09-04. There is no upgrade path from a database built by the old files and
no compatibility aliases, by choice. Everything the hosted database held went
with it — 152 accounts, 100 groups, 806 expenses, all of it development data —
and a dump was taken first. The three rows in storage.objects survived: the
Storage API refuses a direct delete, so those bytes are orphaned until they are
removed through it.
The only thing that keeps its old name is the Firebase project
(baaki-43455), because that id was issued by a console and the app is
still registered under it.
An installed app still carries its own device state across the rename. The
device keys and the mirror's SQLite file move on the first launch after the
update (lib/legacyKeys.ts, sync/legacyDatabase.ts), which keeps the
language, theme, app lock and device identity rather than resetting them. The
mirror itself is of a database that no longer holds those rows, so the first
sync after this is a fresh one either way.
The version is compiled into the binary, so a build can only ever describe
itself — it cannot know something newer exists. The policy lives in
public.app_releases, one row per store, and the app asks on launch and on
every foreground.
| Column | Means |
|---|---|
latest_version |
what is published — a dismissible banner |
minimum_version |
the oldest build allowed to open — a hard wall |
store_url |
where the Update button goes |
message |
optional, replaces the default wall copy |
Raising them is one statement, and it takes effect on the next foreground with no app release involved:
-- a new build is out; nothing is wrong with the old one
UPDATE app_releases SET latest_version = '0.2.0' WHERE platform = 'android';
-- 0.1.x may no longer run: it computed something wrongly
UPDATE app_releases
SET minimum_version = '0.2.0',
message = 'Expenses added on the old version split rupees wrongly.'
WHERE platform = 'android';Only the service role can write it; everybody, including signed-out guests, can read it, because the check runs before the sign-in screen.
Three things stop a mistake here from bricking every phone:
- A
CHECKrefuses aminimum_versionabovelatest_version— that row would block every build in existence, including the one the Update button installs. - A
CHECKrefuses a version string the client cannot compare (v2,2.0-rc), which would otherwise silently switch the policy off. - The client fails towards opening: no answer, an unreadable version, or a policy it does not understand all resolve to "carry on". The one exception is a policy it has already fetched, which is cached and honoured offline — "this build computes money wrongly" does not stop being true when the phone loses signal. Every foreground re-checks, so a corrected policy lands as soon as there is a connection.
The comparison itself is compareVersions in packages/core/src/version,
mirrored in SQL by waves_version_key() so the database and the app cannot
disagree about which of two versions is newer.
- Amounts are
BIGINTminor units plus an ISO-4217 code. No float, no decimal, anywhere (ADR-003). - Balances are always derived, never stored as a mutable running total (ADR-004). The Postgres tables are a cache that CI proves equal to the aggregate.
- The remainder of an uneven split rotates by expense id, so the same person does not always absorb the extra paisa (ADR-009).
- Waves never moves money. Settlement opens a UPI intent in the payer's own app and records the outcome (ADR-007).
Manual expense entry, groups, all split types, balances, settlement recording and export are unlimited and free, forever. No daily caps, no ads in a money flow. Convenience is what gets monetized: AI scan volume beyond the free quota, deeper analytics, trip passes, themes. Treat this as a review checklist item.
Copyright © 2026 Madan D.
Waves is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License v3.0 as published by the Free Software Foundation. If you run a modified version as a network service or app, the AGPL requires you to offer its source to your users.