# clockley/emsmediasystem architecture

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

- Interactive diagram: https://gitdiagram.com/clockley/emsmediasystem
- Repository: https://github.com/clockley/emsmediasystem

## Overview

1. **Top-level shape**
   - This repo is an **Electron desktop application** for media presentation, not a web app.
   - The product is split into a **control/management window** and a separate **presentation window** shown on a selected display.

2. **Electron entrypoint and app shell**
   - The core runtime is in `src/main.mjs`, which is the Electron main-process entry.
   - It likely owns app startup, window creation, display selection, and coordination between the two windows.
   - `src/app.js` appears to hold shared application-level behavior or bootstrapping logic used by the renderer side.

3. **Dual-window architecture**
   - `src/index.html` is the main control surface.
   - `src/media.html` is the clean presentation surface for the audience.
   - The architecture is intentionally separated so operators manage media in one window while content appears distraction-free in another.

4. **Renderer-side modules**
   - The UI and interaction logic are split across ES modules such as:
     - `src/media.mjs` for the presentation window
     - `src/app.js` / `src/settings.mjs` for control state and configuration
     - `src/streamPlayer.mjs` for stream/video playback behavior
     - `src/audioFx.mjs` for audio processing or effects
     - `src/switcher.js` and `src/queue_switch_dialog.html` for switching/queue-related UI
   - These modules form the application logic layer inside the renderer process.

5. **Secure preload boundaries**
   - Multiple preload scripts exist:
     - `src/app_preload.mjs`
     - `src/help_preload.mjs`
     - `src/media_preload.js`
     - `src/queue_switch_dialog_preload.mjs`
   - This indicates context-isolated Electron windows, where the preload layer exposes a narrow IPC/API surface to the HTML pages.
   - Architecturally, this is the boundary between privileged Electron capabilities and the UI code.

6. **Media playback responsibilities**
   - The app supports **local video/audio**, **images**, and **YouTube live stream integration** per the README.
   - `streamPlayer.mjs` is the likely media controller for streaming and playback orchestration.
   - `audioFx.mjs` suggests optional audio enhancement/filtering integrated into playback.

7. **Presentation output and display selection**
   - The system includes display targeting for the presentation window, so the control window and output window can be placed on different monitors.
   - `src/switcher.js` and the queue switch dialog imply operator-driven switching between queued media items or sources.
   - This makes the output pipeline: operator action in control window -> IPC/state update -> presentation window updates media shown on the selected display.

8. **Bible-related subsystem**
   - There is a separate `bibleBackend/` directory with:
     - `main.go`
     - `go.mod` / `go.sum`
     - `bible-sqlite.db`
   - This is a distinct **Go + SQLite** subsystem, likely for local scripture lookup or content retrieval used by the app’s Bible features.
   - It acts as a data-backed service/engine rather than part of the Electron UI itself.

9. **WASM/Go runtime in the renderer**
   - `src/main.wasm` and `src/wasm_exec.js` indicate a Go WebAssembly component bundled into the frontend runtime.
   - That suggests some logic is executed in-browser/renderer via Go WASM, likely for computational or data-access tasks that need to run inside the Electron renderer environment.
   - The architecture therefore includes both native Electron code and embedded Go runtime artifacts.

10. **Static UI pages and auxiliary windows**
   - `src/about.html`, `src/help.html`, and their preload scripts indicate small dedicated utility windows or dialogs.
   - These are separate UI entrypoints rather than overlays inside the main app shell.

11. **Assets and styling**
   - `src/main.css` and the `fonts/Adwaita/` directory provide the visual presentation layer.
   - The styling is packaged with the app so the control and presentation windows render consistently across platforms.

12. **Build and packaging**
   - The repository includes `package.json`, `Makefile`, `.github/workflows/eslint.yml`, and `BUILD.md`, indicating a packaged desktop build pipeline.
   - `build-scripts/embed-css.ps1` suggests part of the build process transforms or embeds CSS into the distributed app.
   - The presence of release instructions for Windows and Linux AppImage in the README confirms cross-platform desktop distribution.

13. **Overall data flow**
   - User interacts with the control window.
   - Renderer logic updates app state and issues IPC through preload boundaries.
   - The Electron main process coordinates the presentation window and display choice.
   - Media content is rendered in the separate presentation window, while optional Bible data comes from the Go/SQLite subsystem and any Go WASM component.

