add high-level spec

architecture-docs/2025-04-08-high-level-spec.md

@@ -0,0 +1,49 @@
+# fediversity product specification
+
+## stack
+
+### user-facing
+
+- fediverse
+- ...
+- prioritize efforts taking in mind
+  - added value to operator autonomy
+  - strategic relevance to counter-balance big tech
+  - demand
+  - nix package/service maturity
+    - may involve relation with application devs to:
+      - [upstream](https://git.fediversity.eu/Fediversity/Fediversity/issues/127#issuecomment-5669) nix package
+      - ensure architecture takes immutable build/storage in mind
+
+### under the hood
+
+- nixos
+- [opentofu](https://opentofu.org/)
+  - passes relevant info on to nixos config wrapper
+- VM hypervisor: [proxmox](https://proxmox.com/)
+- storage: [garage](https://garagehq.deuxfleurs.fr/)
+- backups / data portability: [borgmatic](https://github.com/borgmatic-collective/borgmatic)?
+- data interoperability: [json-schema](https://json-schema.org/)
+
+## component architecture
+
+- orchestration module
+  - application service modules (nixos): templates providing sane defaults and [unified interface](https://nlnet.nl/project/SelfHostBlocks/)
+  - deployment module (opentofu)
+- deployment UIs
+  - [reference imlementation](https://git.fediversity.eu/Fediversity/Fediversity)
+  - hosting panel: [fediversity integration](https://www.figma.com/proto/AZbFAac2Xjxs3q1H3orXzO/Fedi-Design-system?page-id=97%3A1682&node-id=97-2284) TODO
+    - [front](https://git.fediversity.eu/Fediversity/protagio.nl-frontend)
+    - back
+      - [existing](https://git.fediversity.eu/Fediversity/myprotagio-api)
+      - rewrite?
+  - allow for alternate setups
+    - e.g. client doing orchestration
+- [infra](https://git.fediversity.eu/Fediversity/meta/media/branch/main/architecture-docs/architecture.png)
+
+### feature-specific architectural notes
+
+- [decouple version](https://git.fediversity.eu/Fediversity/Fediversity/issues/304)
+- [validate component input](https://git.fediversity.eu/Fediversity/Fediversity/issues/195)
+- [migrate to different host](https://git.fediversity.eu/Fediversity/Fediversity/issues/100) (+ sub-tickets)
+- [breaking changes](https://git.fediversity.eu/Fediversity/Fediversity/issues/214)