add architecture-docs/NixDefinitions.md

architecture-docs/NixConfigs.md

@@ -0,0 +1,15 @@
+# NixConfigs
+
+NixConfigs is a thin layer of configuration options that distinguishes a particular Fediversity deployment from any other. It can be thought of as the API between NixPanel and NixDefinitions.
+
+## Where it's situated
+
+![](./architecture.png)
+
+### [NixPanel](./NixPanel.md)
+
+NixPanel produces the NixConfig based on options set by Administrators.
+
+### [NixDefinitions](./NixDefinitions.md)
+
+NixDefinitions defines what options are included in NixConfigs, and uses them to produce a description of the system that should run.

architecture-docs/NixDefinitions.md

@@ -1,12 +1,14 @@
 # NixDefinitions
 
+NixDefinitions is a layer of NixOS modules that exposes a simple interface of a few options (e.g. what services to run, domain names), and turns that into a full description of all the systems that need to be running.
+
 ## Where it's situated
 
 ![](./architecture.png)
 
 ### [NixConfigs](./NixConfigs.md)
 
-NixDefinitions is a layer of NixOS modules that exposes a simple interface of a few options (e.g. what services to run, domain names). Setting those options is the job of the layer above (NixConfigs).
+ NixConfigs sets the few options exposed by NixDefinitions.
 
 ### [NixOS Instances](./NixOS_Instances.md) & [Services](./Services.md)
 
@@ -14,14 +16,14 @@ The combination of NixConfigs and NixDefintions produces a detailed description
 
 ### [NixOps](./NixOps.md)
 
-NixOps consumes the combined NixConfigs/NixDefintions configuration to know what the system should look like when deployed.
+NixOps consumes the combined NixConfigs/NixDefintions system description to know what the system should look like when deployed.
 
 ### [NixGuard](./NixGuard.md)
 
-NixGuard compares the state of the NixConfigs/NixDefinitions to the running state to detect inconsistent state and either fix or report it.
+NixGuard compares the state of NixConfigs/NixDefinitions to the running state to detect inconsistent state and either fix or report it.
 
 ## Purpose
 
 NixDefinitions...
-- simplifies the job of NixPanel, allowing it to not worry at all about *how* machines work, but simply produce a machine-readable translation of the options set by Administrators.
+- simplifies the job of NixPanel, allowing it to not worry at all about **how** machines work, but simply produce a machine-readable translation of the options set by Administrators.
 - factors out the system configuration that is common between any Fediversity system, defining a simple set of parameters that might differ between them.