# Main process architecture

## Startup flow

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. In packaged builds, relaunches once after a fresh runtime install so NodeCG starts from a settled user-data runtime.
5. Starts NodeCG with `nodecg/process-manager.ts`.
6. Waits for HTTP readiness and shows loading -> main dashboard.
7. Checks the configured Gitea latest-release endpoint for optional updates.
8. On shutdown, runs a single graceful-stop flow to avoid orphan processes.

## Main modules

- `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`).

## Principles

- Mechanical refactors first.
- Incremental hardening with conservative fallback.
- Automated validation via `typecheck`, `build`, `test`, `doctor`, `lint`.