ztimson/homecast
1
0
Fork 0
generated from ztimson/template
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

[OpenCast] - Core architecture for control panel + screensaver integration #9

New Issue
Open
opened 2026-09-21 12:33:28 -04:00 by assistant · 0 comments
assistant commented 2026-09-21 12:33:28 -04:00
Copy Link
Copy Source
name, about, labels
name about labels
Enhancement High-level architectural ticket for OpenCast control shell, screensaver status, and LLM hooks.
Architecture
OpenCast
Electron
LLM

OpenCast Control Shell Architecture

We need a unified control shell that ties together:

  • The OpenCast API/Express backend
  • The LLM AI harness (MCP server)
  • The Puppeteer kiosk browser (casting + idle dashboard)
  • The screensaver status feed
  • The WebVNC remote desktop server

The goal is to implement an "Iron Man" style experience:

  • A control panel accessible via API and PWA link
  • A screensaver/status display that the LLM can speak through on wake/notification
  • Minimal UI layers; concerns kept separate, not mashed into nested iframes

Context

This is the backbone for the media control and screensaver integration discussed in architectural planning. We need to define the app shell and connect it to existing or upcoming services (MRS, puppeteer manager, weather API, etc).

Description

We're building a lean Electron app shell running an Express server on port :3000, hosting an MCP server for LLM hooks, and managing a Puppeteer kiosk in the background. Key aspects:

  • API layer for cast control, idle URL configuration, weather proxy, and status reporting
  • MCP endpoints for the LLM to read status and push hints/notifications
  • A thin UI overlay (sticky blur/blur effect, notification toasts, cast/VNC mode toggles)
  • Puppeteer kiosk that always points to either a casting site or a "idle" URL (random image or custom dashboard)

Expected Behavior

  • App runs as a single Electron process with:

    • In-memory API server
    • MCP server exposed for LLM communication
    • WebVNC access for remote desktop
    • Puppeteer kiosk process manager for browser control

  • OpenCast API provides:

    • /status endpoint returning ui_hint, media_state, weather, notifications
    • /cast endpoint for start/stop casting control
    • /idle-url for managing idle screen/background URL
    • /weather proxy for Homebrew weather station
    • /notification webhook for 3rd party integrations

  • LLM hooks via MCP:

    • list_status() reads current state
    • speak_hint() triggers status updates and overlay hints
    • push_notification() updates status and triggers toasts

  • Screensaver/status feed:

    • Aggregates media state, weather, notifications, and LLM hints
    • Displays minimal, real-time data in idle/cast/vnc modes

  • UI overlay:

    • Sticky/blur focus effect on the window frame
    • Notification tray/overlay (hidden during casting/VNC)
    • Mode control via control panel or system events

Scope

  • In scope:

    • Core app shell (Electron + Express + Puppeteer manager)
    • Minimal API endpoints as defined
    • MCP endpoints and basic status structure
    • Screen saver/status display logic
    • WebVNC integration
    • PWA manifest and service worker for portable sharing

  • Out of scope for this phase:

    • Web gallery uploads (can be added as a simple route later)
    • Complex idle URL customization (basic URL + random image default is fine)
    • Deep UI polish beyond the core blur/overlay effect

Notes

  • Keep it lean: concerns separate, API + backend in one shell, UI thin.
  • Default idle URL: EarthPorn / LoremFlickr / Picsum random image.
  • Puppeteer kiosk: headless or minimal UI; just a browser engine controlling the “face” of cast/idle.
  • This is the central hub for all future integrations (AI harness, weather, maps, atak, etc.)
--- name: "Enhancement" about: "High-level architectural ticket for OpenCast control shell, screensaver status, and LLM hooks." labels: - "Architecture" - "OpenCast" - "Electron" - "LLM" --- # OpenCast Control Shell Architecture We need a unified control shell that ties together: - The OpenCast API/Express backend - The LLM AI harness (MCP server) - The Puppeteer kiosk browser (casting + idle dashboard) - The screensaver status feed - The WebVNC remote desktop server The goal is to implement an "Iron Man" style experience: - A control panel accessible via API and PWA link - A screensaver/status display that the LLM can speak through on wake/notification - Minimal UI layers; concerns kept separate, not mashed into nested iframes ## Context This is the backbone for the media control and screensaver integration discussed in architectural planning. We need to define the app shell and connect it to existing or upcoming services (MRS, puppeteer manager, weather API, etc). ## Description We're building a lean Electron app shell running an Express server on port :3000, hosting an MCP server for LLM hooks, and managing a Puppeteer kiosk in the background. Key aspects: - API layer for cast control, idle URL configuration, weather proxy, and status reporting - MCP endpoints for the LLM to read status and push hints/notifications - A thin UI overlay (sticky blur/blur effect, notification toasts, cast/VNC mode toggles) - Puppeteer kiosk that always points to either a casting site or a "idle" URL (random image or custom dashboard) ## Expected Behavior - App runs as a single Electron process with: - In-memory API server - MCP server exposed for LLM communication - WebVNC access for remote desktop - Puppeteer kiosk process manager for browser control - OpenCast API provides: - `/status` endpoint returning ui_hint, media_state, weather, notifications - `/cast` endpoint for start/stop casting control - `/idle-url` for managing idle screen/background URL - `/weather` proxy for Homebrew weather station - `/notification` webhook for 3rd party integrations - LLM hooks via MCP: - `list_status()` reads current state - `speak_hint()` triggers status updates and overlay hints - `push_notification()` updates status and triggers toasts - Screensaver/status feed: - Aggregates media state, weather, notifications, and LLM hints - Displays minimal, real-time data in idle/cast/vnc modes - UI overlay: - Sticky/blur focus effect on the window frame - Notification tray/overlay (hidden during casting/VNC) - Mode control via control panel or system events ## Scope - **In scope:** - Core app shell (Electron + Express + Puppeteer manager) - Minimal API endpoints as defined - MCP endpoints and basic status structure - Screen saver/status display logic - WebVNC integration - PWA manifest and service worker for portable sharing - **Out of scope for this phase:** - Web gallery uploads (can be added as a simple route later) - Complex idle URL customization (basic URL + random image default is fine) - Deep UI polish beyond the core blur/overlay effect ## Notes - Keep it lean: concerns separate, API + backend in one shell, UI thin. - Default idle URL: EarthPorn / LoremFlickr / Picsum random image. - Puppeteer kiosk: headless or minimal UI; just a browser engine controlling the “face” of cast/idle. - This is the central hub for all future integrations (AI harness, weather, maps, atak, etc.)
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
ztimson (Zakary Timson)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: ztimson/homecast#9