SubMiner/docs/structure-roadmap.md

Structure Roadmap for TASK-27

Date: 2026-02-14

1) Oversized refactor candidates (>=400 LOC)

File	Concern	Status	Reason
src/main.ts	Bootstrap / composition root / orchestration	Active	Main entrypoint owns startup, lifecycle orchestration, service construction, state mutation surfaces, and IPC bindings
src/anki-integration.ts	Domain service orchestration / integrations	Active	2.6k+ LOC, high cyclomatic coupling to mpv/subtitle timing and mining flows
src/core/services/mpv.ts	MPV protocol + app state bridge	Active	~780 LOC, large protocol and behavior mix, 22-entry dep interface
src/core/services/subsync.ts	Subsync orchestration (ffsubsync/alass workflows)	Active	~494 LOC, file IO + mpv command orchestration + result shaping
src/renderer/positioning.ts	Renderer positioning layout policy	Active (downstream of TASK-27.5)	513 LOC, layout/rules + platform-specific behavior in one module
src/config/service.ts	Config load/validation	Active support	~601 LOC, central schema validation + mutation APIs
src/types.ts	Shared contract surface	Active support	~640 LOC, foundational type exports driving module boundaries
src/config/definitions.ts	Config schema/registry definitions	Active support	~480 LOC, dense constants/interfaces used by config runtime and docs
src/media-generator.ts	Media generation helpers	Active support	~431 LOC, utility-heavy with multiple generation flows

2) API contracts by target file

src/main.ts (bootstrap + composition root)

• Entry points: Electron main process boot path (executed by package main entry).
• Contract responsibilities:
  • parse CLI/env and select startup flow through runStartupBootstrapRuntimeService
  • register app-level lifecycle and command handlers (runAppLifecycleService, handleCliCommandService)
  • instantiate core services (mpv, overlay runtime, IPC handlers, shortcuts, tokenizer, config services)
  • hold mutable application runtime state:
    • parser/Yomitan windows and extension state
    • mpv client and tracker/state
    • overlay/app bootstrap flags and modal/shortcut state
    • runtime option and anki integration containers
• Primary callers/integration points:
  • Electron event loop (app.whenReady, process signals)
  • startup/bootstrap services, service adapters in src/core/services

src/core/services/mpv.ts (protocol + facade)

• Core exports: MpvIpcClient, MPV_REQUEST_ID_SECONDARY_SUB_VISIBILITY, MpvIpcClientDeps
• Primary responsibilities / API:
  • connection management (connect, setSocketPath, request, send, requestProperty)
  • protocol message handling (processBuffer, private message handlers for property-change and request IDs)
  • reconnection lifecycle (scheduleReconnect, failPendingRequests)
  • mpv control actions (setSubVisibility, replayCurrentSubtitle, playNextSubtitle)
  • state restoration (restorePreviousSecondarySubVisibility)
• Current caller set:
  • src/main.ts (construction + lifecycle + service invocations)
  • src/main/ipc-mpv-command.ts (runtime control API)
  • src/core/services/subsync.ts (requestProperty, request ID usage)
  • tests under src/core/services/mpv.test.ts
• Observed coupling risk:
  • MpvIpcClientDeps mixes protocol config with app-level side effects (subtitle broadcast, tokenizer, overlay updates, config reads)

src/anki-integration.ts

• Class export: AnkiIntegration
• Primary public operations (validated from external callsites):
  • lifecycle: start, stop, destroy
  • card flow: createSentenceCard, updateLastAddedFromClipboard, triggerFieldGroupingForLastAddedCard, markLastCardAsAudioCard
  • runtime patching: applyRuntimeConfigPatch
• State dependencies (constructor):
  • config, subtitle timing tracker, mpv client, OSD/notification callbacks
• Primary callers:
  • src/core/services/overlay-runtime-init.ts (initial integration creation)
  • src/core/services/anki-jimaku.ts (enable/disable and field-grouping RPC)
  • src/core/services/mining.ts (delegates mining actions)

src/core/services/subsync.ts

