> **Design proposal** — describes a cloud/Azure architecture. The current
> implementation runs locally on a single Linux VM. See `project.md` for the
> actual system layout.

# System Architecture Overview

This document describes the various components of the Roku channel system,
where they reside (cloud vs. local), and the recommended hosting or execution
environment for each.

## Components and Hosting

| Component            | Description | Location / Host | Notes |
|----------------------|-------------|------------------|-------|
| Video Downloader     | Periodically pulls church videos from YouTube. | Ops machine or cloud VM (`media.abcc.org`) | Can run as a cron job on `media.abcc.org`; script `download_from_youtube.sh` lives in repo. |
| Media Storage        | Raw MP4 files (YouTube downloads, uploads). | Azure Blob Storage ("/media") or local file share | Accessible by encoding worker. |
| Encoding Worker      | Transcodes MP4 files into HLS segments. | Cloud VM / container or on-prem server | Could be a simple Node/Python script or Azure Function using FFmpeg. |
| HLS Storage          | Stores generated HLS playlists and segments. | Azure Blob Storage ("/hls") | Publicly readable via CDN. |
| Package Manager      | Manages JSON package definitions (collections of videos). | Cloud API / database | Could be part of the web service or a simple file store under `/packages`. |
| Schedule Manager     | Creates daily schedule JSON files. | Cloud API / database | Exposes `/schedule/*` endpoints for reads/writes. |
| Playlist Generator   | Builds the `channel.m3u8` master playlist from schedule/packages. | Cloud function or server | Triggered on schedule/package changes; writes to `/hls/channel.m3u8`. |
| CDN                  | Delivers HLS content to Roku devices. | Azure Front Door (or CDN of choice) | Points at the `/hls` container. |
| Roku Client App      | SceneGraph application running on Roku devices. | Roku devices / emulator | Fetches schedule and streams HLS playlists. |
| Monitoring / Health  | Simple `/status` endpoint plus logging/alerts. | Part of web API | Use Azure Monitor or equivalent. |

## Deployment Notes

- **Cloud provider:** Azure is assumed based on design docs, but components
  could equally run on AWS/GCP. For example, a Linux VM named `media.abcc.org`
  serves as the primary cloud host for the downloader and encoding worker.
- **API layer:** Lightweight web service (e.g. Express, Flask, Azure Functions)
  that exposes the endpoints described in `server.md`. Can be containerized
  with Docker and deployed to Azure App Service or Kubernetes.
- **Storage layout:** See `server.md` and `roku-channel-technical-design.md` for
  the blob container structure (`/media`, `/hls`, `/packages`, `/schedule`).
- **Security:** CDN should be configured to restrict origin reads to trusted
  sources (if necessary) and the API should be secured with appropriate
  authentication/authorization for write operations.

## Local Development

Developers can simulate the environment using local folders and a simple
HTTP server. For example:

```
./download_from_youtube.sh "https://..." ./media
node encode_worker.js --input ./media --output ./hls
node api_server.js
```

Roku devices can be pointed at the local API using the developer IP so long as
network routing allows it.

---
*Document created March 6, 2026.*