SubMiner/docs/architecture/README.md

Architecture Map

Status: active Last verified: 2026-05-23 Owner: Kyle Yasuda Read when: runtime ownership, composition boundaries, or layering questions

SubMiner runs as three cooperating runtimes:

• Electron desktop app in src/
• Launcher CLI in launcher/
• mpv Lua plugin in plugin/subminer/

The desktop app keeps src/main.ts as composition root and pushes behavior into small runtime/domain modules.

Read Next

• Domains - who owns what
• Layering - how modules should depend on each other
• Subtitle Overlay Priming - visible-overlay subtitle startup flow
• Public contributor summary: docs-site/architecture.md

Current Shape

• src/main/ owns composition, runtime setup, IPC wiring, and app lifecycle adapters.
• src/main/boot/ owns boot-phase assembly seams so src/main.ts can stay focused on lifecycle coordination and startup-path selection.
• src/core/services/ owns focused runtime services plus pure or side-effect-bounded logic.
• src/renderer/ owns overlay rendering and input behavior.
• src/config/ owns config definitions, defaults, loading, and resolution.
• src/types/ owns shared cross-runtime contracts via domain entrypoints; src/types.ts stays a compatibility barrel.
• src/main/runtime/composers/ owns larger domain compositions.
• src/main.ts call sites invoke configured runtime handlers and runtime-object methods directly; do not add local pass-through wrappers around them.

Architecture Intent

• Small units, explicit boundaries
• Composition over monoliths
• Pure helpers where possible
• Stable user behavior while internals evolve

Startup resolves and creates the user-data directory in src/main-entry-runtime.ts before the entry process requests Electron's single-instance lock. Main-process config bootstrap then writes the default config only when no config file exists.