Establish Tuxflotte architecture foundation

00-glossary.md

@@ -0,0 +1,81 @@
+# Tuxflotte Glossary
+
+**Status:** Stable  
+**Datum:** 2026-07-07
+
+## Workspace
+
+Ein fachlich definierter Arbeitsplatz.
+
+Ein Workspace beschreibt, welchen Zielzustand ein System haben soll.
+
+Beispiele:
+
+- Developer Workspace
+- Office Workspace
+- Kiosk Workspace
+
+Ein Workspace ist nicht distributionsabhängig.
+
+## Backend
+
+Eine distributionsspezifische Implementierung.
+
+Ein Backend beschreibt, wie ein Workspace auf einer bestimmten Distribution installiert wird.
+
+Beispiele:
+
+- Fedora Backend
+- Mint Backend
+- Debian Backend
+
+## Organization
+
+Eine Organisation beschreibt kunden- oder unternehmensweite Vorgaben.
+
+Beispiele:
+
+- Zertifikate
+- LDAP
+- Keycloak
+- Paketquellen
+- Proxy
+- Branding
+- VPN
+- Monitoring
+
+## Blueprint
+
+Die technische Beschreibung eines Workspace.
+
+## Runtime Blueprint
+
+Die zur Installationszeit erzeugte vollständige Zielbeschreibung.
+
+Sie entsteht aus:
+
+- Backend
+- Organization
+- Workspace
+- optional Benutzerkontext
+
+## Orchestrator
+
+Die Komponente der Provisioning-ISO, die den Ablauf steuert.
+
+Der Orchestrator erkennt Hardware, lädt Profile, erzeugt Runtime Blueprints und startet das passende Backend.
+
+## Provisioning Agent
+
+Der Agent läuft auf dem installierten System und übernimmt Registrierung, Nachkonfiguration, Inventarisierung und Lebenszyklusaufgaben.
+
+## Native Installer
+
+Der offizielle Installer der jeweiligen Distribution.
+
+Beispiele:
+
+- Anaconda
+- Calamares
+- Debian Installer
+- Subiquity

00-philosophy.md

@@ -0,0 +1,57 @@
+# Tuxflotte Philosophy
+
+**Status:** Stable  
+**Datum:** 2026-07-07
+
+## Leitidee
+
+Tuxflotte installiert keine Distributionen.
+
+Tuxflotte stellt Workspaces bereit.
+
+Ein Workspace beschreibt einen gewünschten Arbeitsplatzzustand, unabhängig davon, ob dieser später mit Fedora, Linux Mint, Debian oder Ubuntu umgesetzt wird.
+
+## Grundsätze
+
+1. Vision vor Implementierung
+2. Architektur vor Code
+3. Schnittstellen vor Implementierungen
+4. Dokumentation ist Teil des Produkts
+5. Der Code implementiert die Spezifikation
+6. Distributionen sind austauschbare Zielplattformen
+7. Der Tuxflotte-Kern bleibt distributionsneutral
+
+## Was Tuxflotte ist
+
+Tuxflotte ist eine Plattform zur Beschreibung, Bereitstellung und Verwaltung standardisierter Linux-Arbeitsplätze.
+
+## Was Tuxflotte nicht ist
+
+Tuxflotte ist kein eigener Linux-Installer.
+
+Die eigentliche Betriebssysteminstallation erfolgt über die nativen Installer der jeweiligen Distribution.
+
+## Produktgedanke
+
+Nicht Fedora oder Mint sind das Produkt.
+
+Der bereitgestellte Arbeitsplatz ist das Produkt.
+
+Beispiele:
+
+- Office Workspace
+- Developer Workspace
+- Kiosk Workspace
+- Schulungsraum
+- Secure Workspace
+
+## Notiz:
+Linux ist das Ergebnis einer weltweiten Gemeinschaft.
+
+Seine Vielfalt ist Ausdruck unterschiedlicher Ideen, Anforderungen und Überzeugungen.
+
+Tuxflotte respektiert diese Vielfalt.
+
+Die Plattform schafft eine gemeinsame Grundlage für die Bereitstellung und Verwaltung von Linux-Workspaces, ohne die Eigenständigkeit der Distributionen aufzugeben.
+
+Tuxflotte schafft Gemeinsamkeit, ohne Vielfalt aufzugeben.

