# clockley/ejaxmediasystem architecture

> Architecture diagram of the GitHub repository clockley/ejaxmediasystem, 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/ejaxmediasystem
- Repository: https://github.com/clockley/ejaxmediasystem

## Overview

1. **Overall shape**
   - This is an **Electron desktop application** with a **dual-window architecture**: one window is the operator/control surface, and a separate window is the clean presentation surface shown on the selected display.

2. **Electron process boundary**
   - The top-level Node/Electron entry point is likely `src/app.js`, which coordinates window creation, lifecycle, and IPC.
   - The repo is split into **main-process orchestration** and **renderer-side UI logic**, with preload scripts bridging the two.

3. **Control window**
   - The control/management UI appears to live in `src/index.html` + `src/main.mjs` + `src/main.css`.
   - This window is where an operator selects media, configures playback, chooses the presentation display, and controls state such as looping or switching content.

4. **Presentation window**
   - The dedicated output/display window is implemented by `src/media.html` + `src/media.mjs` with `src/media_preload.js`.
   - Its job is to render the actual content cleanly, without the management controls, so it can be projected or shown on a second monitor.

5. **Playback subsystem**
   - Media playback logic is separated into reusable modules such as `src/streamPlayer.mjs` and `src/audioFx.mjs`.
   - The README’s feature set indicates support for **local audio/video**, **images**, and **YouTube live streams**, so this layer is the core media pipeline feeding the presentation window.

6. **Content switching and display management**
   - `src/switcher.js` and `src/settings.mjs` suggest a small coordination layer for choosing the active display/window behavior and remembering configuration.
   - `src/queue_switch_dialog.html` + `src/queue_switch_dialog_preload.mjs` implies there is a modal or helper UI for switching queued items or changing the active presentation target.

7. **Bible/scripture subsystem**
   - The repo contains a separate `bibleBackend/` directory with a **Go module** and a bundled **SQLite database** (`bible-sqlite.db`), which strongly suggests an embedded scripture lookup service or offline Bible data source.
   - The `src/Bible.mjs` module likely consumes that data source and provides scripture text to the UI or presentation layer.

8. **Go/WebAssembly asset**
   - `src/main.wasm` and `src/wasm_exec.js` indicate that at least part of the app’s logic is compiled to **WebAssembly from Go** and loaded by the Electron renderers.
   - That means the app likely uses a mixed model: Electron/JavaScript for UI and a Go-derived WASM component for some domain logic or data access.

9. **Preload and IPC boundary**
   - Preload files such as `src/app_preload.mjs`, `src/help_preload.mjs`, `src/media_preload.js`, and `src/queue_switch_dialog_preload.mjs` show a deliberate **sandbox boundary** between renderer code and Electron APIs.
   - This is the main integration seam: UI modules talk to the main process through exposed preload APIs rather than direct Node access.

10. **Auxiliary windows and docs**
   - `src/help.html` and `src/about.html` are separate static UI surfaces, likely opened as dialog-style windows.
   - `src/dev-profiler.mjs` suggests development-time instrumentation or debugging support.

11. **Static assets and presentation styling**
   - `fonts/Adwaita/` and `src/main.css` show the UI has bundled fonts and custom styling, which matters because the presentation window must look polished and consistent across platforms.

12. **Build and packaging**
   - The repo uses **Yarn/Node tooling** (`package.json`, `.yarnrc.yml`) and a `Makefile`/`BUILD.md` for build orchestration.
   - `build-scripts/embed-css.ps1` indicates a packaging step that embeds or transforms CSS for distribution.
   - The GitHub Actions workflow is currently focused on linting (`eslint.yml`), implying CI checks code quality rather than running a full backend service.

13. **Runtime and deployment model**
   - The application is cross-platform for **Windows and Linux**, distributed as an installer/AppImage per the README.
   - At runtime, everything runs locally on the user’s machine: Electron windows, local playback, local settings, and the embedded Bible database/backend. External network use appears limited to features like YouTube live streaming.

