scoreko-electron-dev/docs/architecture.md

Main Process Architecture

This document breaks down how the Electron main process is structured and what happens when the app launches.

Startup Flow

When a user opens Scoreko, the app goes through a precise sequence to ensure NodeCG starts reliably:

1. Configuration: src/main/main.ts kicks things off by loading appConfig via config/runtime-config.ts.
2. Runtime Provisioning: The app checks the user's AppData directory. If the packaged NodeCG runtime is missing or outdated, it extracts a fresh copy (nodecg/runtime-provisioner.ts).
3. Window Creation: The initial windows (like the loading screen) are instantiated via windows/window-factory.ts.
4. NodeCG Boot: nodecg/process-manager.ts spawns the NodeCG process in the background.
5. Readiness Check: The app continuously polls NodeCG until the HTTP server responds. Once ready, it transitions the UI from the loading screen to the main dashboard.
6. Update Check: If updates are enabled, the app checks the configured Gitea endpoint in the background to see if a newer version is available.
7. Graceful Shutdown: When the user closes the app, it triggers a unified teardown sequence to cleanly kill the NodeCG child process, preventing zombie processes from lingering in the background.

Core Modules

Here is where the heavy lifting happens:

• config/runtime-config.ts: Handles environment variables and defaults.
• nodecg/runtime-provisioner.ts: Manages copying the NodeCG runtime out of the read-only Electron package into the writable user data folder.
• nodecg/process-manager.ts: Handles starting, polling, and killing the NodeCG server. It also validates ports and permissions before launching.
• updates/update-manager.ts: Coordinates the Gitea update flow (checking versions, downloading installers, prompting the user).
• windows/window-factory.ts: Centralizes window configuration and security defaults.
• windows/navigation-security.ts: Intercepts navigation events to block unauthorized domains and safely hand off external links (like docs or emails) to the user's default browser.
• errors/error-presenter.ts & errors/logger.ts: Manages structured logging (electron-log) and displaying the fallback error screen if boot fails.