The app

Bytestream is one Expo SDK 57 universal app (managed workflow) with Expo Router for file-based navigation, targeting web, iOS, and Android from a single TypeScript codebase.

Storage keys never rename

Every persisted browser-storage key carries the atlas. prefix — atlas.settings, atlas.saved, atlas.watch, atlas.theater, atlas.stills.v1, atlas.catalog.v*, atlas.epg.v2, and the atlas IndexedDB database name itself (src/state/storage.ts).
These are not configuration — they are where a viewer’s data already lives, in their browser, right now. Renaming a key does not migrate that data; it orphans it, and the app comes up as if the viewer had never used it (settings reset, saved channels gone). A rename is only safe behind a read-old/write-new migration, and none exists.

Auth: Clerk + Supabase

Clerk handles sign-in; Supabase holds the data, gated by row-level security keyed on clerk_sub() — a Postgres function that reads the Clerk subject out of the request, so a signed-in viewer can only read or write their own rows (see the RLS policies in supabase/migrations/20260920090000_recommendations.sql, e.g. (select public.clerk_sub()) = user_id). Sign-in is fully optional. Without EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY set to a real pk_ key, no ClerkProvider mounts at all, and the app renders exactly as it always has — anonymous watch, no auth context.
Clerk hooks (useAuth, etc.) may only be called behind useClerkReady() (src/auth/AuthRoot.tsx), never behind clerkConfigured() alone. A key being configured and a ClerkProvider actually being mounted above a given component are different questions — a component that mounts before the client-only provider does (2026-09-12: AccountControl in the sidebar) throws “useAuth can only be used within the <ClerkProvider />” and blanks the app if it skips this check.
How the token is verified (2026-09-22). The app hands Clerk’s RS256 session token to Supabase as its access token. Supabase can only verify it because the project has a Third-Party Auth entry for the Clerk issuer (https://clerk.bytestream.tv, added by scripts/supabase-clerk-tpa.sh); without it every signed-in query answers No suitable key or wrong key type. The Clerk supabase JWT template carries role: authenticated; the old shared-JWT-secret integration is deprecated and not used.

Creators: uploads, the N00bstream, and live

A creator uploads to a private R2 bucket (bytestream-uploads) through a presigned PUT; api/upload-complete hands Mux a presigned GET; Mux encodes for free and api/mux-webhook copies the highest.mp4 rendition, a poster and eight filmstrip frames back into the private bucket and deletes the Mux asset, so steady-state cost is R2 storage only and delivery is free. A reviewer watches it through presigned URLs (api/review-media) and approves it onto a channel; approval copies it to the same keys in the public bucket (bytestream-media, served whole at media.bytestream.tv), which is the only way anything gets there (api/_lib/media.ts). A creator channel is a playlist played on a loop against the wall clock (src/catalog/schedule.ts): what is on is epoch % total_runtime, so every viewer sees the same frame. The creators catalog source (src/catalog/sources/creators.ts) resolves a row to a progressive mp4 plus a start offset (Playable.startAt), which both players honour; on ended the channel re-resolves to the next item. Live is self-hosted: MediaMTX on a Hetzner box (live/, live.bytestream.tv) takes OBS’s RTMP/SRT and serves LL-HLS. Each live input has a public playback id, which names the path live/<playback_id> that viewers play, and a secret stream key, which OBS sends only as the publisher’s password. Its hooks (api/live) decide each publish against that pair and flip live_inputs.connected; while a creator is connected resolve() returns the live playlist instead of the loop. Metrics go to Grafana Cloud via Alloy; errors to Sentry; both alert into Telegram through api/alerts.

The stream relay

Roughly 868 channels in the catalog serve every one of their streams from jmp2.uk (Pluto TV’s edge), which answers with a CORS header that allows only http://pluto.tv — a browser refuses to fetch it, even though the native app and VLC play it fine. worker/ is a small Cloudflare Worker that fetches such a stream server-side and returns it with a header a browser will accept. It runs on Cloudflare’s free plan by design — no KV, R2, D1, Durable Objects, Queues, cron, smart placement, or custom domain — and is deployed at atlas-stream-relay.brainpowerux.workers.dev.
It is not an open proxy: it relays only hosts on an explicit allowlist and refuses everything else with a 403. It is not a way around geo-blocking — Cloudflare answers from a data centre near the viewer, so a geo-blocked upstream still refuses that viewer. Nothing of the viewer’s goes upstream: no cookies, no Authorization, no client User-Agent, no Referer.
The allowlist (worker/wrangler.toml, [vars] ALLOWED_HOSTS) is five hosts: jmp2.uk, pluto.tv, plutotv.net (Pluto’s redirect chain), plus channel-assembly.mediatailor.us-east-1.amazonaws.com and nasaplus.akamaized.net (NASA+‘s manifest and segment hosts). HLS is recursive — a master playlist points at media playlists, which point at segments and encryption keys — so every URL inside a playlist is rewritten to route back through the relay, resolved against wherever the playlist was finally served from after redirects. The relay is enabled only when EXPO_PUBLIC_ATLAS_RELAY_URL is set at Expo export time, and only for web — native never routes through it. See Quickstart for the variable and the --clear caveat when changing it.

Deploying

The web build deploys to Vercel as a static site (vercel.json: framework: null, buildCommand: pnpm build:web, outputDirectory: dist). The Vercel project is connected to the GitHub repository (sachio222/atlas): every push to main builds and promotes production, and every other branch gets a preview URL. Nothing in the repo deploys itself; the EPG workflow publishes data to Supabase Storage and the docs workflow deploys the separate bytestream-docs project. Two project settings keep deployments small. VERCEL_FORCE_NO_BUILD_CACHE=1 is set on Production and Preview: Vercel stores a build-cache snapshot (about 216 MB here) with every deployment, and at eight deployments a day that reached 10 GB in eleven days; a cold pnpm install costs about a minute per build instead. .vercelignore also drops api/*.test.ts, which Vercel would otherwise build into functions of their own. The project’s Ignored Build Step skips the deploy when a push touches only docs/, scripts/, .github/, e2e/, markdown, or test files, so a docs or workflow commit does not rebuild the app. A manual deploy still works when you need one:
The GitHub connection depends on the Vercel GitHub App having access to the repository. If a push does not produce a deployment, check the app’s repository list under GitHub → Settings → Applications → Vercel, then vercel git connect from the repo.
Vercel refuses any deployment whose git commit author email is not verified on the account, and the CLI then waits on a build-event stream that never opens — a blocked deploy looks like a hang, not an error. Commit as the verified address (git config user.email brainpowerux@gmail.com) and check vercel inspect <deployment-url> if a deploy sits at UNKNOWN for more than a minute or two.