# tuomoku/spx-gc architecture

> Architecture diagram of the GitHub repository tuomoku/spx-gc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tuomoku/spx-gc
- Repository: https://github.com/tuomoku/spx-gc

## Overview

##### 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`

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        UI["Browser UI\n(Handlebars Views)"]:::frontend
        StaticAssets["Static Assets\n(CSS/JS/Images)"]:::frontend
        SocketClient["Socket.io Client"]:::frontend
        RendererClient["/renderer Browser Source"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        Server["Express Server\n(Node.js/Express)"]:::backend
        Routes["Route Handlers"]:::backend
        Utils["Business Logic\n(Utils)"]:::backend
        Sockets["WebSocket Server\n(Socket.io)"]:::backend
        PluginLoader["Plugin Loader\n(ASSETS/plugins)"]:::backend
        Localization["Localization\n(locales/*.json)"]:::backend
    end

    %% Storage Layer
    subgraph "File System Storage"
        direction TB
        Config["Config File\n(config.json)"]:::storage
        Projects["Projects & Rundowns\n(DATAROOT)"]:::storage
        Templates["Template Files\n(ASSETS/templates)"]:::storage
        Media["Media Assets\n(ASSETS/media)"]:::storage
        PluginsFS["Plugin System\n(ASSETS/plugins)"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        CasparCG["CasparCG"]:::external
        WebPlayer["Webplayer"]:::external
        OBS["OBS/vMix\n(Browser Source)"]:::external
    end

    %% Connections
    UI -->|HTTP| Server
    StaticAssets --> Server
    UI -->|WebSocket| Sockets
    Server -->|routes| Routes
    Routes -->|invoke| Utils
    Utils -->|fs I/O| Projects
    Utils -->|fs I/O| Config
    Utils -->|fs I/O| Templates
    Utils -->|fs I/O| Media
    Utils -->|load| PluginsFS
    Utils -->|load| Localization
    Utils -->|socket events| Sockets
    Sockets -->|push updates| UI
    Server -->|/renderer| RendererClient
    RendererClient -->|consume| OBS
    Utils -->|playout API| CasparCG
    Utils -->|playout API| WebPlayer
    PluginLoader -->|register| Server
    PluginLoader -->|extend| UI

    %% Click Events - Backend Entry
    click Server "https://github.com/tuomoku/spx-gc/blob/master/server.js"
    click Config "https://github.com/tuomoku/spx-gc/blob/master/config.json"
    click Routes "https://github.com/tuomoku/spx-gc/blob/master/routes/routes-application.js"
    click Routes "https://github.com/tuomoku/spx-gc/blob/master/routes/routes-api.js"
    click Routes "https://github.com/tuomoku/spx-gc/blob/master/routes/routes-api-v1.js"
    click Routes "https://github.com/tuomoku/spx-gc/blob/master/routes/routes-casparcg.js"
    click Routes "https://github.com/tuomoku/spx-gc/blob/master/routes/routes-osc.js"
    click Routes "https://github.com/tuomoku/spx-gc/blob/master/routes/routes-osc-disabled.js"
    click Routes "https://github.com/tuomoku/spx-gc/blob/master/routes/routes-webplayer.js"
    click Utils "https://github.com/tuomoku/spx-gc/blob/master/utils/api-handlers.js"
    click Utils "https://github.com/tuomoku/spx-gc/blob/master/utils/spx_server_functions.js"
    click Utils "https://github.com/tuomoku/spx-gc/blob/master/utils/spx_getconf.js"
    click Utils "https://github.com/tuomoku/spx-gc/blob/master/utils/spx_auth.js"
    click Utils "https://github.com/tuomoku/spx-gc/blob/master/utils/logger.js"
    click Sockets "https://github.com/tuomoku/spx-gc/blob/master/utils/sockets.js"
    click SocketClient "https://github.com/tuomoku/spx-gc/blob/master/static/js/socket.io.js"
    click SocketClient "https://github.com/tuomoku/spx-gc/blob/master/static/renderer/js/socket.io.js"
    click UI "https://github.com/tuomoku/spx-gc/tree/master/views/layouts/"
    click UI "https://github.com/tuomoku/spx-gc/tree/master/views/partials/"
    click UI "https://github.com/tuomoku/spx-gc/blob/master/views/view-*.handlebars"
    click UI "https://github.com/tuomoku/spx-gc/tree/master/views/_old/"
    click RendererClient "https://github.com/tuomoku/spx-gc/blob/master/views/view-renderer.handlebars"
    click StaticAssets "https://github.com/tuomoku/spx-gc/tree/master/static/css/"
    click StaticAssets "https://github.com/tuomoku/spx-gc/tree/master/static/js/"
    click StaticAssets "https://github.com/tuomoku/spx-gc/tree/master/static/img/"
    click Projects "https://github.com/tuomoku/spx-gc/tree/master/DATAROOT/"
    click Templates "https://github.com/tuomoku/spx-gc/tree/master/ASSETS/templates/"
    click Media "https://github.com/tuomoku/spx-gc/tree/master/ASSETS/media/"
    click PluginsFS "https://github.com/tuomoku/spx-gc/tree/master/ASSETS/plugins/"
    click Localization "https://github.com/tuomoku/spx-gc/tree/master/locales/"
    click CasparCG "https://github.com/tuomoku/spx-gc/blob/master/utils/playout_casparCG.js"
    click WebPlayer "https://github.com/tuomoku/spx-gc/blob/master/utils/playout_webplayer.js"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0055AA,color:#003366;
    classDef backend fill:#DFFFD0,stroke:#228B22,color:#006400;
    classDef storage fill:#EEEEEE,stroke:#888888,color:#333333;
    classDef external fill:#FFE5CC,stroke:#FF8C00,color:#CC5500;
```