14. **How the data flows**
   - Operator input enters the control window → IPC/preload passes commands to the Electron main process → main process updates state and tells the media window what to render/play → media modules perform the actual playback/display.
   - Bible/content data is likely fetched from the local Go/SQLite backend or WASM module and then injected into the presentation UI when needed.

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

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_electron["Electron app"]
  node_n_app["App main<br/>electron main<br/>[app.js]"]
  node_n_app_preload["App bridge<br/>preload<br/>[app_preload.mjs]"]
  node_n_control_ui["Control window<br/>renderer ui<br/>[index.html]"]
  node_n_control_logic["Control logic<br/>renderer logic<br/>[main.mjs]"]
  node_n_control_style["Control style<br/>css<br/>[main.css]"]
  node_n_switcher["Display switcher<br/>coordination<br/>[switcher.js]"]
  node_n_settings["Settings<br/>state<br/>[settings.mjs]"]
  node_n_queue_dialog["Queue dialog<br/>renderer dialog"]
  node_n_queue_preload["Queue bridge<br/>preload"]
end

subgraph group_grp_media["Playback"]
  node_n_media_ui["Media window<br/>renderer ui<br/>[media.html]"]
  node_n_media_logic["Media logic<br/>renderer logic<br/>[media.mjs]"]
  node_n_media_preload["Media bridge<br/>preload<br/>[media_preload.js]"]
  node_n_stream_player["Stream player<br/>playback engine<br/>[streamPlayer.mjs]"]
  node_n_audio_fx["Audio FX<br/>audio processing<br/>[audioFx.mjs]"]
end

subgraph group_grp_bible["Bible backend"]
  node_n_bible_ui["Bible module<br/>scripture access<br/>[Bible.mjs]"]
  node_n_bible_backend["Bible backend<br/>go service<br/>[main.go]"]
  node_n_bible_db[("Bible DB<br/>sqlite data<br/>[bible-sqlite.db]")]
end

subgraph group_grp_build["Build assets"]
  node_n_wasm["WASM runtime<br/>go wasm<br/>[main.wasm]"]
  node_n_wasm_exec["WASM exec<br/>runtime shim<br/>[wasm_exec.js]"]
  node_n_build["Build scripts<br/>packaging<br/>[embed-css.ps1]"]
  node_n_fonts["Bundled fonts<br/>asset"]
end

node_n_app -->|"exposes APIs"| node_n_app_preload
node_n_app -->|"creates"| node_n_control_ui
node_n_app -->|"creates"| node_n_media_ui
node_n_app -->|"opens"| node_n_queue_dialog
node_n_app -->|"coordinates"| node_n_switcher
node_n_app -->|"loads"| node_n_settings
node_n_control_ui -->|"implements"| node_n_control_logic
node_n_control_logic -->|"uses bridge"| node_n_app_preload
node_n_control_logic -->|"selects display"| node_n_switcher
node_n_control_logic -->|"updates"| node_n_settings
node_n_control_ui -->|"styled by"| node_n_control_style
node_n_queue_dialog -->|"uses bridge"| node_n_queue_preload
node_n_media_ui -->|"implements"| node_n_media_logic
node_n_media_logic -->|"uses bridge"| node_n_media_preload
node_n_media_logic -->|"plays"| node_n_stream_player
node_n_media_logic -->|"processes audio"| node_n_audio_fx
node_n_media_logic -->|"renders scripture"| node_n_bible_ui
node_n_stream_player -->|"feeds"| node_n_audio_fx
node_n_bible_ui -->|"queries"| node_n_bible_backend
node_n_bible_backend -->|"reads"| node_n_bible_db
node_n_media_logic -->|"loads"| node_n_wasm
node_n_wasm -->|"requires"| node_n_wasm_exec
node_n_build -->|"packages"| node_n_control_style
node_n_build -->|"bundles"| node_n_fonts

