# Architecture

SubMiner uses a service-oriented Electron main-process architecture where `src/main.ts` acts as the composition root and behavior lives in small runtime services under `src/core/services`.

## Goals

- Keep behavior stable while reducing coupling.
- Prefer small, single-purpose units that can be tested in isolation.
- Keep `main.ts` focused on wiring and state ownership, not implementation detail.
- Follow Unix-style composability:
  - each service does one job
  - services compose through explicit inputs/outputs
  - orchestration is separate from implementation

## Current Structure

- `src/main.ts`
  - Composition root for lifecycle wiring and non-overlay runtime state.
  - Owns long-lived process state for trackers, runtime flags, and client instances.
  - Delegates behavior to services.
- `src/core/services/overlay-manager-service.ts`
  - Owns overlay/window state (`mainWindow`, `invisibleWindow`, visible/invisible overlay flags).
  - Provides a narrow state API used by `main.ts` and overlay services.
- `src/core/services/*`
  - Stateless or narrowly stateful units for a specific responsibility.
  - Examples: startup bootstrap, app lifecycle hooks, CLI command handling, IPC registration, overlay visibility, MPV IPC behavior, shortcut registration, subtitle websocket, jimaku/subsync helpers.
- `src/core/utils/*`
  - Pure helpers and coercion/config utilities.
- `src/cli/*`
  - CLI parsing and help output.
- `src/config/*`
  - Config schema/definitions, defaults, validation, and template generation.
- `src/window-trackers/*`
  - Backend-specific tracker implementations plus selection index.
- `src/jimaku/*`, `src/subsync/*`
  - Domain-specific integration helpers.

## Composition Pattern

Most runtime code follows a dependency-injection pattern:

1. Define a service interface in `src/core/services/*`.
2. Keep core logic in pure or side-effect-bounded functions.
3. Build runtime deps in `main.ts`; use `*-deps-runtime-service.ts` helpers only when they add real adaptation logic.
4. Call the service from lifecycle/command wiring points.

This keeps side effects explicit and makes behavior easy to unit-test with fakes.

## Lifecycle Model

- Startup:
  - `startup-bootstrap-runtime-service` handles initial argv/env/backend setup and decides generate-config flow vs app lifecycle start.
  - `app-lifecycle-service` handles Electron single-instance + lifecycle event registration.
  - `startup-lifecycle-hooks-runtime-service` wires app-ready and app-shutdown hooks.
- Runtime:
  - CLI/shortcut/IPC events map to service calls.
  - Overlay and MPV state sync through dedicated services.
  - Runtime options and mining flows are coordinated via service boundaries.
- Shutdown:
  - `app-shutdown-runtime-service` coordinates cleanup ordering (shortcuts, sockets, trackers, integrations).

## Why This Design

- Smaller blast radius: changing one feature usually touches one service.
- Better testability: most behavior can be tested without Electron windows/mpv.
- Better reviewability: PRs can be scoped to one subsystem.
- Backward compatibility: CLI flags and IPC channels can remain stable while internals evolve.

## Extension Rules

- Add behavior to an existing service or a new `src/core/services/*` file, not as ad-hoc logic in `main.ts`.
- Keep service APIs explicit and narrowly scoped.
- Prefer additive changes that preserve existing CLI flags and IPC channel behavior.
- Add/update unit tests for each service extraction or behavior change.
- For cross-cutting changes, extract-first then refactor internals after parity is verified.