scoreko-electron-dev/docs/refactor/PHASE_1_SUMMARY.md

Phase 1 Summary

Scope

Executed the architecture base refactor only. The change keeps the Electron plus local NodeCG product model intact and does not add a renderer, preload, or IPC layer.

Documentation used as source of truth:

• docs/refactor/ARCHITECTURE_AUDIT.md
• docs/refactor/ARCHITECTURE_RULES.md
• docs/refactor/TARGET_ARCHITECTURE.md
• docs/refactor/MIGRATION_PLAN.md
• docs/refactor/SESSION_HANDOFF.md

Completed

• Split the Electron entrypoint into a thin src/main/main.ts and explicit bootstrap logic in src/main/app/bootstrap.ts.
• Added src/main/app/application-controller.ts to own startup, activation, update scheduling, and shutdown coordination.
• Added src/main/app/paths.ts for pure root path, userData path, NodeCG runtime path, and dashboard URL construction.
• Added src/main/app/shutdown-service.ts so repeated shutdown requests reuse one stop operation.
• Renamed window ownership toward the target architecture:
  • src/main/windows/window-service.ts
  • src/main/windows/navigation-policy.ts
• Moved logging to src/main/logging/logger.ts.
• Extracted process-tree termination to src/main/nodecg/platform-process-killer.ts.
• Normalized imports away from old window-factory, navigation-security, and errors/logger paths.
• Made BrowserWindow security settings explicit:
  • nodeIntegration: false
  • contextIsolation: true
  • sandbox: true
  • webSecurity: true
  • devtools controlled by development mode
  • permissions denied by default
• Added architecture-base tests for:
  • path and URL helpers
  • application startup ordering
  • packaged relaunch after runtime installation
  • activation before readiness
  • shutdown idempotency
  • platform process killing

Intentionally Not Changed

• No UX changes.
• No custom renderer.
• No preload script.
• No IPC layer.
• No packaging changes.
• No update-manager rewrite.
• No complex NodeCG lifecycle rewrite.
• No change to the managed runtime location under Electron userData.
• No change to preservation of cfg, db, and logs.
• No change to launching NodeCG with ELECTRON_RUN_AS_NODE.

Compatibility Notes

• Startup still prepares the managed NodeCG runtime before launching NodeCG.
• Packaged first-run runtime installation still relaunches before NodeCG starts.
• Loading and main windows are still created before NodeCG readiness so the startup experience remains equivalent.
• Dashboard loading remains gated behind NodeCG readiness.
• Update checks are still scheduled only after the main window is shown.
• Shutdown remains idempotent and still stops the NodeCG process tree.
• macOS-style activation now routes through the controller so dashboard loading cannot bypass readiness.

Verification

Commands run successfully:

npm run typecheck
npm test
npm run lint

Current test result:

52 tests passing

Import/security sanity search:

rg -n "navigation-security|window-factory|errors/logger|preload|ipcRenderer|ipcMain|nodeIntegration:\s*true|webSecurity:\s*false|any\b" src docs/refactor

Result:

• No legacy imports or unsafe Electron settings remain in src.
• Remaining matches are source-of-truth documentation references only.