# churchapps/freeshow architecture

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

- Interactive diagram: https://gitdiagram.com/churchapps/freeshow
- Repository: https://github.com/churchapps/freeshow

## Overview

##### Project type and purpose
- FreeShow is a full-stack, cross-platform desktop application built on the Electron framework with multiple embedded micro-frontends (Svelte apps) served as HTTP endpoints. It provides slide-show creation/editing, stage display, remote control, camera preview, and output streaming.

##### File structure
- Top-level “src/electron” folder holds the Electron main process code (business logic, hardware/OS integration, local storage, embedded servers).
- “src/frontend” is the main UI renderer (Svelte).
- “src/server” holds four separate Svelte micro-frontends (cam, controller, remote, stage, output_stream) each with its own HTTP endpoint and static assets.
- Shared modules: “src/common”, “src/types” define cross-cutting types, protocols (protobuf), utilities.
- Config/build scripts for packaging (rollup, vite, snapcraft, electron-builder).

##### README
- Confirms Electron + Svelte, packaging for Windows/Linux/Mac, features: stage display, remote via browser, cloud sync, NDI, audio/MIDI/OSC integrations.

##### Main components
a. Electron Host (node.js process)
- Business logic modules (audio, capture, cloud, data, output, NDI, timecode)
- IPC channels (to all renderer processes)
- Embedded HTTP servers for:
– Stage display (src/server/stage)
– Remote control (src/server/remote)
– Camera view (src/server/cam)
– Controller UI (src/server/controller)
– Output stream (src/server/output_stream)
- Local storage (JSON/db) via data modules
- External integrations: OAuth2-based content providers, Google Drive API, ChurchApps sync
- Network I/O: NDI in/out, OSC, WebSockets

b. Renderer processes (Svelte UIs)
– Main desktop UI (src/frontend) communicates over Electron IPC
– Each micro-frontend served by HTTP: stage, remote, cam, controller, output_stream
– External browsers or devices connect to these endpoints (via WebSocket for state updates)

c. External services
– Cloud APIs (PlanningCenter, ChurchApps, Dropbox/Google Drive, Pixabay/Unsplash)
– NDI network devices
– MIDI / OSC hardware

##### Architectural patterns & design principles
- Client–Server / micro-frontend: multiple independent UIs served by one host
- Event-driven: all modules communicate via IPC or pub/sub (WebSocket)
- Layered separation: UI layer (Svelte), application layer (Electron main), infrastructure layer (OS, network, storage)
- Extensible plugin-style content providers: base class + concrete providers