01-design-principles.md

@@ -0,0 +1,117 @@
+# Design Principles
+
+**Status:** Stable
+
+## Zweck dieses Dokuments
+
+Dieses Dokument beschreibt die grundlegenden Gestaltungsprinzipien von Tuxflotte.
+
+Die Design Principles bilden den architektonischen Rahmen für die Entwicklung der Plattform. Sie sind bewusst technologieunabhängig formuliert und gelten unabhängig von Programmiersprachen, Frameworks oder den verwendeten Werkzeugen.
+
+Bei Architektur- und Implementierungsentscheidungen dienen diese Prinzipien als Orientierung. Sie bilden den gemeinsamen Maßstab für die Weiterentwicklung der Plattform. 
+
+---
+
+# 1. Der Workspace steht im Mittelpunkt
+
+Der fachliche Mittelpunkt von Tuxflotte ist der **Workspace**.
+
+Ein Workspace beschreibt den gewünschten Arbeitsplatz eines Benutzers oder einer Benutzergruppe. Er definiert den Zielzustand eines Systems und bildet die Grundlage jeder Provisionierung.
+
+Linux-Distributionen sind die technischen Zielplattformen, auf denen ein Workspace bereitgestellt wird. Der Workspace selbst bleibt unabhängig von der gewählten Distribution.
+
+---
+
+# 2. Tuxflotte orchestriert
+
+Tuxflotte steuert und begleitet den gesamten Bereitstellungsprozess eines Workspaces.
+
+Dazu erkennt die Plattform Hardware, verarbeitet Organisations- und Workspace-Informationen, erzeugt ein Runtime Blueprint, das den vollständigen Zielzustand der Installation beschreibt, und übergibt dieses an das passende Backend.
+
+Die eigentliche Installation des Betriebssystems erfolgt mit den nativen Installationswerkzeugen der jeweiligen Distribution. Tuxflotte ergänzt diese Werkzeuge, ersetzt sie jedoch bewusst nicht.
+
+---
+
+# 3. Der Kern bleibt distributionsneutral
+
+Der Kern von Tuxflotte stellt die distributionsunabhängige Orchestrierung der Plattform bereit.
+
+Distributionsspezifische Implementierungen werden ausschließlich in Backends umgesetzt. Dadurch bleibt der Kern schlank, wartbar und leicht erweiterbar.
+
+---
+
+# 4. Jede Schicht besitzt eine klare Verantwortung
+
+Die Architektur von Tuxflotte ist in klar abgegrenzte Schichten unterteilt.
+
+Jede Schicht erfüllt genau eine Aufgabe und stellt definierte Schnittstellen für die darüber- oder darunterliegenden Schichten bereit.
+
+Klare Verantwortlichkeiten bilden die Grundlage für eine verständliche, wartbare und langfristig erweiterbare Architektur.
+
+---
+
+# 5. Runtime Blueprints beschreiben den Zielzustand
+
+Vor jeder Installation erzeugt Tuxflotte ein **Runtime Blueprint**.
+
+Es beschreibt den vollständigen Zielzustand einer konkreten Installation und entsteht aus den Informationen der verschiedenen Architekturschichten, beispielsweise Workspace, Organization und Backend.
+
+Das Runtime Blueprint dient dem Backend als Grundlage für die Erstellung distributionsspezifischer Installationsdaten.
+
+---
+
+# 6. Wiederverwendung vor Duplizierung
+
+Tuxflotte setzt auf wiederverwendbare Bausteine.
+
+Neue Anforderungen werden nach Möglichkeit durch die Kombination bestehender Komponenten umgesetzt.
+
+Dadurch entstehen flexible Lösungen mit geringem Wartungsaufwand und einer hohen Konsistenz über alle Workspaces hinweg.
+
+---
+
+# 7. Dokumentation ist Teil der Architektur
+
+Die Dokumentation beschreibt die Architektur und die gemeinsame Sprache von Tuxflotte.
+
+Sie begleitet die Entwicklung von Beginn an und bildet die Grundlage für Implementierung, Erweiterung und Wartung der Plattform. Die Implementierung folgt der Architektur – nicht umgekehrt.
+
+
+---
+
+# 8. Entscheidungen bleiben nachvollziehbar
+
+Architekturentscheidungen werden dokumentiert und begründet.
+
+Historische Dokumente werden archiviert, anstatt gelöscht zu werden. Dadurch bleibt die Entwicklung der Plattform langfristig nachvollziehbar und Erfahrungen gehen nicht verloren.
+
+---
+
+# 9. Verständlichkeit schafft Qualität
+
+Eine verständliche Architektur ist langfristig wertvoller als eine möglichst raffinierte technische Lösung.
+
+Klarheit, Lesbarkeit und nachvollziehbare Zusammenhänge erleichtern die Zusammenarbeit und bilden die Grundlage für nachhaltige Softwareentwicklung.
+
+---
+
+# 10. Nachhaltigkeit vor kurzfristiger Optimierung
+
+Tuxflotte wird als langfristige Plattform entwickelt.
+
+Architekturentscheidungen sollen deshalb nicht nur aktuelle Anforderungen erfüllen, sondern auch zukünftige Erweiterungen ermöglichen.
+
+
+---
+
+# Zusammenfassung
+
+Tuxflotte beschreibt Linux-Workspaces, stellt sie bereit und verwaltet sie.
+
+Workspaces definieren den gewünschten Zielzustand.
+
+Backends übersetzen diesen Zielzustand in distributionsspezifische Installationsdaten.
+
+Die nativen Installer der Distributionen installieren das Betriebssystem.
+
+Tuxflotte orchestriert den gesamten Prozess und schafft damit eine distributionsunabhängige Plattform für den Lebenszyklus standardisierter Linux-Workspaces.

