Architecture

Airwave is a small server plus thin clients. The server does all the thinking — resolving channels, building schedules, running jobs, and holding the one connection to your Plex — and the clients just tune in and stream. Everything lives in a single pnpm + Turborepo monorepo built on the Better-T-Stack.

The parts

The two web apps (web, tv-web) and the native app (tv-native) are separate front-ends over the same server API, so a channel you build in the admin plays identically on every client.

The shared packages

Business logic stays in @airwave/api services; the routers in apps/server are kept thin.

How the pieces talk

  Admin web  ──tRPC (cookie)──┐
                              ├──►  Server (Hono/Bun)  ──Prisma──►  PostgreSQL
  tv-web / tv-native  ──REST──┘         │
       │                                └──owner token──►  Plex Media Server
       └────────────── streams media directly from Plex ─────────┘

• Viewers (tv-web, tv-native) use the REST API at /api/v1, authenticated with a bearer token obtained through the TV device-code login. A client asks "what's on channel N right now?" and gets back the item plus the exact offset (the effectiveTime) to start playing at.
• The admin (apps/web) uses tRPC at /trpc with a cookie session — the type-safe channel/package/ user/job management surface. (It can also hit REST for the browser player.)
• Channel artwork is served through a public /img proxy. A CSS or <img> background can't send a bearer token, so the server proxies Plex cover art (guide thumbnails, blurred bumper backgrounds) and injects the source's token for it — clients never handle Plex credentials directly.
• Persistence is PostgreSQL via Prisma. Channels, schedules, the media-metadata cache, users, sessions, and job state all live there.

Playback is brokered through one Plex owner token

The server holds a single Plex owner token for the connected source. It uses that token to sync metadata, resolve channel filters, and figure out what's on each channel now — but it is not a transcode proxy for the schedule itself. When a client tunes in, the server hands it the item, the offset, and the right Plex connection (resolved automatically local → remote → relay, so the same app works at home and on the road). The client then streams the media straight from Plex, direct-playing natively wherever its measured capabilities allow and only transcoding when it must. Because the owner token stays on the server, viewers never need their own Plex access to the underlying files.

Deployment shape

The whole backend ships as one Docker image whose behavior is chosen at runtime by the CG_ROLE environment variable:

A PostgreSQL database and a docker-compose.yml wire it together; the server role applies Prisma migrations (prisma migrate deploy) on start. The native tv-native apps are built and distributed separately through their platform stores (or sideloaded). See the project README for the full deploy.

Where to go next

Source map

See also: Platforms · Getting started · Channels · Users & access control