fediversity.md

@@ -434,6 +434,139 @@ We will integrate that aspect into the high level process on a best effort basis
 
 # Quality and efficiency of the implementation
 
+## Interactions
+
+To reach these goals, we aim to implement the following interactions between [actors](#actors) (depicted with rounded corners) and system components (see the [glossary](#glossary), depicted with rectangles).
+
+```mermaid
+flowchart
+
+  user(user) --> |use| deployment
+
+  configuration -->|deploy| deployed
+  devs(developers) --> |maintain| fediversity
+
+  fediversity --> |update| provider1
+  subgraph provider1["fediversity setup A"]
+    subgraph panel1[panel]
+      configuration[staged configuration]
+      configuration --> |update| configuration
+      deployed[deployed configuration]
+    end
+    deployed --> |describe| deployment
+    provider-config[runtime config] --> |describe| host
+    provider-config --> |implement runtime interfaces| panel1
+    subgraph host[runtime environment]
+      deployment[applications]
+      state
+    end
+  end
+
+  deployment --> |store| state
+
+  operator(operator) --> |change| configuration
+
+  subgraph provider2["fediversity setup B"]
+     subgraph panel2[panel]
+      configuration2[staged configuration]
+      deployed2[deployed configuration]
+    end
+    subgraph host2[runtime environment]
+      deployment2[applications]
+      state2[state]
+    end
+  end
+
+  operator --> |trigger| migration
+  configuration & deployed & state --> migration
+  migration --> configuration2 & deployed2 & state2
+  provider(hosting provider) --> |maintain| provider1
+  subgraph fediversity[fediversity source code]
+    applications[application modules]
+    backends[runtime backends]
+    config[runtime options]
+  end
+```
+
+## Actors
+
+- Developers
+
+  The group working on this repository.
+  We are creating the deployment workflows and service configurations.
+
+- Hosting provider
+
+  They provide and maintain the physical infrastructure, and run the software in this repository, through which operators interact with their deployments.
+  Hosting providers are technical administrators for these deployments, ensuring availability and appropriate performance.
+
+  We target small- to medium-scale hosting providers with 20+ physical machines.
+
+- Operator
+
+  They select the applications they want to run.
+  They don't need to own hardware or deal with operations.
+  Operators administer their applications in a non-technical fashion, e.g. as moderators.
+  They pay the hosting provider for registering a domain name, maintaining physical resources, and monitoring deployments.
+
+- User
+
+  They are individuals using applications run by the operators, and e.g. post content.
+
+## Glossary
+
+- [Fediverse](https://en.wikipedia.org/wiki/Fediverse)
+
+  A collection of social networking applications that can communicate with each other using a common protocol.
+
+- Application
+
+  User-facing software (e.g. from Fediverse) run by the hosting provider for an operator.
+
+- Configuration
+
+  A collection of settings for a machine running NixOS.
+
+  > Example: Configurations are deployed to VMs.
+
+- Provision
+
+  Make a resource, such as a virtual machine, available for use.
+
+- Deploy
+
+  Put software, such as applications, onto computers.
+  The software includes technical configuration that links software components.
+  In our context, this a Configuration deployed to a runtime environment.
+  Most user-facing configuration remains untouched by the deployment process.
+
+- Migrate
+
+  Move service configurations and deployment (including user data) from one hosting provider to another.
+
+- Resource
+
+  A [resource for NixOps4](https://nixops.dev/manual/development/concept/resource.html) is any external entity that can be declared with NixOps4 expressions and manipulated with NixOps4, such as a virtual machine, an active NixOS configuration, a DNS entry, or customer database.
+
+- Resource provider
+
+  A resource provider for NixOps4 is an executable that communicates between a resource and NixOps4 using a standardised protocol, allowing [CRUD operations](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) on the resources to be performed by NixOps4.
+  Refer to the [NixOps4 manual](https://nixops.dev/manual/development/resource-provider/index.html) for details.
+
+  > Example: We need a resource provider for obtaining deployment secrets from a database.
+
+- Runtime backend
+
+  A type of digital environment one can run operating systems such as NixOS on, e.g. bare-metal, a hypervisor, or a container runtime.
+
+- Runtime environment
+
+  The thing a deployment runs on, an interface against which the deployment is working. See runtime backend.
+
+- Runtime config
+
+  Configuration logic specific to a runtime backend, e.g. how to deploy, how to access object storage.
+
 ## Architecture
 
 At the core of Fediversity lies a Terraform module for setting up NixOS instances on a hypervisor, so far targeting ProxmoX.
@@ -450,7 +583,7 @@ Whereas details of the implementation may need to be decided as the technical ch
 - Initial internal user to kick-start feedback process:
     - automate provisioning of:
         - [databases](https://git.fediversity.eu/Fediversity/Fediversity/issues/115)
-        - [immutable storage](https://git.fediversity.eu/Fediversity/Fediversity/issues/185)
+        - [object storage](https://git.fediversity.eu/Fediversity/Fediversity/issues/185)
         - [virtual machines](https://git.fediversity.eu/Fediversity/Fediversity/issues/116) (and related resources)
         - [DNS](https://git.fediversity.eu/Fediversity/Fediversity/issues/110)
         - [SMTP service](https://git.fediversity.eu/Fediversity/Fediversity/issues/117)