mirror of
https://github.com/Pandipipas/scoreko-electron-dev.git
synced 2026-06-06 05:32:06 +00:00
feat: add comprehensive architecture documentation and migration plan for refactor sessions
This commit is contained in:
@@ -0,0 +1,190 @@
|
||||
# Session Handoff
|
||||
|
||||
## Context
|
||||
|
||||
This handoff captures the agreed architecture direction for future refactor sessions. Do not restart architectural discovery from zero unless the codebase has changed substantially.
|
||||
|
||||
The previous analysis concluded that the codebase is fundamentally healthy. The refactor should be controlled and incremental, focused on lifecycle, updater safety, process shutdown, and explicit Electron security.
|
||||
|
||||
## Current Technical State
|
||||
|
||||
Known validation from the prior analysis:
|
||||
|
||||
```text
|
||||
npm run typecheck
|
||||
npm test
|
||||
npm run lint
|
||||
```
|
||||
|
||||
All passed at that time, with 42 tests passing.
|
||||
|
||||
## Source Of Truth Documents
|
||||
|
||||
Use these documents in order:
|
||||
|
||||
1. `docs/refactor/ARCHITECTURE_AUDIT.md`
|
||||
2. `docs/refactor/ARCHITECTURE_RULES.md`
|
||||
3. `docs/refactor/TARGET_ARCHITECTURE.md`
|
||||
4. `docs/refactor/MIGRATION_PLAN.md`
|
||||
5. `docs/refactor/SESSION_HANDOFF.md`
|
||||
|
||||
## High-Level Project Model
|
||||
|
||||
This is an Electron wrapper around a local NodeCG runtime.
|
||||
|
||||
Important facts:
|
||||
|
||||
- The app lives mostly in Electron main.
|
||||
- There is no custom renderer.
|
||||
- There is no preload.
|
||||
- There is no meaningful IPC.
|
||||
- Electron starts NodeCG locally.
|
||||
- Electron loads dashboards from local HTTP origins.
|
||||
- Runtime provisioning happens under Electron `userData`.
|
||||
- NodeCG is launched through the Electron binary with `ELECTRON_RUN_AS_NODE`.
|
||||
|
||||
Do not treat the absence of IPC or preload as a missing feature. It is currently a desirable security property.
|
||||
|
||||
## Preserve These Behaviors
|
||||
|
||||
- Runtime stored under `userData`.
|
||||
- Relaunch after first runtime installation when required.
|
||||
- Preservation of `cfg`, `db`, and `logs`.
|
||||
- Use of `ELECTRON_RUN_AS_NODE`.
|
||||
- Waiting for NodeCG HTTP readiness before dashboard load.
|
||||
- Existing tests for config, provisioning, navigation, process management, and updates.
|
||||
- Minimal Electron surface.
|
||||
- No IPC unless required.
|
||||
|
||||
## Main Risks To Address
|
||||
|
||||
### Lifecycle
|
||||
|
||||
`main.ts` currently mixes:
|
||||
|
||||
- App configuration.
|
||||
- Runtime preparation.
|
||||
- Window handling.
|
||||
- NodeCG startup.
|
||||
- Readiness waiting.
|
||||
- Update scheduling.
|
||||
- Shutdown.
|
||||
|
||||
Refactor target:
|
||||
|
||||
- Introduce `ApplicationController`.
|
||||
- Add explicit lifecycle states.
|
||||
- Keep `main.ts` or `bootstrap.ts` thin.
|
||||
|
||||
### Activation
|
||||
|
||||
Current risk:
|
||||
|
||||
- macOS activation can recreate a window and load a dashboard without proving NodeCG readiness.
|
||||
|
||||
Refactor target:
|
||||
|
||||
- Route activation through the same readiness-aware controller as startup.
|
||||
|
||||
### Updater
|
||||
|
||||
Current risk:
|
||||
|
||||
- Remote JSON and asset URLs need stronger validation.
|
||||
- Download and install behavior should be separated.
|
||||
- Spanish text contains visible encoding corruption.
|
||||
|
||||
Refactor target:
|
||||
|
||||
- Rewrite updater internals in small modules.
|
||||
- Validate metadata.
|
||||
- Validate URLs.
|
||||
- Use safe temporary paths.
|
||||
- Fix encoding.
|
||||
|
||||
### Process Shutdown
|
||||
|
||||
Current risk:
|
||||
|
||||
- Windows process-tree termination uses `taskkill`.
|
||||
- It is low risk because the PID is numeric, but platform behavior should be isolated.
|
||||
|
||||
Refactor target:
|
||||
|
||||
- Add `platform-process-killer.ts`.
|
||||
- Keep platform-specific commands out of NodeCG lifecycle orchestration.
|
||||
|
||||
### Electron Security
|
||||
|
||||
Current strengths:
|
||||
|
||||
- `nodeIntegration: false`
|
||||
- `contextIsolation: true`
|
||||
- `sandbox: true`
|
||||
- No preload.
|
||||
- No IPC.
|
||||
|
||||
Refactor target:
|
||||
|
||||
- Add explicit `webSecurity: true`.
|
||||
- Add permission denial by default.
|
||||
- Add devtools policy by environment.
|
||||
- Keep navigation allowlisted.
|
||||
|
||||
## Recommended Next Session
|
||||
|
||||
Start with Phase 1 from `MIGRATION_PLAN.md`.
|
||||
|
||||
Immediate next work:
|
||||
|
||||
1. Add lifecycle tests around current behavior.
|
||||
2. Cover first-run relaunch behavior.
|
||||
3. Cover loading window and main window order.
|
||||
4. Cover update scheduling.
|
||||
5. Cover shutdown idempotency.
|
||||
6. Cover activation readiness behavior.
|
||||
|
||||
Do not move files before these tests exist.
|
||||
|
||||
## Important Constraints
|
||||
|
||||
- Do not re-architect around a renderer.
|
||||
- Do not introduce IPC proactively.
|
||||
- Do not rewrite the whole project.
|
||||
- Do not move folders before preserving behavior with tests.
|
||||
- Do not remove the managed NodeCG runtime strategy.
|
||||
- Do not delete user-owned runtime directories.
|
||||
- Do not broaden Electron permissions.
|
||||
|
||||
## Preferred Refactor Order
|
||||
|
||||
1. Tests around current lifecycle behavior.
|
||||
2. Pure path and URL extraction.
|
||||
3. `ApplicationController`.
|
||||
4. Shutdown service.
|
||||
5. Updater rewrite.
|
||||
6. Platform process-killer adapter.
|
||||
7. Electron security hardening.
|
||||
8. Script normalization.
|
||||
9. Folder reorganization.
|
||||
|
||||
## Completion Criteria For The Refactor
|
||||
|
||||
The refactor is successful when:
|
||||
|
||||
- Startup is controlled by a tested application controller.
|
||||
- Shutdown is idempotent.
|
||||
- Activation cannot load dashboards before NodeCG readiness.
|
||||
- Updater metadata and URLs are validated.
|
||||
- Downloads use safe paths and atomic finalization.
|
||||
- Process-tree termination is isolated by platform.
|
||||
- Browser windows declare secure settings explicitly.
|
||||
- Permission requests are denied by default.
|
||||
- No unnecessary IPC, preload, or renderer has been introduced.
|
||||
- Typecheck, tests, and lint pass.
|
||||
|
||||
## Reminder For Future Agents
|
||||
|
||||
This project does not need to become bigger to become safer.
|
||||
|
||||
Keep Electron small. Keep NodeCG ownership explicit. Keep remote update data untrusted. Keep the browser surface boring.
|
||||
Reference in New Issue
Block a user