HeartBeat
A gamified life tracker for two people. Moods, workouts, cycles and calendars in
one place, on both phones, with nudges that arrive whether the app is open or not.
If you got here from a birthday present: hey babe :). Start below.
Getting it on your phone
It installs like an app but arrives through Safari. Four steps.
1 · Open the app link in Safari. Not Chrome, and not the browser inside
Instagram or Messages — actual Safari. If you couldn't find it yet, it's in the bio section of this repo
iPhone only allows web apps to install from there.
2 · Tap Share, then Add to Home Screen. This step is not cosmetic. iOS
refuses to deliver notifications to a web app unless it has been added to the
Home Screen and opened from that icon.
3 · Open it from the icon and allow notifications. iOS only shows the
permission prompt on a tap inside the installed app. If you decline by accident,
the only way back is to delete the icon and add it again — so say yes.
4 · Tap the invite link. One tap and the two phones are paired. No account,
no password, no phone number. (If this deploy has sign-in switched on, you can
also connect a GitHub or Google account afterwards — purely as a way back in if
the phone is lost. It is never how you get in.)
Android is simpler: Chrome will offer to install it, and notifications work
without the Home Screen step.
What's on it
The home screen is your pet and what today still wants from you, spread over
three panes you swipe between: Today, Us and Adventure. A bar along
the bottom holds the six places you open it for: Home, Quests, Shop,
Partner, Bag and Birb. Everything else is behind the menu button.
| Place | What it holds |
|---|
| Mood | Three sliders, 1–10: hunger, joy, moody. Both of you, side by side. The cycle log is the last section of this page, behind its own PIN if you want one |
| Move | A workout log, and camera proof — front and back — that you did it |
| Work | A shared calendar, filled from a file you export from your own |
| Tasks | Dailies, habits and to-dos, and what you finished |
| Eve's Garden | The islands, the boss, and going in together |
| You | Pairing, the theme picker, your partner's name and photo, calendar |
The pet is the point. It gains XP when either of you logs something, and
levels up on quests that get set from a few questions during setup. Rep ranges,
streaks, achievements worth a big bonus. Neglect it and it sulks.
Themes
Five, switchable any time under Settings: Hello Kitty, SpongeBob, Naruto, The
Last Airbender, My Little Pony. Each is a palette plus a hand-drawn animated
backdrop. Every artwork is original — see NOTICE.md.
Each comes both ways: every theme has a dark palette and a white one, and a
Light / Dark / System control under the picker chooses between them. System is
the default and follows your phone, so it turns over when your phone does. The
backdrops are drawn differently in each — a pale sparkle on a white page is not
a subtle sparkle, it is an invisible one.
Backdrops pause when the app is in the background, respect your phone's
reduced-motion setting, and damp under Calm mode. Palette contrast is
enforced by tests, so a theme cannot ship with text you can't read.
Privacy
Your phone holds the record. The server holds a copy so the other phone can read
it, and that is the whole reason it exists — a shared tracker that shares nothing
is just two separate apps.
Concretely: mood, exercise, cycle and calendar entries are stored on the server,
readable only by the two devices paired to your couple.
Images are stored on the server too. Workout proof and your profile photo
are synced, because a shared tracker whose photographs only one person can see
is not shared. Both are downscaled on the phone before they are sent — proof to
roughly 180 KB, a profile photo to 64 KB — and both are readable only by the two
devices paired to your couple, exactly like every other entry. If you would
rather a photograph stayed on your phone, do not take it in the app.
There are no accounts and no email addresses, and the app itself runs no
analytics: no tracking script, no cookie, no client identifier.
There are two optional third parties, and only if the person deploying it
turns them on. The first is sign-in with GitHub or Google, as a way back in if
you lose your phone.
It is off unless a client ID and secret are configured, and when it is off the
app never contacts either company. Even switched on it is not a login — the
pairing code is still the only way into a couple, and signing in with an account
nobody connected gets you told so and nothing else. Google is asked for openid
alone and GitHub for no scope at all, so what is stored is an opaque account id
and never an address, a name or a photograph.
The second is anonymous product counts, sent by the server rather than by your
phone: which features get used, and which screen a crash happened on. It is a
count or a short label, hashed with a secret salt so it cannot be traced back to
an account. It is never an entry, a message, a name, a photograph, a timezone or
a token, and a test fails if a property that looks like one is added. It is off
unless a key and a salt are configured, and /api/health reports which. See §10
of docs/DEPLOY.md.
Invite links expire after fifteen minutes and work exactly once. A couple is two
people; a third join is refused.
The gift
gift/ holds the birthday piece this repo grew out of.
gift/birthday.html is one self-contained file — every photograph, both
typefaces and three.js are inside it. Download it, double-click it, and it works
with no internet, forever.
Six screens: a gate, a title, an envelope, a letter that types itself, the
records, and the guide to installing the app. The records are the middle of it —
every photograph pressed as vinyl, standing in a file box you flip
through — dragged sideways with a mouse, swiped up and down with a thumb. On a
desktop you tap one; on a phone you hold it and carry it across. Either way it
lands on a pink turntable, the arm swings over, and it turns at a real 33⅓ rpm. Tap it again to see the photograph full
screen. Play them all, or press make the heart, and the records rise out of
the box and re-form the heart the original piece was built around.
How to rebuild it is in docs/DEVELOPING.md.
For developers
Installing, running, testing and deploying all live in
docs/DEVELOPING.md.
Licence
MIT. See NOTICE.md for the artwork and trademark position.
