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, Trovo) and includes a manual Spotify connect feature for controlling the Spotify polling worker independently of stream status.

Architecture

Platform Workers (Twitch/YouTube/Kick/Trovo)
    |
    +--> 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.

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!
  isOnline: Boolean!
  streamTitle: String
  category: String
  viewerCount: Int
  startedAt: DateTime
  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
is_online	BOOLEAN	Whether the channel is currently live
stream_title	TEXT	Current stream title
category	TEXT	Current stream category/game
viewer_count	INT	Current viewer count
started_at	TIMESTAMPTZ	When the stream started
updated_at	TIMESTAMPTZ	Last status update

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

DB Functions

Function	Description
set_online	Upsert with is_online = TRUE and metadata
set_offline	Set is_online = FALSE, clear started_at
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)