How tuomoku/spx-gc works
Project type and purpose
• This is a full-stack, Node.js-based web application (“SPX Graphics Controller”) for live on-screen graphics playout and control.
• It exposes a browser-based UI (frontend) and a JSON/HTTP/Socket-driven backend to manage “projects,” “rundowns,” and playout templates, and delivers HTML-renderer URLs to downstream video software (OBS, CasparCG, etc.).
File-structure overview
• Top-level server entry point: server.js (+ optional PM2 config ecosystem.config.js)
• Routes: /routes/*.js define HTTP endpoints (UI routes and API v1)
• Utils: /utils/*.js house business logic (file I/O, sockets, playout commands)
• Views: /views/**/*.handlebars are Handlebars templates for server-rendered UI
• Static assets: /static (CSS/JS/img) and /ASSETS (template HTML, media files, plugins)
• Data storage: /DATAROOT holds user projects, profile.json, rundown JSON files
• Localization: /locales/*.json
Key architectural insights from README
• Uses Express.js for HTTP server, Handlebars for server-rendered pages, and Socket.io for real-time preview updates.
• Projects and rundowns are stored as JSON files on disk (no external DB).
• Exposes a /renderer endpoint that video tools consume as a “browser source.”
• Communicates with external playout servers (e.g., CasparCG) via custom JS modules in utils/playout_*.js.
• Supports plugins/extensions loaded from ASSETS/plugins.
Main components and their interactions
A. Browser-based Frontend
• UI pages (views/*.handlebars)
• Static assets (static/js, static/css)
• Socket.io client for live preview and rundown events
B. Node.js Backend (Express)
• HTTP server (server.js)
• Route handlers (routes/)
• Business logic in utils/ (file I/O, config management, playout commands)
• WebSocket server via utils/sockets.js
• Template definition loader (scans HTML for window.SPXGCTemplateDefinition)
C. File-system storage
• Config (config.json), projects (DATAROOT/<project>/profile.json), rundowns (.json), logs
• Template files under ASSETS/templates and media under ASSETS/media
D. External Services
• CasparCG (via utils/playout_casparCG.js)
• Webplayer playout (utils/playout_webplayer.js)
• Any other video pipeline (OBS, vMix) consumes /renderer endpoint
E. Plugin system
• Custom UI controls & extensions loaded from ASSETS/plugins
Architectural patterns & design principles
• MVC-like separation:
• Models: JSON files in DATAROOT
• Views: Handlebars templates
• Controllers: routes/ + utils/api-handlers.js
• File-based persistence instead of a DB simplifies portability
• Plugin architecture (loose coupling): each plugin has its own subfolder + init.js
• Real-time updates: Socket.io for preview and control signals
• Configuration driven: all settings in config.json, localizable via /locales