02-workspace-model.md

@@ -0,0 +1,57 @@
+# Workspace Model
+
+**Status:** Stable
+
+## Zweck dieses Dokuments
+
+Dieses Dokument beschreibt den Workspace als zentralen Gegenstand von Tuxflotte.
+
+Es definiert seine Aufgabe innerhalb der Plattform und beschreibt seine Verantwortung sowie seine Abgrenzung zu den übrigen Komponenten der Architektur.
+
+---
+
+## Motivation
+
+Benutzende erfüllen unterschiedliche Aufgaben und übernehmen unterschiedliche Rollen.
+
+Daraus ergeben sich unterschiedliche Anforderungen an ihren Arbeitsplatz.
+
+**Ein Workspace beschreibt die Anforderungen, die sich aus einer bestimmten Aufgabe oder Rolle der Benutzenden ergeben.**
+
+---
+
+## Definition
+
+Der Workspace ist der zentrale Gegenstand von Tuxflotte.
+
+Er beschreibt den gewünschten Zielzustand eines Linux-Arbeitsplatzes unabhängig von dessen technischer Umsetzung.
+
+Ein Workspace definiert, welche Eigenschaften ein Arbeitsplatz besitzen soll. Er beschreibt den gewünschten Zielzustand, der durch die weiteren Komponenten der Plattform umgesetzt wird.
+
+---
+
+## Verantwortungsbereich
+
+Ein Workspace beschreibt beispielsweise
+
+- den Zweck eines Arbeitsplatzes,
+- die Zielgruppe,
+- die erforderlichen Funktionen,
+- die benötigte Software,
+- optionale Erweiterungen,
+- Sicherheitsanforderungen sowie
+- organisatorische Anforderungen.
+
+Der Workspace beschreibt den gewünschten Zielzustand eines Arbeitsplatzes.
+
+Die technische Umsetzung dieses Zielzustands erfolgt durch die weiteren Komponenten der Plattform.
+
+---
+
+## Zusammenfassung
+
+Der Workspace bildet die Grundlage jeder Bereitstellung.
+
+Er beschreibt den gewünschten Zielzustand eines Linux-Arbeitsplatzes.
+
+Alle weiteren Komponenten von Tuxflotte arbeiten darauf hin, diesen Zielzustand auf einem Zielsystem bereitzustellen.

03-organization-model.md

