refactor: update security policies in window creation and enhance loading page CSP

docs/architecture.md

@@ -1,29 +1,27 @@
-# Main process architecture
+# Main Process Architecture
 
-## Startup flow
+This document breaks down how the Electron main process is structured and what happens when the app launches.
 
-1. `src/main/main.ts` loads `appConfig` from `config/runtime-config.ts`.
-2. Installs or refreshes the packaged NodeCG runtime in user data when needed (`nodecg/runtime-provisioner.ts`).
-3. Creates windows (`windows/window-factory.ts`).
-4. Starts NodeCG with `nodecg/process-manager.ts`.
-5. Waits for HTTP readiness and shows loading -> main dashboard.
-6. Checks the configured Gitea latest-release endpoint for optional updates.
-7. On shutdown, runs a single graceful-stop flow to avoid orphan processes.
+## Startup Flow
 
-## Main modules
+When a user opens Scoreko, the app goes through a precise sequence to ensure NodeCG starts reliably:
 
-- `config/runtime-config.ts`: read/validate env vars.
-- `nodecg/runtime-provisioner.ts`: install/refresh the managed runtime in the writable user data folder and report whether it changed.
-- `nodecg/process-manager.ts`: start, readiness, and stop for NodeCG; install/permission/port validation.
-- `updates/update-manager.ts`: optional Gitea release checks, installer download, and user-controlled install.
-- `updates/update-utils.ts`: release version comparison and installer asset selection.
-- `windows/window-factory.ts`: window creation and navigation policy.
-- `windows/navigation-security.ts`: internal navigation allowlist and safe external schemes.
-- `errors/error-presenter.ts`: fatal error presentation.
-- `errors/logger.ts`: structured logging (`info/warn/error/debug`).
+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.
 
-## Principles
+## Core Modules
 
-- Mechanical refactors first.
-- Incremental hardening with conservative fallback.
-- Automated validation via `typecheck`, `build`, `test`, `doctor`, `lint`.
+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.