SubMiner/docs/architecture/layering.md

Layering Rules

Status: active
Last verified: 2026-05-23
Owner: Kyle Yasuda
Read when: deciding whether a dependency direction is acceptable

Preferred Dependency Flow

1. src/main.ts
2. src/main/ composition and runtime adapters
3. src/core/services/ focused services
4. src/core/utils/ and other pure helpers

Renderer, launcher, plugin, and stats each keep their own local layering and should not become a grab bag for unrelated cross-runtime behavior.

Rules

• Keep src/main.ts thin; wire, do not implement.
• Prefer injecting dependencies from src/main/ instead of reaching outward from core services.
• Keep side effects explicit and close to composition boundaries.
• Put reusable business logic in focused services, not in top-level lifecycle files.
• Keep renderer concerns in src/renderer/; avoid leaking DOM behavior into main-process code.
• Treat launcher/*.ts and the runtime bootstrap generators as source of truth for launcher behavior. scripts/build-launcher.ts creates dist/launcher; never hand-edit those artifacts.

Smells

• main.ts grows because logic was not extracted
• service reaches directly into unrelated runtime state
• renderer code depends on main-process internals
• docs-site page becomes the only place internal architecture is explained