@@ -0,0 +1,59 @@
+# Organization Model
+
+**Status:** Stable
+
+## Zweck dieses Dokuments
+
+Dieses Dokument beschreibt die Organization als organisatorischen Rahmen für die Bereitstellung von Workspaces.
+
+Es definiert ihre Aufgabe innerhalb der Plattform und beschreibt ihre Verantwortung sowie ihre Abgrenzung zu den übrigen Komponenten der Architektur.
+
+---
+
+## Motivation
+
+Workspaces beschreiben den gewünschten Arbeitsplatz.
+
+Unterschiedliche Organisationen stellen jedoch unterschiedliche Anforderungen an die Bereitstellung desselben Workspace.
+
+So kann ein Workspace beispielsweise auf einem einer Person fest zugeordneten Gerät oder auf einem gemeinsam genutzten Gerät bereitgestellt werden.
+
+Die Organization beschreibt die organisatorischen Rahmenbedingungen, unter denen Workspaces bereitgestellt werden.
+
+---
+
+## Definition
+
+Die Organization beschreibt die organisatorischen Rahmenbedingungen, unter denen Workspaces bereitgestellt werden.
+
+Sie ergänzt den Workspace um organisationsspezifische Anforderungen, die unabhängig vom eigentlichen Arbeitsplatz gelten.
+
+Dadurch können identische Workspaces in unterschiedlichen Organisationen unter jeweils passenden Rahmenbedingungen bereitgestellt werden.
+
+---
+
+## Verantwortungsbereich
+
+Eine Organization beschreibt beispielsweise
+
+- organisatorische Richtlinien,
+- organisationsweite Sicherheitsanforderungen,
+- Standardkonfigurationen,
+- Anforderungen an Authentifizierung und Identitätsmanagement,
+Zertifikate,
+- Softwarequellen,
+- Netzwerkanforderungen,
+- Branding sowie
+- Rahmenbedingungen für die Nutzung von Geräten.
+
+Die Organization beschreibt den organisatorischen Rahmen der Bereitstellung.
+
+Die technische Umsetzung dieser Rahmenbedingungen erfolgt durch die weiteren Komponenten der Plattform.
+
+---
+
+## Zusammenfassung
+
+Die Organization ergänzt den Workspace um organisationsspezifische Rahmenbedingungen.
+
+Gemeinsam beschreiben Workspace und Organization die fachliche Grundlage für die Bereitstellung eines Linux-Workspaces.

04-backend-model.md

@@ -0,0 +1,55 @@
+# Backend Model
+
+**Status:** Stable
+
+## Zweck dieses Dokuments
+
+Dieses Dokument beschreibt das Backend als distributionsspezifische Umsetzung der Workspaces von Tuxflotte.
+
+Es definiert seine Aufgabe innerhalb der Plattform und beschreibt seine Verantwortung sowie seine Abgrenzung zu den übrigen Komponenten der Architektur.
+
+---
+
+## Motivation
+
+Die Linux-Welt zeichnet sich durch ihre Vielfalt aus.
+
+Unterschiedliche Distributionen verfolgen unterschiedliche Ziele und besitzen eigene Stärken. Sie unterscheiden sich beispielsweise in ihrer Systemarchitektur, den Paketformaten, den Desktopumgebungen oder ihren Veröffentlichungsmodellen.
+
+Diese Vielfalt ist eine Stärke des Linux-Ökosystems.
+
+Tuxflotte respektiert diese Vielfalt und bewahrt sie. Anstatt Distributionen zu vereinheitlichen, kapselt die Plattform distributionsspezifische Unterschiede bewusst in Backends.
+
+Dadurch können identische Workspaces auf unterschiedlichen Linux-Distributionen bereitgestellt werden.
+
+---
+
+## Definition
+
+Ein Backend beschreibt die distributionsspezifische Umsetzung eines Workspace unter Berücksichtigung der organisatorischen Rahmenbedingungen.
+
+Es übersetzt die fachlichen Anforderungen in distributionsspezifische Installationsdaten und nutzt dabei die nativen Installationsmechanismen der jeweiligen Distribution.
+
+---
+
+## Verantwortungsbereich
+
+Ein Backend beschreibt beispielsweise
+
+- die Zuordnung fachlicher Funktionen zu distributionsspezifischen Paketen,
+- distributionsspezifische Konfigurationen,
+- die Erstellung distributionsspezifischer Installationsdaten,
+- die Anbindung an native Installationswerkzeuge sowie
+- distributionsspezifische Besonderheiten.
+
+Das Backend beschreibt die technische Umsetzung eines Workspace.
+
+Die fachliche Beschreibung eines Arbeitsplatzes erfolgt durch den Workspace. Die organisatorischen Rahmenbedingungen werden durch die Organization beschrieben.
+
+---
+
+## Zusammenfassung
+
+Das Backend verbindet die distributionsunabhängigen Modelle von Tuxflotte mit den nativen Installationsmechanismen einer Linux-Distribution.
+
+Dadurch bleibt der Kern von Tuxflotte distributionsneutral, während gleichzeitig die Vielfalt des Linux-Ökosystems vollständig erhalten bleibt.

