Doc: add conceptual documentation

docs/mkdocs.yml

@@ -14,6 +14,7 @@ markdown_extensions:
   - attr_list
   - footnotes
   - md_in_html
+  - def_list
   - meta
   - plantuml_markdown
   - pymdownx.emoji:
@@ -49,6 +50,8 @@ nav:
       - Mesh VPN: getting-started/mesh-vpn.md
       - Backup & Restore: getting-started/backups.md
       - Flake-parts: getting-started/flake-parts.md
+  - Concepts:
+      - Configuration: concepts/configuration.md
   - Reference:
       - Clan Modules:
           - reference/clanModules/borgbackup-static.md

docs/site/concepts/configuration.md

@@ -0,0 +1,114 @@
+# Configuration
+
+## Introduction
+
+When managing machine configuration this can be done through many possible ways.
+Ranging from writing `nix` expression in a `flake.nix` file; placing `autoincluded` files into your machine directory; or configuring everything in a simple UI (upcomming).
+
+clan currently offers the following methods to configure machines:
+
+!!! Success "Recommended for nix people"
+
+    - flake.nix (i.e. via `buildClan`)
+        - `machine` argument
+        - `inventory` argument
+
+    - machines/`machine_name`/configuration.nix (`autoincluded` if it exists)
+
+???+ Note "Used by CLI & UI"
+
+    - inventory.json
+    - machines/`machine_name`/hardware-configuration.nix (`autoincluded` if it exists)
+
+
+!!! Warning "Deprecated"
+
+    machines/`machine_name`/settings.json
+
+## BuildClan
+
+The core function that produces a clan. It returns a set of consistent configurations for all machines with ready-to-use secrets, backups and other services.
+
+### Inputs
+
+`directory`
+: The directory containing the machines subdirectory
+
+`machines`
+: Allows to include machine-specific modules i.e. machines.${name} = { ... }
+
+`meta`
+: An optional set
+
+: `{ name :: string, icon :: string, description :: string }`
+
+`inventory`
+: Service set for easily configuring distributed services, such as backups
+
+: For more details see [Inventory](#inventory)
+
+`specialArgs`
+: Extra arguments to pass to nixosSystem i.e. useful to make self available
+
+`pkgsForSystem`
+: A function that maps from architecture to pkgs, if specified this nixpkgs will be only imported once for each system.
+  This improves performance, but all nipxkgs.* options will be ignored.
+  `(string -> pkgs )`
+
+## Inventory
+
+`Inventory` is an abstract service layer for consistently configuring distributed services across machine boundaries.
+
+The following is the specification of the inventory in `cuelang`
+
+```cue
+{
+    meta: {
+        // A name of the clan (primarily shown by the UI)
+        name: string
+        // A description of the clan
+        description?: string
+        // The icon path
+        icon?: string
+    }
+
+    // A map of services
+    services: [string]: [string]: {
+        // Required meta fields
+        meta: {
+            name: string,
+            icon?: string
+            description?: string,
+        },
+        // Machines are added via the avilable roles
+        // Membership depends only on this field
+        roles: [string]: {
+            machines: [...string],
+            tags: [...string],
+        }
+        machines?: {
+            [string]: {
+                config?: {
+                    ...
+                }
+            }
+        },
+
+        // Global Configuration for the service
+        // Applied to all machines.
+        config?: {
+            // Schema depends on the module.
+            // It declares the interface how the service can be configured.
+            ...
+        }
+    }
+    // A map of machines, extends the machines of `buildClan`
+    machines: [string]: {
+        name: string,
+        description?: string,
+        icon?: string
+        tags: [...string]
+        system: string
+    }
+}
+```