14. **Architecture summary for diagramming**
   - A good diagram would show:
     - **Electron main process** at the center
     - **Control renderer** and **presentation renderer** as two separate frontends
     - **Preload/IPC bridges** between them and main
     - **Go + SQLite Bible backend** as a local data subsystem
     - **Go WASM runtime** as an embedded runtime artifact used by the renderer
     - **Static assets/fonts/build tooling** as supporting infrastructure

Main entry points: [`src/main.mjs`](https://github.com/clockley/emsmediasystem/blob/master/src/main.mjs) (Main process), [`src/index.html`](https://github.com/clockley/emsmediasystem/blob/master/src/index.html) (Control UI), [`src/media.html`](https://github.com/clockley/emsmediasystem/blob/master/src/media.html) (Presentation UI), [`src/app.js`](https://github.com/clockley/emsmediasystem/blob/master/src/app.js) (App logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Electron app"]
  node_n1["Main process<br/>electron main<br/>[main.mjs]"]
end

subgraph group_g2["Renderer UI"]
  node_n2["Control UI<br/>control shell<br/>[index.html]"]
  node_n3["Presentation UI<br/>presentation shell<br/>[media.html]"]
  node_n4["App logic<br/>renderer core<br/>[app.js]"]
  node_n5["Settings<br/>config state<br/>[settings.mjs]"]
  node_n6["Media runtime<br/>player logic<br/>[media.mjs]"]
  node_n7["Stream player<br/>playback engine<br/>[streamPlayer.mjs]"]
  node_n8["Audio FX<br/>audio processing<br/>[audioFx.mjs]"]
  node_n9["Switcher<br/>queue control<br/>[switcher.js]"]
  node_n10["Queue dialog<br/>switch dialog"]
  node_n11["About window<br/>utility page<br/>[about.html]"]
  node_n12["Help window<br/>utility page<br/>[help.html]"]
  node_n13["App preload<br/>preload bridge<br/>[app_preload.mjs]"]
  node_n14["Media preload<br/>preload bridge<br/>[media_preload.js]"]
  node_n15["Help preload<br/>preload bridge<br/>[help_preload.mjs]"]
  node_n16["Queue preload<br/>preload bridge"]
  node_n17["Bible bridge<br/>renderer module<br/>[Bible.mjs]"]
end

subgraph group_g3["Local data"]
  node_n18["Go backend<br/>go service<br/>[main.go]"]
  node_n19[("Bible DB<br/>sqlite data<br/>[bible-sqlite.db]")]
  node_n20["WASM runtime<br/>go wasm<br/>[main.wasm]"]
  node_n21["WASM loader<br/>runtime shim<br/>[wasm_exec.js]"]
end

subgraph group_g4["Support"]
  node_n22["Styles<br/>css theme<br/>[main.css]"]
  node_n23(("Fonts<br/>asset pack"))
  node_n24["Build scripts<br/>build tooling<br/>[embed-css.ps1]"]
end

node_n2 -->|"preload"| node_n13
node_n3 -->|"preload"| node_n14
node_n11 -->|"preload"| node_n15
node_n12 -->|"preload"| node_n15
node_n10 -->|"preload"| node_n16
node_n1 -->|"creates"| node_n2
node_n1 -->|"creates"| node_n3
node_n1 -->|"opens"| node_n11
node_n1 -->|"opens"| node_n12
node_n1 -->|"opens"| node_n10
node_n13 -->|"ipc"| node_n1
node_n14 -->|"ipc"| node_n1
node_n16 -->|"ipc"| node_n1
node_n4 -->|"reads/writes"| node_n5
node_n4 -->|"coordinates"| node_n9
node_n9 -->|"drives"| node_n10
node_n4 -->|"uses"| node_n17
node_n17 -->|"calls"| node_n18
node_n18 -->|"stores"| node_n19
node_n6 -->|"uses"| node_n7
node_n6 -->|"uses"| node_n8
node_n6 -->|"embeds"| node_n20
node_n20 -->|"runs with"| node_n21
node_n2 -->|"styled by"| node_n22
node_n3 -->|"styled by"| node_n22
node_n2 -->|"assets"| node_n23
node_n3 -->|"assets"| node_n23
node_n24 -->|"builds"| node_n22
node_n24 -->|"packages"| node_n2
node_n24 -->|"packages"| node_n3

click node_n1 "https://github.com/clockley/emsmediasystem/blob/master/src/main.mjs"
click node_n2 "https://github.com/clockley/emsmediasystem/blob/master/src/index.html"
click node_n3 "https://github.com/clockley/emsmediasystem/blob/master/src/media.html"
click node_n4 "https://github.com/clockley/emsmediasystem/blob/master/src/app.js"
click node_n5 "https://github.com/clockley/emsmediasystem/blob/master/src/settings.mjs"
click node_n6 "https://github.com/clockley/emsmediasystem/blob/master/src/media.mjs"
click node_n7 "https://github.com/clockley/emsmediasystem/blob/master/src/streamPlayer.mjs"
click node_n8 "https://github.com/clockley/emsmediasystem/blob/master/src/audioFx.mjs"
click node_n9 "https://github.com/clockley/emsmediasystem/blob/master/src/switcher.js"
click node_n10 "https://github.com/clockley/emsmediasystem/blob/master/src/queue_switch_dialog.html"
click node_n11 "https://github.com/clockley/emsmediasystem/blob/master/src/about.html"
click node_n12 "https://github.com/clockley/emsmediasystem/blob/master/src/help.html"
click node_n13 "https://github.com/clockley/emsmediasystem/blob/master/src/app_preload.mjs"
click node_n14 "https://github.com/clockley/emsmediasystem/blob/master/src/media_preload.js"
click node_n15 "https://github.com/clockley/emsmediasystem/blob/master/src/help_preload.mjs"
click node_n16 "https://github.com/clockley/emsmediasystem/blob/master/src/queue_switch_dialog_preload.mjs"
click node_n17 "https://github.com/clockley/emsmediasystem/blob/master/src/Bible.mjs"
click node_n18 "https://github.com/clockley/emsmediasystem/blob/master/bibleBackend/main.go"
click node_n19 "https://github.com/clockley/emsmediasystem/blob/master/bibleBackend/bible-sqlite.db"
click node_n20 "https://github.com/clockley/emsmediasystem/blob/master/src/main.wasm"
click node_n21 "https://github.com/clockley/emsmediasystem/blob/master/src/wasm_exec.js"
click node_n22 "https://github.com/clockley/emsmediasystem/blob/master/src/main.css"
click node_n23 "https://github.com/clockley/emsmediasystem/tree/master/fonts/Adwaita"
click node_n24 "https://github.com/clockley/emsmediasystem/blob/master/build-scripts/embed-css.ps1"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1 toneBlue
class node_n2,node_n3,node_n4,node_n5,node_n6,node_n7,node_n8,node_n9,node_n10,node_n11,node_n12,node_n13,node_n14,node_n15,node_n16,node_n17 toneAmber
class node_n18,node_n19,node_n20,node_n21 toneMint
class node_n22,node_n23,node_n24 toneRose
```

## Components

### Electron app

Main process and window coordination

- [Main process](https://github.com/clockley/emsmediasystem/blob/master/src/main.mjs): electron main · Creates windows, manages app lifecycle, and coordinates display/output · `src/main.mjs`

### Renderer UI

Control, presentation, and dialog entrypoints

- [Control UI](https://github.com/clockley/emsmediasystem/blob/master/src/index.html): control shell · Operator-facing app window and primary interaction surface · `src/index.html`
- [Presentation UI](https://github.com/clockley/emsmediasystem/blob/master/src/media.html): presentation shell · Clean audience-facing output window · `src/media.html`
- [App logic](https://github.com/clockley/emsmediasystem/blob/master/src/app.js): renderer core · Shared renderer behavior and app-level state · `src/app.js`
- [Settings](https://github.com/clockley/emsmediasystem/blob/master/src/settings.mjs): config state · Configuration and persisted UI/application settings · `src/settings.mjs`
- [Media runtime](https://github.com/clockley/emsmediasystem/blob/master/src/media.mjs): player logic · Presentation-side media orchestration and rendering logic · `src/media.mjs`
- [Stream player](https://github.com/clockley/emsmediasystem/blob/master/src/streamPlayer.mjs): playback engine · Handles stream and video playback behavior · `src/streamPlayer.mjs`
- [Audio FX](https://github.com/clockley/emsmediasystem/blob/master/src/audioFx.mjs): audio processing · Audio processing and effects used during playback · `src/audioFx.mjs`
- [Switcher](https://github.com/clockley/emsmediasystem/blob/master/src/switcher.js): queue control · Queue and source switching logic for operator actions · `src/switcher.js`
- [Queue dialog](https://github.com/clockley/emsmediasystem/blob/master/src/queue_switch_dialog.html): switch dialog · Dedicated UI for queue switching interactions · `src/queue_switch_dialog.html`
- [About window](https://github.com/clockley/emsmediasystem/blob/master/src/about.html): utility page · Small auxiliary about dialog/window · `src/about.html`
- [Help window](https://github.com/clockley/emsmediasystem/blob/master/src/help.html): utility page · Help/info window for the application · `src/help.html`
- [App preload](https://github.com/clockley/emsmediasystem/blob/master/src/app_preload.mjs): preload bridge · Preload API boundary for the main control window · `src/app_preload.mjs`
- [Media preload](https://github.com/clockley/emsmediasystem/blob/master/src/media_preload.js): preload bridge · Preload API boundary for the presentation window · `src/media_preload.js`
- [Help preload](https://github.com/clockley/emsmediasystem/blob/master/src/help_preload.mjs): preload bridge · Preload API boundary for the help window · `src/help_preload.mjs`
- [Queue preload](https://github.com/clockley/emsmediasystem/blob/master/src/queue_switch_dialog_preload.mjs): preload bridge · Preload API boundary for the queue switch dialog · `src/queue_switch_dialog_preload.mjs`
- [Bible bridge](https://github.com/clockley/emsmediasystem/blob/master/src/Bible.mjs): renderer module · Bible-related renderer integration and lookup logic · `src/Bible.mjs`

### Local data

Bible backend and embedded runtime artifacts

- [Go backend](https://github.com/clockley/emsmediasystem/blob/master/bibleBackend/main.go): go service · Local Go subsystem backing Bible/content features · `bibleBackend/main.go`
- [Bible DB](https://github.com/clockley/emsmediasystem/blob/master/bibleBackend/bible-sqlite.db): sqlite data · Local SQLite database used by the Bible backend · `bibleBackend/bible-sqlite.db`
- [WASM runtime](https://github.com/clockley/emsmediasystem/blob/master/src/main.wasm): go wasm · Go WebAssembly runtime artifact used in the renderer · `src/main.wasm`
- [WASM loader](https://github.com/clockley/emsmediasystem/blob/master/src/wasm_exec.js): runtime shim · JavaScript support for running Go WASM in the renderer · `src/wasm_exec.js`

### Support

Assets and build pipeline

- [Styles](https://github.com/clockley/emsmediasystem/blob/master/src/main.css): css theme · Shared application styling for all windows · `src/main.css`
- [Fonts](https://github.com/clockley/emsmediasystem/tree/master/fonts/Adwaita): asset pack · Bundled Adwaita font assets · `fonts/Adwaita`
- [Build scripts](https://github.com/clockley/emsmediasystem/blob/master/build-scripts/embed-css.ps1): build tooling · CSS embedding and release/build automation · `build-scripts/embed-css.ps1`

## Connections

- Control UI → App preload: preload · Control window loads its isolated bridge
- Presentation UI → Media preload: preload · Presentation window loads its isolated bridge
- About window → Help preload: preload · About window loads its bridge
- Help window → Help preload: preload · Help window loads its bridge
- Queue dialog → Queue preload: preload · Queue switch dialog loads its bridge
- Main process → Control UI: creates · Main process opens the control window
- Main process → Presentation UI: creates · Main process opens the presentation window
- Main process → About window: opens · Main process can open the about window
- Main process → Help window: opens · Main process can open the help window
- Main process → Queue dialog: opens · Main process can open the queue switch dialog
- App preload → Main process: ipc · Control UI communicates privileged actions through IPC
- Media preload → Main process: ipc · Presentation window receives coordination via IPC
- Queue preload → Main process: ipc · Queue dialog sends switch actions through IPC
- App logic → Settings: reads/writes · Renderer logic manages settings and application state
- App logic → Switcher: coordinates · App logic drives queue and switch operations
- Switcher → Queue dialog: drives · Switcher logic feeds the queue switch dialog
- App logic → Bible bridge: uses · Renderer app integrates Bible features
- Bible bridge → Go backend: calls · Bible renderer integration relies on the Go backend
- Go backend → Bible DB: stores · Go backend reads from local SQLite Bible data
- Media runtime → Stream player: uses · Presentation runtime delegates playback to stream player
- Media runtime → Audio FX: uses · Presentation runtime applies audio effects during playback
- Media runtime → WASM runtime: embeds · Renderer includes the Go WASM component
- WASM runtime → WASM loader: runs with · WASM code depends on the Go runtime shim
- Control UI → Styles: styled by · Control window uses shared styling
- Presentation UI → Styles: styled by · Presentation window uses shared styling
- Control UI → Fonts: assets · Control UI is packaged with bundled fonts
- Presentation UI → Fonts: assets · Presentation UI is packaged with bundled fonts
- Build scripts → Styles: builds · Build tooling embeds or packages CSS
- Build scripts → Control UI: packages · Build pipeline produces the control application
- Build scripts → Presentation UI: packages · Build pipeline produces the presentation application
