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