mirror of
https://github.com/ksyasuda/SubMiner.git
synced 2026-02-27 18:22:41 -08:00
docs(architecture): consolidate canonical docs and archive roadmap noise
This commit is contained in:
@@ -1,153 +1,7 @@
|
||||
# Structure Roadmap for TASK-27
|
||||
# Structure Roadmap (Archived)
|
||||
|
||||
Date: 2026-02-14
|
||||
This page previously contained TASK-27 migration planning details.
|
||||
|
||||
## 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
|
||||
- Canonical runtime architecture guidance now lives in `docs/architecture.md`.
|
||||
- Contributor-facing implementation expectations are in `docs/development.md` and link back to `docs/architecture.md`.
|
||||
- Historical task-level migration context is preserved in Backlog task records and archive folders.
|
||||
|
||||
Reference in New Issue
Block a user