Channel Status

Overview

The channel status module tracks live stream status per platform for each account. It stores whether a channel is online, along with metadata such as stream title, category, viewer count, and stream start time. Status is updated by platform workers (Twitch, YouTube, Kick) and includes a manual Spotify connect feature for controlling the Spotify polling worker independently of stream status.

Architecture

Platform Workers (Twitch/YouTube/Kick)
    |
    +--> db::channel_status::set_online / set_offline / update_stream_data
    |
    v
channel_status table (PostgreSQL)
    ^
    |
Dashboard UI
    |
    v
Next.js API Proxy
    |
    v
GraphQL (ChannelStatusQuery / ChannelStatusMutation)
    |
    +--> db::channel_status::get_status
    +--> services::channel_status (manual connect via Redis)

Status Updates

Platform workers poll for stream status changes and update the database:

• Going online -- set_online() upserts a row with is_online = TRUE and metadata (title, category, viewer count, start time).
• Going offline -- set_offline() sets is_online = FALSE and clears started_at.
• Data updates -- update_stream_data() updates viewer count, title, and category for channels that are already online.

Spotify Manual Connect

The Spotify worker normally polls only when a channel is online. The manual connect feature allows users to start Spotify polling independently, using a Redis key with a 30-minute TTL. This is useful for pre-stream setup or listening sessions without going live.

• Start -- Sets a Redis key and publishes a synthetic status change event via Redis pub/sub.
• Stop -- Deletes the Redis key and publishes a status change event.
• Query -- Returns whether manual connect is active and the remaining seconds.

Spotify Worker Lifecycle (relay)

The channel-status relay (apps/api/src/workers/channel_status_relay.rs) owns the Spotify worker's start/stop lifecycle. It subscribes to lumio:channel_status:* and, on every status change, evaluates whether the worker should run for that account:

• Should run when any channel is online or a manual connect is active. On a should-run transition the relay resolves the worker config from the live channel_connections row on demand (resolve_spotify_config) and starts the worker with the connection's current connection_id. There is no boot-time config snapshot, so a Spotify connection linked, re-authorized, or disconnected-and-reconnected after the API booted starts polling on the next stream-start or manual connect -- without an API restart. An account with no Spotify connection resolves nothing and is simply not started.
• Should not run (no channel online, no manual connect) tears the worker down. A separate 60-second poll also stops any worker whose manual connect has expired.

This is why stopping the worker at stream end / manual-connect expiry is safe: it always restarts from the DB on the next trigger. Note the emission asymmetry: only the worker produces spotify:track; spotify:skip/play/pause/… come from the playback-control path and do not depend on the worker running.

API

GraphQL Queries

Query	Args	Returns	Permission
channelStatus	--	[ChannelStatus]	spotify:read
spotifyManualStatus	--	SpotifyManualStatus	spotify:read

• channelStatus returns all platform statuses for the active account.
• spotifyManualStatus checks the Redis TTL key and returns active status with remaining seconds.

GraphQL Mutations

Mutation	Args	Returns	Permission
startSpotifyManual	--	SpotifyManualStatus	spotify:worker
stopSpotifyManual	--	Boolean	spotify:worker

REST Endpoints

All paths live under /v1.

Method	Path	Permission	Description
GET	/v1/channel-status	spotify:read	All platform statuses for the active account
GET	/v1/spotify/manual-connect	spotify:read	Manual-connect status + remaining seconds
POST	/v1/spotify/manual-connect	spotify:worker	Start manual Spotify polling (30 min TTL)
DELETE	/v1/spotify/manual-connect	spotify:worker	Stop manual Spotify polling

GraphQL Types

type ChannelStatus {
  platform: String!
  broadcastId: String!
  isOnline: Boolean!
  broadcastStatus: String
  streamTitle: String
  category: String
  viewerCount: Int
  likeCount: Int
  totalViews: Int
  startedAt: DateTime
  scheduledStart: DateTime
  liveChatId: String
  updatedAt: DateTime!
}

type SpotifyManualStatus {
  active: Boolean!
  remainingSeconds: Int
}

Permissions

Permission	Description
spotify:read	View channel status and Spotify manual connect status
spotify:worker	Start/stop Spotify manual connect

Included in: Owner, Administrator, Moderator roles have spotify:read. Owner and Administrator have spotify:worker.

Database

Table: channel_status

Column	Type	Description
account_id	UUID (PK, FK)	Account ID
platform	TEXT (PK)	Platform identifier
broadcast_id	TEXT (PK)	Broadcast/stream identifier (per-broadcast rows for multi-stream)
is_online	BOOLEAN	Whether the channel is currently live
broadcast_status	TEXT NULL	"live", "upcoming", or NULL (non-YouTube platforms)
stream_title	TEXT	Current stream title
category	TEXT	Current stream category/game
viewer_count	INT	Current viewer count
like_count	INT NULL	Current like count (YouTube only)
total_views	BIGINT NULL	Lifetime view count (YouTube only)
started_at	TIMESTAMPTZ	When the stream started
scheduled_start	TIMESTAMPTZ NULL	When an upcoming broadcast is scheduled to start
live_chat_id	TEXT NULL	YouTube live chat ID for this broadcast
updated_at	TIMESTAMPTZ	Last status update

Primary key: (account_id, platform, broadcast_id) -- one status row per broadcast per platform per account, using upsert on conflict.

DB Functions

Function	Description
set_online	Upsert with is_online = TRUE and metadata (title, viewer count, like count, total views, scheduled start, live chat ID)
set_offline	Set is_online = FALSE, clear started_at
upsert_upcoming	Upsert an upcoming broadcast (is_online = FALSE) with title, scheduled start, and live chat ID
delete_broadcast	Delete a specific broadcast row (used when a broadcast disappears from discovery)
get_status	Get all statuses for an account, ordered by platform
is_any_online	Check if any platform is online (DB fallback)
update_stream_data	Update viewer count, title, category for online channels
get_all_online_accounts	Boot recovery: all accounts with online channels, grouped

Redis Keys

Key	TTL	Description
lumio:spotify_manual:{account_id}	30 min	Manual Spotify connect active flag

Key Files

File	Purpose
apps/api/src/graphql/channel_status.rs	GraphQL queries and mutations
apps/api/src/db/channel_status.rs	Database operations
apps/api/src/services/channel_status.rs	Manual connect logic (Redis TTL, pub/sub)