Clarify module, profile, and host boundaries #113

New issue

Closed

opened 2026-07-28 08:35:02 +01:00 by nimmo · 0 comments

nimmo commented

2026-07-28 08:35:02 +01:00

Owner

Context

This repository already has a useful layered structure, but the boundaries between reusable modules, profiles, host composition, and Home Manager configuration are not always explicit.

Scope

Document and clarify the intended architecture:

modules provide one coherent capability or policy;
profiles compose related capabilities into a usable environment;
hosts select modules and profiles, then provide hardware facts and host-specific values;
Home Manager modules own user-specific configuration;
helper functions and packages remain implementation details unless they need user-facing options.

Review the current boundary cases and record which are intentional, which should be renamed or narrowed, and which should be deferred. Coordinate the Home Manager split with #111.

Non-goals

Do not introduce the Dendritic pattern or flake-parts.
Do not reorganise every file for aesthetic consistency.
Do not split cohesive service modules merely because they contain multiple packages.
Do not move host facts into abstract shared modules.

Acceptance criteria

The intended architecture and decision rules are documented in the repository.
The main current boundary cases are reviewed and either corrected or explicitly deferred.
Any resulting refactor is small, reviewable, and passes nix flake check.
#111 follows the documented module, profile, and user boundaries.

## Context This repository already has a useful layered structure, but the boundaries between reusable modules, profiles, host composition, and Home Manager configuration are not always explicit. ## Scope Document and clarify the intended architecture: - modules provide one coherent capability or policy; - profiles compose related capabilities into a usable environment; - hosts select modules and profiles, then provide hardware facts and host-specific values; - Home Manager modules own user-specific configuration; - helper functions and packages remain implementation details unless they need user-facing options. Review the current boundary cases and record which are intentional, which should be renamed or narrowed, and which should be deferred. Coordinate the Home Manager split with #111. ## Non-goals - Do not introduce the Dendritic pattern or flake-parts. - Do not reorganise every file for aesthetic consistency. - Do not split cohesive service modules merely because they contain multiple packages. - Do not move host facts into abstract shared modules. ## Acceptance criteria - The intended architecture and decision rules are documented in the repository. - The main current boundary cases are reviewed and either corrected or explicitly deferred. - Any resulting refactor is small, reviewable, and passes nix flake check. - #111 follows the documented module, profile, and user boundaries.

nimmo added this to the Developer Experience and Configuration Hygiene milestone

2026-07-28 08:35:02 +01:00

nimmo modified the milestone from Developer Experience and Configuration Hygiene to Configuration Architecture Hygiene

2026-07-28 08:36:36 +01:00

nimmo referenced this issue

2026-07-28 08:37:03 +01:00

Decompose oversized profiles where useful #115

nimmo referenced this issue from a pull request that will close it,

2026-07-28 09:51:15 +01:00

docs: clarify module and profile boundaries #117

nimmo closed this issue

2026-07-28 10:06:22 +01:00