From ecf66a537dbd2a5183b83db352c4d757cf085c1a Mon Sep 17 00:00:00 2001 From: cinereal Date: Mon, 2 Jun 2025 11:37:59 +0200 Subject: [PATCH] tweak architecture wording --- architecture.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/architecture.md b/architecture.md index 10d7e46..6523ed2 100644 --- a/architecture.md +++ b/architecture.md @@ -4,8 +4,12 @@ - Developers - The group working on this repository. - We are creating the deployment workflows and service configurations. + The group maintaining this repository. + We are creating the deployment workflows and service configurations, and curate changes proposed by contributors. + +- Contributors + + People proposing changes to this repository. - Hosting provider @@ -33,11 +37,11 @@ - Application - User-facing software (e.g. from Fediverse) run by the hosting provider for an operator. + User-facing software (e.g. from Fediverse) configured by operators and used by users. - Configuration - A collection of settings for a machine running NixOS. + A collection of settings for a piece of software. > Example: Configurations are deployed to VMs. @@ -47,10 +51,8 @@ - Deploy - Put software, such as applications, onto computers. + Put software 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 @@ -100,7 +102,7 @@ Considered alternatives include: ### [SelfHostBlocks](https://nlnet.nl/project/SelfHostBlocks/) -SelfHostBlocks offers Nix module contracts to decouple applications from service providers, empowering user choice by providing sane defaults yet a [unified interface](https://nlnet.nl/project/SelfHostBlocks/). +SelfHostBlocks offers Nix module contracts to decouple application configuration from implementation details, empowering user choice by providing sane defaults yet a [unified interface](https://nlnet.nl/project/SelfHostBlocks/). Considered alternatives include: @@ -192,10 +194,10 @@ Considered alternatives include: ## Architecture -At the core of Fediversity lies a NixOS configuration template containing selected applications. -We support using this with different run-time environments, with targets deemed in scope including NixOS itself and hypervisor ProxmoX. -Depending on the targeted run-time environment, deployment will further involve orchestrator OpenTofu. -We further provide a [reference front-end](https://git.fediversity.eu/Fediversity/Fediversity/src/branch/main/panel) to configure our template. +At the core of Fediversity lies a NixOS configuration module for a set of selected applications. +We will support using it with different run-time environments, such as a single NixOS machine or a ProxmoX hypervisor. +Depending on the targeted run-time environment, deployment will further involve OpenTofu as an orchestrator. +We further provide a [reference front-end](https://git.fediversity.eu/Fediversity/Fediversity/src/branch/main/panel) to configure applications. To ensure reproducibility, we also offer Nix packaging for our software. To reach our 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). @@ -212,7 +214,7 @@ Relationships among the entities used to model migrations are as follows, using ### Host architecture -Whereas the core abstraction in Fediversity is a NixOS configuration template, a more full-fledged example architecture of the web host use-case we aim to support as part of our exploitation would be as follows, where VMs in question run Fediversity to offer our selected applications: +Whereas the core abstraction in Fediversity is a NixOS configuration module, a more full-fledged example architecture of the web host use-case we aim to support as part of our exploitation would be as follows, where VMs in question run Fediversity to offer our selected applications: ![](https://git.fediversity.eu/Fediversity/meta/raw/branch/entity-relations/architecture-docs/host-architecture.png) @@ -261,7 +263,7 @@ Whereas details of the implementation may need to be decided as the technical ch - [garbage collection of unallocated resources](https://git.fediversity.eu/Fediversity/Fediversity/issues/188) - [Nix-less bootstrap](https://git.fediversity.eu/Fediversity/Fediversity/issues/332) - [ensure hosts may update users' deployments](https://git.fediversity.eu/Fediversity/Fediversity/issues/159) - - [reference front-end decoupled from template version](https://git.fediversity.eu/Fediversity/Fediversity/issues/304) + - [reference front-end decoupled from version of configuration module](https://git.fediversity.eu/Fediversity/Fediversity/issues/304) - [security audit](https://git.fediversity.eu/Fediversity/Fediversity/issues/291) - [Key features improving user experience supported](https://git.fediversity.eu/Fediversity/Fediversity/issues/289): - [enqueuing deployment syncs](https://git.fediversity.eu/Fediversity/Fediversity/issues/242)