##### Relevant technologies/frameworks
- Electron + Node.js + TypeScript
- Svelte (multiple apps)
- Vite & Rollup for bundling
- Protobuf for internal message definitions
- Snapcraft / electron‐builder for packaging
- Playwright for e2e testing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Subgraphs
    subgraph "Electron Host" 
        direction TB
        ElectronMain["Electron Main Process"]:::backend
        PreloadScript["Preload Script"]:::backend
        IPCChannels["IPC Channels"]:::backend
        subgraph "Business Logic Modules"
            direction TB
            AudioModule["Audio Module"]:::backend
            CaptureModule["Capture Module"]:::backend
            CloudModule["Cloud/Sync Module"]:::backend
            DataModule["Local Data & Storage"]:::backend
            OutputModule["Output Module"]:::backend
            NDIModule["NDI Integration"]:::backend
            TimecodeModule["Timecode Module"]:::backend
        end
        ServersDef["Embedded HTTP Server Definitions"]:::backend
    end

    subgraph "Frontend UIs"
        direction TB
        DesktopUI["Main Desktop UI"]:::ui
    end

    subgraph "Embedded Servers"
        direction TB
        StageServer["Stage Server (port 5000)"]:::backend
        RemoteServer["Remote Control Server (port 5001)"]:::backend
        CamServer["Camera Preview Server (port 5002)"]:::backend
        ControllerServer["Controller UI Server (port 5003)"]:::backend
        OutputStreamServer["Output Stream Server (port 5004)"]:::backend
    end

    subgraph "Storage"
        direction TB
        LocalStorage["Local JSON/DB Storage"]:::storage
    end

    subgraph "External Integrations"
        direction TB
        CloudAPIs["Cloud APIs (OAuth2)"]:::external
        NDIDevices["NDI Devices"]:::external
        OSCHardware["OSC/MIDI Hardware"]:::external
    end

    subgraph "Shared Modules"
        direction TB
        SharedUtils["Shared Utilities"]:::backend
        SharedTypes["Type Definitions & Protobuf"]:::backend
    end

    %% Connections
    DesktopUI <-->|"IPC"| PreloadScript
    PreloadScript -->|"IPC"| ElectronMain
    ElectronMain -->|"uses"| AudioModule
    ElectronMain -->|"uses"| CaptureModule
    ElectronMain -->|"uses"| CloudModule
    ElectronMain -->|"uses"| DataModule
    ElectronMain -->|"uses"| OutputModule
    ElectronMain -->|"uses"| NDIModule
    ElectronMain -->|"uses"| TimecodeModule
    ElectronMain -->|"serves UIs"| ServersDef
    ServersDef --> StageServer
    ServersDef --> RemoteServer
    ServersDef --> CamServer
    ServersDef --> ControllerServer
    ServersDef --> OutputStreamServer

    StageServer <-->|"HTTP/WebSocket"| ExternalClients1(("Browser/Mobile Clients"))
    RemoteServer <-->|"HTTP/WebSocket"| ExternalClients1
    CamServer <-->|"HTTP/WebSocket"| ExternalClients1
    ControllerServer <-->|"HTTP/WebSocket"| ExternalClients1
    OutputStreamServer <-->|"HTTP/WebSocket"| ExternalClients1

    ElectronMain -->|"reads/writes"| LocalStorage
    ElectronMain -->|"HTTPS"| CloudAPIs
    ElectronMain -->|"NDI Stream"| NDIDevices
    ElectronMain -->|"OSC/MIDI"| OSCHardware

    ElectronMain --> SharedUtils
    ElectronMain --> SharedTypes
    DesktopUI --> SharedUtils
    DesktopUI --> SharedTypes

    %% Click Events
    click ElectronMain "https://github.com/churchapps/freeshow/blob/main/src/electron/index.ts"
    click PreloadScript "https://github.com/churchapps/freeshow/blob/main/src/electron/preload.ts"
    click IPCChannels "https://github.com/churchapps/freeshow/blob/main/src/electron/IPC/main.ts"
    click AudioModule "https://github.com/churchapps/freeshow/tree/main/src/electron/audio"
    click CaptureModule "https://github.com/churchapps/freeshow/tree/main/src/electron/capture"
    click CloudModule "https://github.com/churchapps/freeshow/tree/main/src/electron/cloud"
    click DataModule "https://github.com/churchapps/freeshow/tree/main/src/electron/data"
    click OutputModule "https://github.com/churchapps/freeshow/tree/main/src/electron/output"
    click NDIModule "https://github.com/churchapps/freeshow/tree/main/src/electron/ndi"
    click TimecodeModule "https://github.com/churchapps/freeshow/tree/main/src/electron/timecode"
    click ServersDef "https://github.com/churchapps/freeshow/blob/main/src/electron/servers.ts"
    click DesktopUI "https://github.com/churchapps/freeshow/tree/main/src/frontend"
    click SharedUtils "https://github.com/churchapps/freeshow/tree/main/src/common"
    click SharedTypes "https://github.com/churchapps/freeshow/tree/main/src/types"
    click StageServer "https://github.com/churchapps/freeshow/tree/main/src/server/stage"
    click RemoteServer "https://github.com/churchapps/freeshow/tree/main/src/server/remote"
    click CamServer "https://github.com/churchapps/freeshow/tree/main/src/server/cam"
    click ControllerServer "https://github.com/churchapps/freeshow/tree/main/src/server/controller"
    click OutputStreamServer "https://github.com/churchapps/freeshow/tree/main/src/server/output_stream"

    %% Styles
    classDef ui fill:#cfe2f3,stroke:#084298
    classDef backend fill:#d1e7dd,stroke:#0f5132
    classDef storage fill:#fff3cd,stroke:#664d03
    classDef external fill:#e2e3e5,stroke:#6c757d
```