• Exports: runSubsyncManualService, openSubsyncManualPickerService, triggerSubsyncFromConfigService
• Caller set:
  • src/core/services/subsync-runner.ts (runtime wrappers)
  • src/core/services/mpv-jimaku/? (through runtime services and IPC command handlers)

src/config/service.ts

• Class export: ConfigService
• Primary API:
  • reloadConfig, saveRawConfig, patchRawConfig
  • read methods: getConfig, getRawConfig, getWarnings, getConfigPath
• Primary callers:
  • src/main.ts, src/core/services/cli-command and runtime config consumers

src/renderer/positioning.ts

• Public style/runtime contract
  • exported calculation helpers for subtitle Y-position and inset offsets
  • event handlers for window geometry and subtitle-size changes
• Primary callers:
  • src/renderer/handlers/*
  • src/renderer/subtitle-render.ts

3) Split sequence / dependency ordering

Adopted sequence (from TASK-27 parent):

1. TASK-27.3 (Anki integration split)
2. TASK-27.2 (main.ts composition-root split) — depends on TASK-7 and TASK-27.3
3. TASK-27.4 (mpv-service protocol/transport/property/facade split) — depends on TASK-27.1 and absorbs TASK-8
4. TASK-27.5 (renderer positioning split) — downstream

4) Compatibility and migration risks per split

TASK-27.3 / anki integration surface

• Risk: interface breakage in field-grouping preview/build/enable flow
• Mitigation: keep constructor params and public methods stable; preserve IPC payload shapes

TASK-27.2 (composition root)

• Risk: lifecycle/cleanup regressions from moving startup hooks and shutdown behavior
• Mitigation: preserve service construction order and keep existing event registration boundaries

Migration note:

• src/main.ts now delegates composition edges to src/main/startup.ts, src/main/app-lifecycle.ts, src/main/startup-lifecycle.ts, src/main/ipc-runtime.ts, src/main/cli-runtime.ts, and src/main/subsync-runtime.ts.
• Overlay/modal interaction has been moved into src/main/overlay-runtime.ts (window selection, modal restore set tracking, runtime-options palette/modal close handling) so main.ts now uses a dedicated runtime service for modal routing instead of inline window bookkeeping.
• Stateful runtime session data has moved to src/main/state.ts via createAppState() so main.ts no longer owns the AppState shape inline, only importing and mutating the shared state instance.
• Behavioral contract remains stable: startup flow, CLI dispatch, IPC handlers, and subsync orchestration keep existing external behavior; only dependency wiring moved out of main.ts.

TASK-27.4 (mpv-service)

• Risk: request/deps interface changes could break control and subsync interactions
• Mitigation: preserve public MpvClient methods, request semantics, and reconnect events while splitting internal modules

TASK-27.4 expected event flow snapshot (current)

• connect() establishes socket and starts observe_property subscriptions via subscribeToProperties().
• processBuffer() uses splitMpvMessagesFromBuffer() to parse JSON lines and route each message to handleMessage().
• dispatchMpvProtocolMessage() now owns protocol-level handling for:
  • event === "property-change" updates (subtitle text/ASS/timing, media/path/title, track metrics, secondary subtitles, visibility restore flags)
  • request_id responses for startup state fetches and dynamic property queries
  • shutdown handling and pending request resolution
• handleMessage() now delegates state mutation and side effects through MpvProtocolHandleMessageDeps to the client facade (emit(...), state fields, sendCommand, etc.).
• Reconnect path stays behavior-critical:
  • socket close/error clears pending requests and calls scheduleReconnect()
  • timer callback calls connect() after exponential-ish delay

TASK-27.5 (renderer positioning)

• Risk: UI placement drift on platform edge cases
• Mitigation: keep existing DOM state updates and geometry math in place while refactoring module boundaries

5) Global smoke checklist (required for all TASK-27 subtasks)

• App starts and connects to MPV
• Subtitle text appears in overlay
• Card mining creates a note in Anki
• Field grouping modal opens and resolves
• Global shortcuts work (mine, toggle overlay, copy subtitle)
• Secondary subtitle display works
• TypeScript compiles with no new errors
• Manual smoke checklist executed for runtime behavior