click node_n_app "https://github.com/clockley/ejaxmediasystem/blob/master/src/app.js"
click node_n_app_preload "https://github.com/clockley/ejaxmediasystem/blob/master/src/app_preload.mjs"
click node_n_control_ui "https://github.com/clockley/ejaxmediasystem/blob/master/src/index.html"
click node_n_control_logic "https://github.com/clockley/ejaxmediasystem/blob/master/src/main.mjs"
click node_n_control_style "https://github.com/clockley/ejaxmediasystem/blob/master/src/main.css"
click node_n_switcher "https://github.com/clockley/ejaxmediasystem/blob/master/src/switcher.js"
click node_n_settings "https://github.com/clockley/ejaxmediasystem/blob/master/src/settings.mjs"
click node_n_queue_dialog "https://github.com/clockley/ejaxmediasystem/blob/master/src/queue_switch_dialog.html"
click node_n_queue_preload "https://github.com/clockley/ejaxmediasystem/blob/master/src/queue_switch_dialog_preload.mjs"
click node_n_media_ui "https://github.com/clockley/ejaxmediasystem/blob/master/src/media.html"
click node_n_media_logic "https://github.com/clockley/ejaxmediasystem/blob/master/src/media.mjs"
click node_n_media_preload "https://github.com/clockley/ejaxmediasystem/blob/master/src/media_preload.js"
click node_n_stream_player "https://github.com/clockley/ejaxmediasystem/blob/master/src/streamPlayer.mjs"
click node_n_audio_fx "https://github.com/clockley/ejaxmediasystem/blob/master/src/audioFx.mjs"
click node_n_bible_ui "https://github.com/clockley/ejaxmediasystem/blob/master/src/Bible.mjs"
click node_n_bible_backend "https://github.com/clockley/ejaxmediasystem/blob/master/bibleBackend/main.go"
click node_n_bible_db "https://github.com/clockley/ejaxmediasystem/blob/master/bibleBackend/bible-sqlite.db"
click node_n_wasm "https://github.com/clockley/ejaxmediasystem/blob/master/src/main.wasm"
click node_n_wasm_exec "https://github.com/clockley/ejaxmediasystem/blob/master/src/wasm_exec.js"
click node_n_build "https://github.com/clockley/ejaxmediasystem/blob/master/build-scripts/embed-css.ps1"
click node_n_fonts "https://github.com/clockley/ejaxmediasystem/tree/master/fonts/Adwaita"

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_n_app,node_n_app_preload,node_n_control_ui,node_n_control_logic,node_n_control_style,node_n_switcher,node_n_settings,node_n_queue_dialog,node_n_queue_preload toneBlue
class node_n_media_ui,node_n_media_logic,node_n_media_preload,node_n_stream_player,node_n_audio_fx toneAmber
class node_n_bible_ui,node_n_bible_backend,node_n_bible_db toneMint
class node_n_wasm,node_n_wasm_exec,node_n_build,node_n_fonts toneRose
```

## Components

### Electron app

Main Electron runtime, renderer windows, and preload bridge.

- [App main](https://github.com/clockley/ejaxmediasystem/blob/master/src/app.js): electron main · Top-level Electron entry that creates windows, wires lifecycle, and coordinates IPC. · `src/app.js`
- [App bridge](https://github.com/clockley/ejaxmediasystem/blob/master/src/app_preload.mjs): preload · Preload surface for the main control window. · `src/app_preload.mjs`
- [Control window](https://github.com/clockley/ejaxmediasystem/blob/master/src/index.html): renderer ui · Operator-facing window for selecting media, displays, and playback state. · `src/index.html`
- [Control logic](https://github.com/clockley/ejaxmediasystem/blob/master/src/main.mjs): renderer logic · Main control-window UI logic and state handling. · `src/main.mjs`
- [Control style](https://github.com/clockley/ejaxmediasystem/blob/master/src/main.css): css · Styling for the operator window. · `src/main.css`
- [Display switcher](https://github.com/clockley/ejaxmediasystem/blob/master/src/switcher.js): coordination · Coordinates active display selection and presentation-window behavior. · `src/switcher.js`
- [Settings](https://github.com/clockley/ejaxmediasystem/blob/master/src/settings.mjs): state · Persists and applies application configuration. · `src/settings.mjs`
- [Queue dialog](https://github.com/clockley/ejaxmediasystem/blob/master/src/queue_switch_dialog.html): renderer dialog · Auxiliary UI for queue switching or target changes. · `src/queue_switch_dialog.html`
- [Queue bridge](https://github.com/clockley/ejaxmediasystem/blob/master/src/queue_switch_dialog_preload.mjs): preload · Preload bridge for the queue switch dialog. · `src/queue_switch_dialog_preload.mjs`

### Playback

Media rendering and playback pipeline for the presentation surface.

- [Media window](https://github.com/clockley/ejaxmediasystem/blob/master/src/media.html): renderer ui · Clean presentation surface shown on the selected display. · `src/media.html`
- [Media logic](https://github.com/clockley/ejaxmediasystem/blob/master/src/media.mjs): renderer logic · Renderer code for presentation-window behavior and content display. · `src/media.mjs`
- [Media bridge](https://github.com/clockley/ejaxmediasystem/blob/master/src/media_preload.js): preload · Preload bridge for the presentation window. · `src/media_preload.js`
- [Stream player](https://github.com/clockley/ejaxmediasystem/blob/master/src/streamPlayer.mjs): playback engine · Core media playback for local files and live streams. · `src/streamPlayer.mjs`
- [Audio FX](https://github.com/clockley/ejaxmediasystem/blob/master/src/audioFx.mjs): audio processing · Audio effects and processing layer used by playback. · `src/audioFx.mjs`

### Bible backend

Embedded scripture data source and lookup service.

- [Bible module](https://github.com/clockley/ejaxmediasystem/blob/master/src/Bible.mjs): scripture access · Scripture lookup and presentation integration in the UI. · `src/Bible.mjs`
- [Bible backend](https://github.com/clockley/ejaxmediasystem/blob/master/bibleBackend/main.go): go service · Embedded Go module backing Bible/data access. · `bibleBackend/main.go`
- [Bible DB](https://github.com/clockley/ejaxmediasystem/blob/master/bibleBackend/bible-sqlite.db): sqlite data · Bundled offline scripture database. · `bibleBackend/bible-sqlite.db`

### Build assets

Tooling, packaging, fonts, and compiled runtime assets.

- [WASM runtime](https://github.com/clockley/ejaxmediasystem/blob/master/src/main.wasm): go wasm · Compiled Go/WebAssembly asset loaded by the Electron renderers. · `src/main.wasm`
- [WASM exec](https://github.com/clockley/ejaxmediasystem/blob/master/src/wasm_exec.js): runtime shim · Go WebAssembly runtime support script. · `src/wasm_exec.js`
- [Build scripts](https://github.com/clockley/ejaxmediasystem/blob/master/build-scripts/embed-css.ps1): packaging · Packaging and asset-embedding automation. · `build-scripts/embed-css.ps1`
- [Bundled fonts](https://github.com/clockley/ejaxmediasystem/tree/master/fonts/Adwaita): asset · Packaged UI fonts used for consistent cross-platform rendering. · `fonts/Adwaita`

## Connections

- App main → App bridge: exposes APIs · Main process exposes controlled window APIs through preload.
- App main → Control window: creates · Creates the operator/control window.
- App main → Media window: creates · Creates the presentation window.
- App main → Queue dialog: opens · Opens the queue-switch helper dialog.
- App main → Display switcher: coordinates · Main process delegates display and window switching.
- App main → Settings: loads · Reads and applies persisted configuration.
- Control window → Control logic: implements · Control window markup is driven by its renderer logic.
- Control logic → App bridge: uses bridge · Control UI talks to Electron through preload APIs.
- Control logic → Display switcher: selects display · Operator actions update active display and window state.
- Control logic → Settings: updates · Control logic reads and writes settings.
- Control window → Control style: styled by · Operator surface uses bundled CSS.
- Queue dialog → Queue bridge: uses bridge · Dialog communicates with main process through preload.
- Media window → Media logic: implements · Presentation window markup is driven by renderer logic.
- Media logic → Media bridge: uses bridge · Presentation renderer uses a constrained preload API.
- Media logic → Stream player: plays · Media window delegates actual playback to the stream player.
- Media logic → Audio FX: processes audio · Playback can be shaped by audio effects.
- Media logic → Bible module: renders scripture · Bible content is surfaced in the presentation UI.
- Stream player → Audio FX: feeds · Playback engine passes audio through processing.
- Bible module → Bible backend: queries · Scripture module consumes the embedded backend.
- Bible backend → Bible DB: reads · Go backend is backed by the bundled SQLite data.
- Media logic → WASM runtime: loads · Renderer loads the Go-compiled WASM asset where needed.
- WASM runtime → WASM exec: requires · WASM asset depends on the Go runtime shim.
- Build scripts → Control style: packages · Build automation can embed or transform CSS for distribution.
- Build scripts → Bundled fonts: bundles · Packaging includes application fonts.