README.md

@@ -1,13 +1,27 @@
-# Tuxflotte Provisioning
+# Tuxflotte Platform Docs
 
-Repositories:
+Dieses Repository beschreibt die Architektur, Begriffe und Leitentscheidungen von Tuxflotte.
 
-- provisioning-server
+Tuxflotte ist eine distributionsunabhängige Workspace-Provisioning-Plattform für Linux-Arbeitsplätze.
-- provisioning-client
-- platform-docs
 
-Planned:
+## Einstieg
 
-- profiles
+1. `00-philosophy.md`
-- installer definitions
+2. `00-glossary.md`
-- ansible roles
+3. `architecture/01-layered-provisioning.md`
+4. `architecture/02-workspace-model.md`
+5. `architecture/05-runtime-blueprint.md`
+6. `architecture/06-backend-api.md`
+
+## Bereiche
+
+- `architecture/` – gültige Architektur
+- `adr/` – Architekturentscheidungen
+- `roadmap/` – Planung und Meilensteine
+- `archive/` – historische Dokumente
+
+## Grundsatz
+
+Die Dokumentation ist die Spezifikation.
+
+Der Code implementiert diese Spezifikation.

architecture/02-workspace-model.md

@@ -0,0 +1,76 @@
+# Workspace Model
+
+**Status:** Stable  
+**Datum:** 2026-07-07
+
+## Zweck
+
+Ein Workspace beschreibt einen fachlichen Arbeitsplatz-Zustand.
+
+Er beantwortet die Frage:
+
+> Welchen Arbeitsplatz soll der Benutzer erhalten?
+
+Ein Workspace beschreibt nicht, mit welcher Distribution dieser Zustand umgesetzt wird.
+
+## Beispiele
+
+- Office Workspace
+- Developer Workspace
+- Kiosk Workspace
+- Schulungsraum Workspace
+- Secure Workspace
+- Lab Workspace
+
+## Eigenschaften
+
+Ein Workspace kann definieren:
+
+- Name
+- Beschreibung
+- Zielgruppe
+- benötigte Rollen
+- Softwaregruppen
+- optionale Features
+- Konfigurationen
+- Sicherheitsanforderungen
+- empfohlene Hardware
+- Lebenszyklusregeln
+
+## Beispiel
+
+```yaml
+id: developer
+name: Developer Workspace
+description: Standard-Arbeitsplatz für Softwareentwicklung.
+
+features:
+  - git
+  - container-tools
+  - ssh
+  - vpn
+  - ide
+
+recommended_hardware:
+  ram: 16GB
+  cpu_cores: 4
+  disk: 256GB
+Abgrenzung
+Ein Workspace enthält keine distributionsspezifische Installationslogik.
+
+Nicht erlaubt:
+
+Kickstart-Anweisungen
+
+Preseed-Direktiven
+
+Autoinstall-Details
+
+Anaconda-spezifische Optionen
+
+Calamares-Konfiguration
+
+Diese Übersetzung übernimmt das jeweilige Backend.
+
+Leitprinzip
+Ein Workspace beschreibt den gewünschten Arbeitsplatz, nicht die gewünschte Distribution.