homeio

This repo stays a single deployable Next.js + Node application. Refactors should strengthen domain boundaries inside that monolith, not split the runtime.

Dependency Rules

• app/api/* are HTTP translators only: validate input, call server application services, map response and errors.
• app/* pages and shell components can compose feature modules, but should not embed domain logic.
• lib/server/modules/* is the server application/domain layer. Infra details such as Docker, DB, filesystem, D-Bus, NetworkManager, and spawned processes stay behind local adapters.
• modules/* owns feature UI and feature hooks. Feature code must not import app/api/*.
• Shared contracts only move to lib/shared/contracts/* when they cross a real client/server boundary.

Server Shape

For new server work inside a domain, prefer this layout:

• contracts/types: DTOs and boundary-level types
• application/use-cases: orchestrators that express one business action
• domain: policies, invariants, business decisions
• infrastructure: repositories and host adapters

Avoid placing new behavior into broad service.ts files when a narrower use-case or adapter file is a better fit.

UI Shape

Large feature screens should converge on three roles:

• container/orchestrator: data loading, section selection, high-level actions
• presentational components: cards, rows, forms, dialogs, menus
• focused hooks: one capability per hook when state and effects are non-trivial

If a file grows beyond roughly 300-400 lines and owns multiple responsibilities, extract at least one responsibility before adding more logic.

Refactor Definition of Done

Each vertical pass should leave the codebase with:

• one todo.md item easier to test
• at least one hotspot file reduced
• no new cross-domain coupling
• targeted tests and production build green

First Hotspots

Current priority hotspots:

• lib/server/modules/docker/compose-runner.ts
• modules/settings/hooks/useSettingsBackend.ts
• modules/apps/components/app-store.tsx

The goal is steady extraction, not a rewrite branch.