🐂 YakPack

An offline-first packing and itinerary companion for the mountains.

Weather-aware packing · a shared list for up to four people · an AI guide you bring your own key for

yakpack.tech · Terms · Privacy

---

Contents

• What it does
• Architecture
• The decision worth reading first
• Ticking something off with no signal
• Four more decisions
• Repo structure
• Quick start
• Environment
• Roles and data
• Testing
• What's imperfect
• Tech stack
• Licence

---

What it does

I wrote it for one specific trip: nine days from Delhi into the Spiti Valley and back, climbing from 216 m to 4,590 m at Kunzum La, with two days where the itinerary's own notes record the signal as "near-zero" and then gone entirely.

Packing for that with other people is genuinely awkward. You carry a down jacket you will not touch for four days and a headlamp you need at exactly one campsite. Half the kit is shared and should only be carried once. And the day the packing matters most is the day you cannot reach the internet.

So the trip became the spec.

• Weather-aware packing. Items carry tags. Below 5 °C or above 4,000 m the cold layers surface on their own; rain probability at or above 50 % pulls the cover out; a UV index of 6 or more pulls the sunscreen. The thresholds live in lib/weather.ts, not in a prompt.
• Four people, one list. An organiser plus up to three partners, invited by link. Items belong to one person or to everyone: personal items track a packed state each, shared items track one between the group. Changes arrive on the other phones over Supabase Realtime.
• Genuinely offline. The pack list, plan, and last-known forecast stay readable with the radio off. Check-offs made offline are queued on the device and replayed on reconnect — and they are never rolled back.
• Altitude-aware. lib/ams.ts derives acute-mountain-sickness risk from the day's altitude gain with no AI involved, so the warning still works with the network off.
• Pemba, the AI guide. Reads the real itinerary, live weather, and packing state before answering. It can add items — every write stops at a confirmation sheet first.
• Bring your own key. Pemba runs on the user's own OpenAI key, held in the browser and passed per request. It is never written to the database. The deployment's own key is reserved for the admin account, so nobody else can spend it.
• Start a trip however you like. Upload a PDF, paste a link to an itinerary, build it by hand, or copy the seeded example. The link importer works without any AI key at all.
• A small admin panel. The operator can list accounts, rename them, set a password, grant or revoke admin, and delete an account with everything it owns.

---

Architecture

flowchart LR
  subgraph Phones["📱 Up to four phones"]
    PWA["PWA shell<br/>service worker + outbox"]
  end

  subgraph Edge["Next.js 16 on Vercel"]
    PX["proxy.ts<br/>auth gate on every route"]
    RSC["Server Components<br/>one reader per screen"]
    ACT["Server Actions<br/>all writes"]
    API["Route Handlers<br/>ai · weather · import"]
  end

  subgraph Supa["Supabase"]
    PG[("Postgres<br/>RLS scoped per trip")]
    AUTH["Auth"]
    RT["Realtime"]
  end

  OM["Open-Meteo<br/>forecast + geocoding, keyless"]
  OAI["OpenAI<br/>the user's own key"]

  PWA --> PX
  PX --> RSC
  PX --> ACT
  PX --> API
  RSC --> PG
  ACT --> PG
  RSC --> OM
  API --> OM
  API --> OAI
  AUTH --- PG
  RT -. "pushes changes" .-> PWA

Reads go through one getXData() per screen in lib/, each parallel-fetching under RLS with the cookie-bound client. Writes are server actions that re-check the session and sanitise free text before it can reach a prompt. Weather is fetched server-side directly rather than by the server calling its own /api/weather — building an internal URL from the Host header is an SSRF vector.

---

The decision worth reading first

A service worker that must not cache the framework's own navigation.

The obvious service worker has a catch-all branch: try the network, fall back to the cache, and cache whatever comes back. I wrote that one. It broke the app in both directions, and the online direction was the surprising one.

Next's client-side navigation is not a document navigation. It is a fetch carrying an RSC: 1 header and a ?_rsc=<hash> query parameter, and request.mode === 'navigate' is false for it. So it misses every handler written to recognise a page load and lands in the catch-all instead.

flowchart TD
  F(["fetch event"]) --> A{"GET?"}
  A -- no --> N["pass through"]
  A -- yes --> B{"http or https?"}
  B -- no --> N
  B -- yes --> C{"dev build?"}
  C -- yes --> N
  C -- no --> D{"RSC: 1 header<br/>or ?_rsc= param?"}
  D -- yes --> G["pass through — the guard"]
  D -- no --> E{"which URL?"}
  E -- "Supabase rest/v1" --> H["network-first, DATA_CACHE"]
  E -- "api/weather" --> I["network-first, WEATHER_CACHE"]
  E -- "other api routes" --> N
  E -- "next/static, icons" --> J["cache-first, STATIC_CACHE"]
  E -- "document navigation" --> K["network-first, PAGE_CACHE, then offline shell"]

  style G fill:#d4943a,stroke:#333,color:#000

Once an RSC payload lands in a cache, two things go wrong:

This is the beginning of the README. Read the rest at the original. Read the full README ↗