Skip to main content

Architecture

Documentation Map​

Architecture

Zweck​

Diese Datei beschreibt die provisorische Architektur des Repositories.

Aktueller Stand​

Status: provisorisch

Das Repository ist derzeit kein allgemeines Laufzeitsystem, sondern ein kleines Upgrade-Verifikationstool mit einem einzelnen realen Upgrade-Artefakt.

Systemuebersicht​

  • Dokumentationsschicht in docs/
  • Repo-Metadaten in README.md, AGENTS.md, DEPENDENCIES.md, RELEASE_POLICY.md und fabric-manifest.json
  • minimale CI-Schicht in .gitea/workflows/ci.yml

Hauptkomponenten​

  • Einstieg und Klassifikation
  • technische Baseline und Policies
  • issue-getriebene Arbeitsplanung
  • minimale Linux-CI-Verifikation
  • ein einzelnes Upgrade-Artefakt mit execution contract, verify path und evidence-Modell

Datenfluss​

  1. Aenderungen werden issue-getrieben im Repository vorgenommen
  2. Gitea ist Source of Truth fuer Code und Historie
  3. Linux-Runner validieren die Pflichtstruktur
  4. das Upgrade-Artefakt unter upgrade/openclaw/2026.3.13-to-2026.3.24/ definiert artifact inputs und verify path
  5. checks.sh erzeugt evidence fuer standalone oder helpifyr-integrierten Lauf

Interne Schnittstellen​

  • Datei-Kontrakte innerhalb des Repositories
  • Backlog- und Issue-Konventionen unter docs/
  • Upgrade-Artefakt-Kontrakt unter upgrade/openclaw/<version-path>/

Externe Schnittstellen​

  • Gitea fuer Git und CI
  • OpenClaw-Gateway als reale Verify-Referenz fuer den ersten Pfad
  • im integrierten Modus zusaetzlich die maintained News Memory Komponenten als scenario-bezogene Verify-Referenz

Betriebliche Annahmen​

  • Linux ist Referenzplattform
  • Shell-Logik muss bash-kompatibel bleiben
  • keine Windows-spezifischen Annahmen in CI oder Scripts

Upgrade Run Model​

Minimaler execution contract:

  • tool: openclaw
  • source version: 2026.3.13
  • target version: 2026.3.24
  • run path: openclaw-2026.3.13-to-2026.3.24
  • terraform scenario: openclaw-only
  • verify path: upgrade/openclaw/2026.3.13-to-2026.3.24/checks.sh
  • evidence: JSON-Datei mit run metadata, versions, result und checks

Modi:

  • standalone: prueft nur den OpenClaw-Zielzustand fuer den einen Versionspfad
  • helpifyr-integriert: prueft denselben Zielzustand plus scenario-bezogene Container fuer den maintained News Memory Pfad

Rolle im Helpifyr-Oekosystem​

  • heute: kleines Supporting-Repository mit einem implementierten Verify-Pfad
  • spaeter: moeglicher Input fuer helpifyr-update- oder Fabric-nahe Entscheidungslogik

Rolle gegenueber Fabric​

  • aktuell: nur dokumentarische und manifestbasierte Vorbereitung
  • nicht vorhanden: aktive Events, APIs oder kontrollierbare Tool-Schnittstellen

Maintenance- und Promotionschicht​

Implementiert:

  • repo-lokale Maintenance-Vertraege unter maintenance/
  • maschinenlesbare Trennung zwischen Inventory, Promotion-Handoff, Live-Feedback und Governance-Baseline
  • primaerer Promotion-Trigger als strukturiertes Gitea-Issue in jhf-deployment
  • Stage-3-Rueckmeldung als strukturierter Kommentar oder JSON-Anhang gegen dasselbe Promotion-Issue

Nicht implementiert:

  • zweiter Orchestrator neben jhf-deployment
  • repo-eigene Live-Scheduling- oder Queue-Infrastruktur

Shared-Service-Boundary im Integrated-Modus​

Implementiert:

  • jhf-fabric liefert nur read-first Metadata und keinen mutierenden Shared Service fuer diesen Pfad
  • jhf-deployment bleibt das Execution Substrate fuer create -> verify -> destroy
  • run evidence, offload stubs, compatibility exports und Host-Hygiene bleiben tool-owned oder host-local

Nicht implementiert:

  • Shared Postgres
  • Shared Queue oder Bus
  • Fabric-gesteuerte Runtime-Attachment-Logik

Adopt-First-Pfad fuer denselben Run​

Implementiert:

  • standalone und helpifyr-integrated teilen denselben run path, dieselben artifact inputs und denselben verify path
  • beim Wechsel zu helpifyr-integrated wird kein bestehender lokaler Run-Zustand migriert, sondern derselbe Pfad gegen das dokumentierte Execution Substrate erneut ausgefuehrt
  • der Adopt-First-Pfad bleibt damit explizit re-execution statt migration
  • dateibasierte run evidence bleibt tool-owned und kann nach dem Lauf als offloaded cold data archiviert werden

Nicht implementiert:

  • automatische Adoption von Host-Volumes, Datenbanken oder Netzwerken
  • Rebuild-/Migrate-Entscheidungslogik fuer mehrere Tools

Stage-Modell​

  • Stage 1 bleibt repo-lokaler Verify- und Packaging-Gate
  • Stage 2 bleibt Staging-Regression in jhf-deployment
  • Stage 3 bleibt Live-Apply und Post-Upgrade-Verify ueber jhf-beam
  • die drei Stufen werden getrennt ausgewiesen und sequentiell durchlaufen
  • Locking bleibt ueber das Promotion-Issue modelliert; ein zweiter paralleler Promotion-Flow fuer dasselbe Repo ist nicht zulaessig

Bezug zur urspruenglichen Upgrade-Idee​

Die Ausgangsidee war eine enge OpenClaw-Upgrade-Pruefung. Diese Praegung ist weiterhin sichtbar, aber heute noch nicht in konkrete Artefakte ueberfuehrt.

Bezug zum neuen Zielbild​

Das neue Zielbild ist breiter: Helpifyr-Upgrade-Kit statt reinem OpenClaw-Pruef-Ordner. Die Dokumentations- und Klassifikationsbasis ist jetzt vorhanden, die operative Artefaktebene fehlt noch. Das neue Zielbild bleibt bewusst klein: ein funktionierendes Beispiel zuerst, keine Plattform.