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-service.ts	MPV protocol + app state bridge	Active	~780 LOC, large protocol and behavior mix, 22-entry dep interface
src/core/services/subsync-service.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-service.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/core/services/mpv-control-service.ts (runtime control API)
  • src/core/services/subsync-service.ts (requestProperty, request ID usage)
  • tests under src/core/services/mpv-service.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-service.ts (initial integration creation)
  • src/core/services/anki-jimaku-service.ts (enable/disable and field-grouping RPC)
  • src/core/services/mining-service.ts (delegates mining actions)

src/core/services/subsync-service.ts

• Exports: runSubsyncManualService, openSubsyncManualPickerService, triggerSubsyncFromConfigService
• Caller set:
  • src/core/services/subsync-runner-service.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

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().
• Protocol frames are dispatched through processBuffer() → handleMessage().
• For property-change and request responses, handling remains in MpvIpcClient today but is a target for extraction:
  • subtitle text/ASS/timing updates → deps.setCurrentSubText, deps.setCurrentSubAssText, subtitle timing tracker, overlay broadcast hooks
  • media/path/title updates → deps.updateCurrentMediaPath, optional deps.updateCurrentMediaTitle
  • property update commands (sub-pos, sub-font*, sub-scale*, etc.) → deps.updateMpvSubtitleRenderMetrics
  • secondary-sub visibility tracking → deps.setPreviousSecondarySubVisibility + local restorePreviousSecondarySubVisibility()
• 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