From be71b17474805fd6dc02aaefadf6a94035b3ce03 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Wed, 3 Jul 2024 14:13:30 +0200
Subject: [PATCH] Doc: add conceptual documentation

---
 docs/mkdocs.yml                      |   3 +
 docs/site/concepts/configuration.md  | 114 +++++++++++++++++++++++++++
 inventory.json                       |   3 +
 lib/inventory/spec/schema/schema.cue |   1 +
 4 files changed, 121 insertions(+)
 create mode 100644 docs/site/concepts/configuration.md

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 1432872d..eecfbb33 100644
--- a/docs/mkdocs.yml
+++ b/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
diff --git a/docs/site/concepts/configuration.md b/docs/site/concepts/configuration.md
new file mode 100644
index 00000000..b3d97a1b
--- /dev/null
+++ b/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
+    }
+}
+```
diff --git a/inventory.json b/inventory.json
index bd9d2570..207630e5 100644
--- a/inventory.json
+++ b/inventory.json
@@ -1,4 +1,7 @@
 {
+  "meta": {
+    "name": "Minimal inventory"
+  },
   "machines": {
     "minimal-inventory-machine": {
       "name": "foo",
diff --git a/lib/inventory/spec/schema/schema.cue b/lib/inventory/spec/schema/schema.cue
index 428fbe9b..09689584 100644
--- a/lib/inventory/spec/schema/schema.cue
+++ b/lib/inventory/spec/schema/schema.cue
@@ -5,6 +5,7 @@ package schema
     description?: string,
     icon?: string
     tags: [...string]
+    system: string
 }
 
 #role: string