Festival Navigator
Plan a festival with your friends. One link per crew, everyone's picks on
one wall, live, and it still works in a field with one bar of signal.
Try it: fest.kevinhg.com
Live: v116, checked 2026-10-19.
The 2026 season is over (Portola in September, ACL in October). Still in
the catalog, with crews already picking: EDC Orlando (Nov 6–8) and Seismic
(Nov 13–15), both lineups waiting on set times, and Tomorrowland Winter
(March 2027). This is a personal project built by Kevin HG for his friends,
in the open.
Festivals loaded: 10. The list lives in
data/festivals/index.json, and only there.
Adding one: docs/add-a-festival.md.
How it works
- Your crew is a link. Every festival board mints an unguessable link
for its group of friends. The link is the access: no accounts, no
passwords, no email. Anyone holding it can read and write that board, and
nobody can touch any other. Different friend groups get different links,
like real life.
- Your own link brings it all back. "My link" on the front page is yours
alone. Open it on a new phone and every crew you're in comes with it.
- Inviting is a QR or a text. "+ Invite someone" opens one sheet: the
crew link as a QR in the app's own look (a friend points their camera at
it), a card you can save, or the link to paste into a chat. A pasted link
unfurls as that festival's own card.
- The festival's data decides the layout. While only the lineup is out
you get a searchable artist list. Where a festival publishes a stage grid,
that day is a timetable: stage columns on an honest clock, overlaps side by
side. Everything else (the afters, the late nights, the street party) is a
stack of cards under the room it happens in, in play order. Picks carry
over when set times land, because they belong to the artist, not the slot.
- Board or List. The menu on the festival's name switches between the
wall and a time list of rows, per phone and per festival. In the List,
what's already over folds away behind an "Earlier" line.
- Tap to open, + and − to pick. On a phone, a tap opens the card's
shelf: its facts,
− and + in its bottom corners, and the crew's notes.
Levels go picked ×1 → ×2 → ×3 → must; + climbs and − steps back.
With a mouse, hover grows the card and a click cycles the levels. Everyone
in the crew gets a color, and overlapping picks blend on the card, so you
can see at a glance where the crew is heading.
- Our picks. Just above the bar at the bottom of the screen sits where
most of the crew will be right now (or next). Drag it up for the day's
whole route, stop by stop, with the moments the crew splits. "Share our
picks" sends the day as a few plain lines and a link that opens on it.
- Notes go where you are standing: on the festival, on a date, on a
section on a date (the street fair on Friday), or on an artist. Replies
thread one level deep, and a note you pin stays on top for you.
- Import from a festival's own app. Screenshots of your schedule there
become picks: Gemini reads only what is printed, your phone matches the
names, nothing is saved until you add them, and the image is never kept.
- Cancelled acts stay on the wall, struck through, with your picks kept
and the reason when you open the card.
- Offline first. Picks save on the phone instantly and sync when signal
comes back. The server merges every write atomically, so two people picking
at once never overwrite each other.
- Spotify, if you want it. Connect (a sign-in that keeps no secret in
the browser) and artists you already listen to get a badge; picks can
become a playlist on your own account. See Spotify below; the 2026
rules are tight.
- Export. A day of the wall as a picture, or all your picks as text.
Privacy, plainly
- No accounts. The crew link is the key to that crew's board, so share it
like you'd share a group chat, never in public. Your "My link" is a key to
every crew you're in.
- On the hosted app, crash reports and a short list of usage counts leave
the phone through one file,
js/errlog.js. Each carries
your name in the crew, your phone type and what you tapped, which
festival you had open, your public person id, a random id for the phone,
and its screen size and app build, all from an allowlist of fields and
words. Never note text, artist names or crew links; links and tokens are
scrubbed out of error messages.
- The same file also counts visits with Vercel's cookie-free Web Analytics,
on the hosted app only: the page's address with everything after
? or
# cut off (so never a crew link), plus the rough location, browser and
device type Vercel works out itself. No cookie, and no IP is kept with
the count.
- One switch in Settings, "Send crash reports and usage to Kevin", turns it
all off. A fork on its own domain reports nowhere until it sets its own
key; run locally, it still reports upstream until that key is changed or
emptied (
docs/fork-setup.md).
Run it locally
Use Node 24, as CI does (package.json pins engines.node to 24.x).
The test tools ask for 24.15.0 or newer on that line (jsdom's own
engines); Node 22.22.2 or newer also runs everything, and there npm ci
prints an EBADENGINE warning about the 24.x pin, which is expected. No
build step: the CSS is hand-written and the JS ships as ES modules.
npm cinpm test runs the unit suite on a pinned clock. It needs no database
and no secrets: it runs the real merge SQL in-process (PGlite).npx playwright install chromium webkit once, then
npm run test:browser for the real-input contracts in Chromium and
WebKit.
tests/README.md explains the pinned clock.
To run the app itself, npx vercel dev (the Vercel CLI is not one of this
repo's dependencies; install it globally if you'd rather type
vercel dev). Two traps, both real: it does not serve files created after
it started (restart it), and it pulls the real cloud environment, so
localhost talks to whatever database DATABASE_URL names. Point Development at a database branch, or treat local writes as
production writes.
Fork it or host your own
Before your first deploy, point the app at yourself in three things:
index.html's fn-canonical-host tag (left as is, Spotify sign-in sends
your users' crew links to the upstream domain), its fn-report-key tag
(your own PostHog key, or empty), and the link-preview origin (ORIGIN in
api/share.js and the og:url and og:image tags in index.html; left
as is, every pasted link unfurls from the upstream domain).
docs/fork-setup.md has the exact steps in the order
that keeps the tests green, and the traps a real fork hit.
-
Deploy to Vercel (static files and functions).
-
Create a Postgres database (the free Neon tier is plenty) and load
the schema: psql "$DATABASE_URL" -f db/schema.sql
-
Set environment variables:
| Variable | Required | What it does |
|---|
DATABASE_URL | yes | the crew store |
GEMINI_API_KEY | no | AI festival research (api/festival-add.js) and the schedule-image import (api/import-schedule.js) |
GEMINI_MODEL | no | pins a Gemini model; default gemini-flash-latest |
OWNER_SPOTIFY_CLIENT_ID | no | your Spotify app, offered to your crew |
SLACK_WEBHOOK_URL | no | where Spotify access requests get sent |
APPROVE_SECRET | no | signs the approve link in that Slack message |
PUBLIC_BASE_URL | no | your origin, for that approve link |
The access-request flow turns on with the three Spotify and Slack
variables. On your own domain also set PUBLIC_BASE_URL: without it the
server trusts no host to build the approve link for, so no Slack message
is sent at all (the request is still recorded). Without the three
variables, members bring their own Spotify Client ID.
Add a festival
docs/add-a-festival.md is the format;
docs/fest-update-runbook.md brings one
festival's data up to date without losing anyone's picks. Two commands
matter:
node scripts/validate-festivals.mjs before committing (CI runs it too).node scripts/freeze-pick-keys.mjs <fest-id> the day real people start
picking. Artist names are pick keys, so a renamed artist would orphan
every pick on it; the freeze makes CI catch that.
Contributing
Ideas, bugs and pull requests are welcome:
CONTRIBUTING.md has the short version. Found a way to
read a crew you're not in? Please report it privately
(SECURITY.md).
Project structure
Full paths, one per line. tests/docs-truth.test.mjs checks that every one
still exists, so this list can't quietly rot.
index.html app shell: every screen lives here
gallery.html every card, wall and zoom state on one page; the browser tests run against it
service-worker.js offline shell; node scripts/sw-stamp.mjs after any cached-file change
js/v3/app.js boot, wiring, screen assembly, sheets
js/v3/wall.js the wall: the timetable where a grid is published, venue stacks everywhere else
js/v3/card-facts.js the card's facts: the zoom (hover, keyboard) and the notes shelf's card (a tap)
js/v3/events.js the events model: the days, the rooms a day holds, a room's stack in play order
js/v3/motion.js how this app moves: the shared motion constants
js/v3/settings.js settings and its drills (Spotify, export, bulk paste)
js/v3/notes.js notes on a festival, a date, a section on a date, or an artist
js/v3/import.js picks from a festival app's schedule images
js/v3/model.js the read model over a crew doc + festival data
js/v3/aura.js how a crew's picks blend into one card's color
js/v3/palette.js the 24-color member board
js/v3/router.js history-backed navigation
js/state.js crew doc + the pending-changes overlay
js/sync.js push / poll, retry, and the sync dot's one truth
js/crew.js tokens, the local crew registry, share links
js/merge.js the deep-merge the client and server agree on
js/errlog.js the only door out: crash reports and usage counts, allowlisted
js/overlap.js same-stage lane math
js/time.js parsing and flooring set times
js/name-rules.mjs name validation SHARED with the server
api/crew.js the crew store: create, read, atomic merge
api/person.js the me link: one person across crews (public pid, secret token)
api/access.js Spotify access requests (Slack approve flow)
api/festival-add.js AI lineup research: returns a candidate; saves it as the crew's own festival once confirmed
api/import-schedule.js reads a schedule image; returns only what is printed, stores nothing
api/share.js per-festival link previews: index.html with its OG tags swapped
api/_lib/ validation + guards shared by client and server
db/schema.sql Neon Postgres schema incl. the atomic jsonb_deep_merge()
assets/v3-tokens.css design tokens: look values up here, never invent them
assets/v3.css components; hand-written, no framework, no build step
assets/mark.svg the mark: one vector source for every icon and preview
assets/og/ pre-rendered link previews, one per festival
data/festivals/index.json the festival list (single source of truth)
data/venues/index.json the venue registry: each room's usual doors, close and set lengths, with sources
scripts/validate-festivals.mjs run before committing festival data; CI enforces it
scripts/guess-run-times.mjs a night's set-time guesses (club or concert) from the venue registry, as a reviewable diff
scripts/brand-assets.mjs npm run brand: regenerates the icons and every link preview
tests/ node --test suites (npm test); every test runs on a pinned clock (tests/README.md)
tests/browser/ real-input contracts in Chromium and WebKit (npm run test:browser)
docs/user-flows.md what every screen is supposed to do
docs/add-a-festival.md how to add a festival
docs/fest-update-runbook.md bringing one festival's data up to date without orphaning a pick
docs/fork-setup.md forking and self-hosting, and the traps a real fork hit
AGENTS.md the rules of the repo, for people and coding agents alike
DEVLOG.md the story so far, newest first
claude-plans/ specs, build logs and reviews (claude-plans/README.md is the index)
Sync model
Every pick is saved on the phone at once, then the change is pushed to
/api/crew, where Postgres merges it into the crew document in a single
atomic UPDATE through jsonb_deep_merge() (see
db/schema.sql). Because the merge is computed inside the
UPDATE, a second write waits on the row lock and then merges against the
first one's committed row, so two writes can't race by construction.
Other phones poll the merged doc every 25 seconds and again when the app
comes back to the screen. In Low power, or with the phone's Reduce Motion
on (it rides the same switch), the poll stretches to every 5 minutes and
coming back does not jump the queue. Removals sync as tombstones
(removed: true, and level-0 picks) because a deep merge can't express
deletion.
Two consequences worth knowing before you change anything here:
- Notes are keyed objects at every level, never arrays.
jsonb_deep_merge
replaces arrays wholesale, so an array would eat notes written at the same
time.
- Vercel Blob is not an option for the crew document. It was tried first
and dropped: its reads are eventually consistent and it measurably lost
writes under rapid merges.
Spotify
Spotify's February 2026 rules shape this whole feature: a development-mode
app is capped at 5 authorized users, a developer may hold one
development-mode app, and the app's owner needs Premium.
So the app offers three doors, in the order most people will use them:
- Connect with the crew's app. If the deployment sets the Spotify and
Slack variables above, members just connect. The owner adds them to the
app's allowlist.
- Request access. A member who isn't on the allowlist yet asks; the
owner gets a Slack message with an approve button that lands on the
Spotify dashboard's user page.
- Bring your own Client ID. The fork path. If you have your own Spotify
app, paste its Client ID. Settings has a five-step guide.
License
No open license. The code is public to read and learn from, and all rights
are reserved ("license": "UNLICENSED" in package.json); if you'd like to
reuse part of it, ask. The bundled vendor/html2canvas.min.js and
vendor/uqr.mjs keep their own MIT licenses (their headers are kept), and
the Anton and Inter fonts are under the SIL Open Font License.
