jawz/NixOS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

documentation regarding the new core functions

Browse Source
This commit is contained in:
Danilo Reyes
2026-03-16 15:50:14 -06:00
parent 28c8db6cb7
commit 4f4c23d1df
4 changed files with 17 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/constitution.md
View File

@@ -8,6 +8,7 @@
## Repository Overview
- Architecture: Flake-based repo using `flake-parts` with inputs for pkgs (stable/unstable), stylix, home-manager, sops-nix, and service overlays. Common modules are composed through `parts/core.nix` and `parts/hosts.nix`.
- Module auto-import: `modules/modules.nix` auto-imports legacy flat modules under `modules/apps`, `modules/dev`, `modules/scripts`, `modules/servers`, `modules/services`, `modules/shell`, `modules/websites`, and `modules/network`, excluding `librewolf.nix`, and also discovers nested `nixos.nix` files under those trees. `config/base.nix` registers `modules/home-manager.nix` as a Home Manager shared module, which discovers nested `home.nix` files under `modules/` for every Home Manager user. Factories live in `modules/factories/` (`mkserver`, `mkscript`), and shared options are in `modules/nix` and `modules/users`.
- Home Manager helper layer: Common Home Manager wrapper logic belongs in `parts/core.nix` helpers under `inputs.self.lib` when it is repeated across multiple `home.nix` modules. Current helpers include split-loader support plus `hmModule`, `hmShellType`, and `hmOnlyUser` for shared enablement and shell-selection patterns.
- Hosts and toggles: Host definitions live in `hosts/<name>/configuration.nix` with host-specific toggles in `hosts/<name>/toggles.nix`. The `my` namespace carries toggles for apps/dev/scripts/services/shell, feature flags like `enableProxy` and `enableContainers`, and per-host `interfaces` and `ips` maps.
- Port assignment: Service ports should live with the service module when the port is intrinsic to a server definition under `modules/servers/`. Miscellaneous or host-specific ports that do not belong to a server module should be centralized in `my.ports` in `modules/modules.nix` and referenced via `config.my.ports.*` (use `toString config.my.ports.*` where a string is required).
- Main server and proxies: `my.mainServer` selects the host that should serve traffic by default (default `vps`). Reverse proxies use helpers in `parts/core.nix` (`proxy`, `proxyReverse`, `proxyReverseFix`, `proxyReversePrivate`) and pick IPs from `my.ips` plus the hostName/ip set by `mkserver` options. Nginx defaults to `proxyReverse` for any server with `enableProxy = true` unless `useDefaultProxy = false` or the server is listed in the Fix/Private proxy lists.
@@ -49,6 +50,7 @@ config.services = {
## Module Categories and Active Hosts
- Module categories: apps, dev, scripts, servers, services, shell, websites, network, users, nix. Factories sit in `modules/factories/` and are imported explicitly; patch artifacts live at the repo root in `patches/`.
- Split-module preference: For categories that need both system and Home Manager behavior, co-locate both surfaces in `modules/<category>/<name>/nixos.nix` and `modules/<category>/<name>/home.nix`. Keep helpers local to that directory only when they are feature-specific; otherwise promote them into shared helpers/factories.
- Home module helper rule: Extract repeated Home Manager wrapper code into `parts/core.nix` once at least a few modules share the same structure. Keep only feature-specific package lists, files, and service settings inside each `home.nix`.
- User config split: Personal configs may also split across `config/<name>.nix` for NixOS-side account/secrets state and `config/<name>-home.nix` for Home Manager-only state imported from the user home module.
- Active hosts: `workstation`, `server`, `miniserver`, `galaxy`, `emacs`, `vps`. Host roles and secure status are defined in `hosts/<name>/configuration.nix` and toggles in `hosts/<name>/toggles.nix`.