Trailmarks
Live at trailmarks-lovat.vercel.app
A fun, interactive way to track every state you've visited in North America —
mark states off on a live map, capture the memories and photos from each
trip, and relive them in a slideshow. Photo book printing is on the roadmap.
Deployed on Vercel (auto-deploys from main), backed
by Supabase for the database and photo storage.
Stack
Next.js 16 (App Router) + React 19 + TypeScript + Tailwind CSS 4, backed by
Supabase (Postgres + Storage). No local database
file, no persistent-volume requirement — the app is stateless and can
deploy to any Node host.
- Map:
react-simple-maps +
us-atlas TopoJSON — a real,
accurate geographic map (not a hand-drawn approximation), rendered with
geoAlbersUsa so Alaska and Hawaii sit as insets like on a printed map.
- Animation: Framer Motion for the mark-visited pop, stat bar fills, the
slideshow's Ken Burns pan/zoom, and page transitions.
- Images: uploads are resized (max 2400px) and re-encoded to WebP with
sharp on upload, then served through Next's image optimizer.
- Trip map:
maplibre-gl with free,
no-API-key tiles from OpenFreeMap (positron
style) — real streets/terrain, not a choropleth, so a recorded route draws
as an actual line over the map like Polarsteps. MapLibre's web worker
can't be found once Next bundles the library, so
scripts/copy-maplibre-worker.mjs (run by predev/prebuild) copies it
into public/vendor/maplibre/ and TripMap points setWorkerUrl() there.
Design system
"Glacier": modeled on the photo-first travel apps the owner picked as
references. Cool mist and white surfaces let the photos carry the color.
Petrol (deep teal) is for anything you act on. Aqua marks land and
routes you've claimed. Sun (amber) is for highlights and achievements,
and Coral is used only for recording and errors. There is a true dark mode.
Tokens live in src/app/globals.css; never hard-code hex values in components.
- Type: Outfit everywhere, in bold geometric headlines and a plain UI weight.
Icons: Phosphor, light weight.
- You land on the map: the home page is a one-line headline and the map,
sized to fit above the fold. Progress lives in a "16 / 50 states" pill that
grows into a stats drawer (count, region ranking, land explored) over the
left third of the map; on desktop a tapped state takes over the map's top
bar instead of a side panel.
- Photos lead everywhere else. Trip cards are the trip's cover (or its first
step's photo) with the route drawn over it in white, and trip and state
pages open on a full-bleed photo. With no photo,
surfaces fall back to the
.brand-gradient. .glass is for stat chips on
photos, and .photo-scrim keeps white type legible on them.
- Cards are one white surface (
Panel) with a soft cool shadow and a 28px
radius. Buttons come in primary, secondary and quiet for the page,
plus light and glass for photos.
- Motion:
src/lib/motion.ts holds the shared easings and springs. Respect
prefers-reduced-motion (handled globally via MotionConfig).
- The home map (
src/components/map/UsMap.tsx) is hand-built on d3-geo +
us-atlas's pre-projected Albers file, so every state is its own animatable
path. It has a sunrise-sweep intro; tap to claim (the edge glows and the
color blooms outward from your finger, gold when it completes the family),
press and hold to unclaim (a ring fills under your finger); haptics; and an
amber outline trace on select.
Architecture
src/lib/supabase.ts — single getSupabase() singleton, a
@supabase/supabase-js client authenticated with the service_role
key. All data access goes through this app's own API routes on the
server; the browser never talks to Supabase directly, so no key is ever
exposed client-side and Row Level Security on every table is left "on,
no policies" as a second lock (the service role bypasses RLS regardless).- Requires two env vars:
SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY
(Supabase dashboard → your project → Settings → API). Put them in
.env.local for local dev (gitignored) and in your host's environment
variables for production.
- Photos upload to a public Supabase Storage bucket named
photos (resized
to max 2400px and re-encoded to WebP with sharp first) and are served
straight from Supabase's CDN — next.config.ts allow-lists
*.supabase.co/storage/v1/object/public/** for next/image.
src/lib/statesData.ts — the 50 states + DC, keyed by USPS code, with a
FIPS code for matching against the TopoJSON id, region, land area (for
the "% of North America explored" stat), and a fun fact.- Data model:
families (name + invite code), profiles (one per person:
family, display name, map color), state_visits (one row per person per
state, visited flag + first-visited date), memories (title/body/date,
optionally linked to a state and/or a trip, with lat/lng for trip
"steps"), photos (file name + caption, linked to a memory), trips
(title/status/dates), trip_points (the raw GPS breadcrumb trail for a
trip). Trips, memories and photos carry user_id (author) and family_id.
Family accounts
- Everyone has their own login (Supabase Auth, email + password) and belongs
to one family.
/join starts a new family; /join?code=XXXXXXXX joins one
from its invite link (on /family). Accounts are created server-side as
already-confirmed users (src/lib/family.ts → createAccount), so no
confirmation email or Supabase email setup is needed.
- Claims are per person; trips, memories and photos are shared with the whole
family and show who added them. Only the author can delete a memory or
photo, and only a trip's owner can record, add steps to, finish or delete
it. Nothing crosses families.
- On the map: your states are solid aqua, states only other family members
have claimed are a lighter tint, and a state everyone in the family has
claimed turns shimmering gold. Tap a state and the people who've been
appear round a campfire on it (
Campfire.tsx). The stats drawer adds a
family ranking and an "everyone's been" count.
- Invites: the dashed "+" seat in the map header (or Invite in the nav)
opens a sheet with the share sheet, Text, Email, Copy and a QR code; any
member can make a new link.
/join also takes a typed code.
- Adventurer avatars: tap your own avatar in the map header to pick or
make one. A selfie becomes the free in-browser comic badge
(
src/lib/photoBadge.ts, unlimited) or, up to 5 times per person, an
AI illustration (/api/avatar/illustrate, AI Gateway, medium quality,
about 1 cent each). Every illustration is kept in adventurers to switch
between; a failed call doesn't use a try. Only finished avatars are stored,
never the selfie, in the private avatars bucket (/a/<file>).
- Password reset without email: on
/family, anyone can make another
member a one-time, 48-hour link (src/lib/passwordReset.ts; only a hash is
stored). You can change your own password there too.
- Private media: photos (
/p/<file>, resized via a custom next/image
loader), avatars and voice notes are all in private buckets, served only to
the owner's family.
src/proxy.ts refreshes the session cookie on every request and sends
anyone signed out to /login (API routes get a 401). Pages call
requireViewer() and API routes apiViewer() (src/lib/auth.ts), then
scope every query by the viewer's family and check ownership on writes.- Auth uses the project's publishable key (
src/lib/supabaseConfig.ts,
overridable with SUPABASE_PUBLISHABLE_KEY). It is public by design and
reads nothing on its own, since every table has RLS on with no policies;
data access stays on the server-side service role client.
Trips: auto-generated maps from GPS
Starting a trip (/trips/new → trip page → "Start recording") begins a
navigator.geolocation.watchPosition session that streams points to
/api/trips/[id]/points, throttled to roughly one point per ~10 seconds or
~13 meters of movement. src/components/TripMap.tsx (MapLibre) draws that
breadcrumb trail as a live route line on a real map, and
src/lib/stateLookup.ts does a point-in-polygon check (via d3-geo's
geoContains against the same us-atlas state polygons the choropleth
map uses) to figure out which states a trip actually passed through.
Finishing a trip (src/lib/trips.ts → finishTrip) runs that detection
over every recorded point and merges the results into state_visits — so a
recorded road trip auto-marks the states/countries it touched, the same way
the manual tap-to-mark map does. Both stay available: manual marking for
quick logging or trips with no GPS data, auto-detection for anything
actually recorded.
Important limitation — read before assuming this behaves like Life360 or
Polarsteps' native app: this is a website, not a phone app with background
location permission. GPS recording only runs while that trip's page is open
in the foreground (screen on, tab active) — it stops the moment the tab is
closed or the phone is locked/backgrounded. The UI says "Recording — keep
this tab open" for exactly this reason. True background tracking (recording
a drive while the phone is in your pocket) needs a native app or a PWA with
background geolocation, which is a real follow-up project, not a setting to
flip. Points recorded so far are never lost when recording stops — resuming
just continues appending to the same trip.
Supabase setup
The trailmarks Supabase project (org: benjaminjakeallen-alt's Org) already
has this schema applied via migration:
families, profiles, state_visits, trips, trip_points,
memories, photos — the shapes described above. Migrations since
family accounts live in supabase/migrations/.- A public Storage bucket named
photos.
- RLS enabled on every table with no policies — nothing but the
service_role key (used only server-side by this app) can read or write.
To point a fresh checkout at it (or a different Supabase project), set:
SUPABASE_URL=https://<project-ref>.supabase.co
SUPABASE_SERVICE_ROLE_KEY=<service_role secret, from Settings → API>
Setting up a brand-new Supabase project instead of reusing this one? The
migration SQL is straightforward to reconstruct from src/lib/supabase.ts,
src/lib/trips.ts, and src/lib/memories.ts's row shapes, or ask Claude to
regenerate it from this repo's history.
Getting started
npm install
npm run dev
Open http://localhost:3000. The map starts empty —
click any state to mark it visited (or start a trip under Trips to
record a real route), which takes you to that page to add memories and
photos.
Geolocation requires a "secure context" (HTTPS, or localhost — which
npm run dev already is) or the browser will refuse it outright.
Journal and voice
On the map, a state's Open journal grows a slide-over panel out of the
button, docked on the right: that state's family memories plus the composer, without leaving the
map (the full /states/[code] page is a link away). Every composer has a
mic: speak and the words stream into the entry (browser speech recognition,
src/lib/useDictation.ts), while the recording itself is kept and plays back
on the memory (src/lib/useRecorder.ts). Without live speech recognition the
clip is transcribed on the server.
The world
The map's USA / World switch turns to a globe (WorldGlobe.tsx): drag to
spin, tap a continent and it turns to face you, tap a country to claim it,
hold to unclaim, search for the small ones. See docs/BACKLOG.md item 8.
Photo import
On a trip page, Import photos reads each photo's capture time and GPS in
the browser, joins photos to nearby same-day steps, groups the rest into new
stops, and shows the plan for review before uploading. See
docs/BACKLOG.md item 7 for the rules and the iPhone picker's limits.
Roadmap
Detailed feature ideas awaiting a go-ahead live in docs/BACKLOG.md.
- Photo books — export a state's (or a whole trip's) memories and photos
into a printable photo book via a print-on-demand API (e.g. Mixbook,
Printful, or Artifact Uprising's API where available).
- Canada & Mexico — the data model and map component are built to
extend beyond the US 50; adding provinces/states just means new entries
in
statesData.ts and swapping in a North America TopoJSON.
- Background GPS tracking — a native app or PWA with background
geolocation, so a trip keeps recording without the page staying open.
This is the biggest gap versus Polarsteps' actual app.
- GPX import — for anyone who already recorded a route in another app
(Strava, Gaia GPS, a Garmin) and wants to bring it in instead of
re-recording live.
- Map themes and a different activity in every state — see
docs/BACKLOG.md items 9 and 10.
- Offline-friendly PWA — so photos can be added from the road before
reception comes back.
