Glossary

The platform inherited names from a MongoDB/Redis era. This page separates what a word means today from what it used to mean.

Runtime

Gateway — vps-reverse-proxy. The only public entry point. A TLS nginx tier plus one proxy per domain. It terminates TLS, matches the longest path prefix, and strips it.

SPA — a single-page application. The website, webview and admin back office are static bundles served by nginx; the browser does the routing.

WebView — the React SPA (greyscreen-webview) embedded in the phone app. It does not authenticate on its own; the native shell injects the user and token over a bridge.

Bridge — a postMessage protocol between the phone shell and the webview. Actions such as SAVE_USER_DATA, NAVIGATE_TO_TV_PAIR, CAST_LOAD_MEDIA and TV_REMOTE_COMMAND travel over it.

Admin API — gstv-admin-api, port 3003. Content CRUD, upload signing, transcode queue, VM lifecycle, readiness, deletion cascade, admin notifications. One replica only.

Customer API — gstv-customer-api, port 3000 in test/prod and 3001 in dev. Public catalogue, playback data, viewer state, My List, Top 10, Stripe and Flutterwave billing.

Multimedia — gstv-multimedia, port 8000 (plus NMS 8080 and RTMP 1935). Serves HLS through a two-tier cache; also accepts RTMP ingest.

Worker — gstv-vps. An ephemeral Google Compute Engine VM that runs ffmpeg, writes the HLS ladder, publishes one resolution event per rendition, then deletes itself when idle.

Admin web — gstv-admin-web, the back-office SPA. Upload wizard, catalogue management, processing monitor, users, plans, audit logs, notification bell.

TV — gstv-tv, the Android TV client. Browsing, HLS playback, Google sign-in, pairing and a limited remote. Payments happen on the phone.

Phone shell — greyscreen-expo-webview. Expo/React Native host for the webview; Google and Apple sign-in, FCM, Android Cast, pairing and remote screens.

Data

Firestore — the source of truth. Users, catalogue, plans, payments, admins, audit logs, staging, notifications, view aggregates. Native mode, region nam5.

RTDB — Firebase Realtime Database. Used for queues (queue/transcode, queue/resolutionEvents), worker heartbeat and shutdown flags, and TV pairing sessions. Not a second catalogue.

GCS — Google Cloud Storage. Three roles: images (artwork), input (raw masters), output (HLS renditions). Bucket names carry -test or -prod.

Staging — a temporary Firestore document keyed by fileId, created by addVideo with a seven-day expiry. It records upload progress; it is removed when the title goes live.

Readiness — the transition to isReady: true. It requires transcode.status === "completed", a non-empty trailerResolution, and thumbnail.thumbnailUrl. It is evaluated in a transaction, not flipped by an event handler.

Snapshot — the customer API's in-memory view of all ready videos, series and seasons, maintained by a Firestore onSnapshot listener.

Entitlement — what a user's current plan allows. It is checked by the client and by the customer API, but most legacy endpoints trust a client-supplied user ID. See Security notes.

_id — the identifier synthesised from a Firestore document ID in API responses. For plans and admins it preserves the legacy Mongo _id. Changing a document ID is a breaking API change.

Media

HLS — HTTP Live Streaming. A master playlist points to one playlist per quality level, which points to .ts segments. This is the only delivery format; there is no DRM.

Rendition / rung — one quality level in the ladder: 144p, 240p, 360p, 480p, 720p, 1080p, 1440p or 2160p. Only rungs at or below the source height are produced.

Master playlist — playlist.m3u8, written before the renditions so the readiness consumer can find it. A title is not considered complete until the master exists.

gcsfuse — a FUSE mount that makes a GCS bucket look like a local directory to the worker and the streaming server. It is why the worker container needs privileges and /dev/fuse.

Two-tier cache — the multimedia server's HLS cache: 512 MB in RAM, 8 GB on disk, promote after repeated hits, LRU eviction. It sits between the player and gcsfuse.

Operations

APP_ENV — dev, test or prod. Distinct from NODE_ENV. Selects which env layers are loaded and which checks fail closed at boot.

.env.template — the only tracked env file in the APIs. .env.*.local and .env.nonprod.local are gitignored and excluded from Docker builds.

Test stack — the containers on test.greyscreentv.com (82.38.44.60). It currently shares the production Firebase project; RESOLUTION_CONSUMER_DISABLED=true prevents a second claim consumer.

Moving tag — CI publishes :test or :prod and overwrites it. It also stamps an OCI revision label. There is no retained per-commit tag, so a rollback means rebuilding the previous commit or redeploying a digest recorded before the upgrade.

Claim queue — an RTDB list consumed with child_added by a process that removes each child after handling it. Two consumers on the same queue would double-process, which is why the admin API is single-instance.

SSE — Server-Sent Events. The admin API streams video.live and video.failed frames to the admin notification bell over /notifications/stream, with replay by Last-Event-ID.

Pairing — a six-character TV session in RTDB. The TV shows the code; the phone writes user data and commands. Today the RTDB rules are world-readable and writable, and the TV applies paired data without server verification.