CompanyOS Slice 1 API Foundation

CompanyOS Slice 1 API Foundation

Dieses Dokument definiert den ersten konkreten Implementierungsschnitt in brezel/api.

Ziel ist nicht, CompanyOS vollständig zu bauen. Ziel ist, die kleinste belastbare Grundlage zu schaffen, auf der Explainability, sichere AI-Änderungen und systemnahe Workflow-Tests aufbauen können.

Ziel des ersten Slices

Slice 1 liefert vier Dinge:

1. ein maschinenlesbares system inventory
2. ein workflow catalog pro System
3. ein formales Startmodell für semantische Metadaten
4. eine explizite Workflow-Testmatrix für Framework- und Systemebene

Warum dieser Slice zuerst kommt

Ohne Inventar und Katalog weiß Brezel nicht zuverlässig, was in einem System überhaupt existiert. Ohne Semantik bleibt das Wissen nur implizit. Ohne Tests sind spätere AI- oder Refactoring-Schritte zu riskant.

Deshalb ist dieser Slice die Voraussetzung für:

• system explain
• Change Proposals
• AI-Assistenten
• Bestandskunden-Upgrades
• SaaS-Onboarding

Bestehende Andockpunkte in brezel/api

Der Slice soll auf vorhandenen Strukturen aufsetzen:

• CLI-Kommandos unter app/Console/Commands/CLI
• Bakery-Planung unter app/Bakery/Plan
• Workflow-Kern unter app/Workflow
• Workflow-Controller und Routen
• bestehende Tests unter tests/Unit/Workflow und tests/Feature/Workflow

Das ist wichtig: Wir bauen keinen separaten Analyse-Stack neben Brezel, sondern erweitern die vorhandene Runtime.

Scope

In Scope

• Dateisystembasierte Inventarisierung von systems/<system>/
• Parsing von Modulen, Workflows, Menüs, Rollen und Layout-Referenzen
• Ausgabe eines standardisierten Inventars
• Ausgabe eines Workflow-Katalogs
• Definition eines ersten semantischen Schemas
• Definition der Workflow-Testmatrix

Nicht in Scope

• vollständige AI-Oberfläche
• GUI für Explainability
• automatische Änderungsvorschläge
• vollständige Business-Workflow-Test-Runner-UX

Deliverable 1: System Inventory

Zweck

Das system inventory ist die kanonische maschinenlesbare Beschreibung eines Brezel-Systems.

Inhalt

Mindestens enthalten sein sollten:

• System-Identifier
• Pfad zum System
• vorhandene Ressourcen nach Typ
• Module und Feld-Identifier
• Workflow-Identifier
• Workflow-Events
• Rollen
• Menüs
• referenzierte Layout-Dateien
• einfache Relationen zwischen Ressourcen

Beispielstruktur

{
  "system": "kab",
  "path": "systems/kab",
  "modules": [
    {
      "identifier": "customers",
      "source": "systems/kab/modules/customers/customers.bake.json",
      "fields": ["name", "email", "customer_number"],
      "layouts": {
        "detail": "systems/kab/modules/customers/customers.layout.detail.json",
        "index": "systems/kab/modules/customers/customers.layout.index.json"
      }
    }
  ],
  "workflows": [
    {
      "identifier": "OrderCreated",
      "source": "systems/kab/workflows/OrderCreated.workflow.json",
      "events": ["create"],
      "module": "orders"
    }
  ],
  "roles": [],
  "menus": [],
  "references": []
}

Erste technische Form

Für Slice 1 reicht eine read-only Erzeugung als JSON-Artefakt oder CLI-Output.

Empfohlene erste Form:

• CLI-Kommando mit JSON-Ausgabe
• optional später API-Endpunkt auf derselben internen Service-Schicht

Vorgeschlagene Schnittstelle

php bakery system:inventory kab --json

Alternativ, wenn die bestehende CLI-Struktur enger an bakery system hängt:

php bakery system inventory kab --json

Deliverable 2: Workflow Catalog

Zweck

Der workflow catalog ist die fokussierte Sicht auf Geschäftslogik in einem System.

Er sollte nicht nur listen, dass Workflows existieren, sondern auch grob beschreiben, wie sie ins System eingreifen.

Inhalt

• Workflow-Identifier
• Titel
• Quelle
• Sync/Async
• Event-Typen
• Zielmodul
• verwendete Element-Typen
• Referenzen auf andere Workflows
• grobe Seiteneffekte
• semantische Metadaten, falls vorhanden

Beispielstruktur

{
  "system": "kab",
  "workflows": [
    {
      "identifier": "CreateCustomerFromOrder",
      "title": "Create customer from order",
      "source": "systems/kab/workflows/CreateCustomerFromOrder.workflow.json",
      "async": false,
      "events": [
        {
          "identifier": "OrderCreated",
          "type": "create",
          "module": "orders"
        }
      ],
      "elements": [
        "event/create",
        "source/entities",
        "op/set",
        "action/save"
      ],
      "writes_modules": ["customers", "orders"],
      "runs_workflows": [],
      "semantic": null
    }
  ]
}

Erste Abstraktionsstufe

Slice 1 braucht keine perfekte Datenflussanalyse. Es reicht ein robuster, konservativer Katalog, der aus den Workflow-Definitionen ableitbare Fakten sammelt.

Deliverable 3: Semantic Metadata Startmodell

Ziel

Wir brauchen ein minimales, sofort einführbares Schema.

Startobjekte

• Module
• Workflows

Startfelder für Module

{
  "purpose": "Why this module exists in business terms",
  "business_owner": "Responsible role or team",
  "summary": "Short explanation",
  "inputs": [],
  "outputs": [],
  "invariants": [],
  "risks": [],
  "related_workflows": []
}

Startfelder für Workflows

{
  "purpose": "Why this workflow exists",
  "business_owner": "Responsible role or team",
  "summary": "Short explanation",
  "trigger_summary": "Business-readable trigger description",
  "effects": [],
  "invariants": [],
  "risks": [],
  "test_criticality": "high"
}

Speicherform

Für Slice 1 ist die sauberste Zwischenlösung:

• begleitende semantische Dateien nahe an der Ressource

Beispiel:

• customers.semantic.module.json
• CreateCustomerFromOrder.semantic.workflow.json

Begründung:

• geringe Eingriffe in bestehende Parser
• leicht auffindbar
• gut versionierbar
• später in Ressourcen integrierbar, wenn das stabiler ist

Deliverable 4: Workflow-Testmatrix

Ziel

Die Testmatrix definiert, was wir ab jetzt systematisch absichern.

Sie dient als:

• Planungsinstrument
• Abdeckungsübersicht
• Grundlage für Change-Proposals
• Grundlage für CI-Auswahl relevanter Tests

Teil A: Element-Typ-Matrix

Für jeden Workflow-Element-Typ wird erfasst:

• Typ-Identifier
• Kritikalität
• existierende Unit-Tests
• fehlende Unit-Tests
• existierende Integrationsszenarien
• typische Fehlerfälle

Beispiel:

{
  "type": "action/save",
  "criticality": "high",
  "unit_test_status": "partial",
  "integration_test_status": "present",
  "business_test_relevance": "high",
  "failure_modes": [
    "validation failure",
    "unexpected writes",
    "event recursion"
  ]
}

Teil B: Workflow-Szenario-Matrix

Szenarien, die im Core systematisch vorhanden sein sollen:

• linearer Workflow
• branching mit flow/if
• Persistenz mit action/save
• Löschen mit action/delete
• Event-Trigger
• Workflow-zu-Workflow via action/run
• Fehlerpfad
• Async/Queue-Pfad

Teil C: System-Level-Matrix

Für reale Systeme soll je Workflow erfassbar sein:

• Business-Kritikalität
• betroffene Module
• vorhandene Business-Tests
• benötigte Fixtures
• Upgrade-Relevanz

Empfohlene Dateikonventionen

In brezel/api

• Service für Inventarisierung und Katalogisierung
• CLI-Kommando(s)
• Tests für Parsing, Inventar und Katalog

In Systemen

Empfohlene neue Konvention:

• systems/<system>/tests/
• systems/<system>/tests/fixtures/
• systems/<system>/tests/workflows/

Für Semantik

• semantische Begleitdateien neben Ressource oder in direkter Nähe

Technische Umsetzung in brezel/api

1. Interne Services

Erste naheliegende Service-Grenzen:

• DeclaredInventoryBuilder
• SystemInventoryBuilder
• WorkflowCatalogBuilder
• SemanticMetadataResolver
• WorkflowTestMatrixBuilder

Empfohlene Verantwortung:

• DeclaredInventoryBuilder baut deklarative Inventories primär aus bakery plan für Bakery-Ressourcen
• SystemInventoryBuilder orchestriert die Gesamtinventarisierung und ergänzt Workflows oder Scanner-Fallbacks

Diese Services sollten zunächst reine Leselogik kapseln.

2. CLI-Anbindung

Naheliegende erste Kommandos:

• system inventory
• workflow catalog
• optional später system explain

Die CLI ist für Slice 1 besser als eine UI, weil:

• schneller implementierbar
• CI-fähig
• agentenfreundlich
• gut als internes Arbeitswerkzeug nutzbar

Empfohlene Datenquellen

Nicht jede Inventar-Sicht sollte direkt aus denselben Quellen gebaut werden.

Bakery-Ressourcen

Primäre Quelle:

• bakery plan

Begründung:

• näher an Brezels deklarativer Semantik
• vereinheitlicht Resource-Dateien
• geeigneter für Explainability und Change-Proposals als nackter Dateiscan

Workflows

Kurzfristige Quelle:

• direkte Workflow-Katalogisierung aus den Workflow-Definitionen

Begründung:

• bakery plan deckt Workflows derzeit noch nicht ab
• ein Workflow-Planmodell muss separat entstehen

Scanner

Der Scanner bleibt sinnvoll:

• als Fallback
• für nicht geplante Artefakte
• für Diagnose und Drift-Hinweise
• für Übergangsphasen, bis alle deklarativen Typen durch Plan-Modelle abgedeckt sind

3. Test-Anbindung

Der Slice selbst braucht Tests auf drei Ebenen:

• Unit-Tests für Inventory- und Catalog-Builder
• Feature-Tests für CLI-Ausgabe
• erste Matrix-Tests gegen reale Beispieldaten

Workflow-Testing: konkrete erste Entscheidungen

Core-Ebene

Die vorhandene Teststruktur in brezel/api/tests wird ausgebaut, nicht ersetzt.

Zielstruktur:

• tests/Unit/Workflow/Elements/...
• tests/Feature/Workflow/...
• zusätzliche Matrix- und Harness-Tests

System-Ebene

Konkrete Business-Logik-Tests sollen als neue offizielle Konvention möglich werden:

• systems/<system>/tests/workflows/*.php

Diese Tests sollen langfristig über einen standardisierten Harness laufen, aber Slice 1 muss vor allem die Konvention und das Zielbild festziehen.

Minimaler Harness für spätere Slices

Der Harness sollte später mindestens bieten:

• Laden eines Systems
• Laden von Fixtures
• Dispatch eines konkreten Workflows
• Assertions auf Entitäten, Dateien, Zustände und Nebeneffekte

Empfohlener Implementierungsablauf

Schritt 1

SystemInventoryBuilder implementieren.

Definition of done:

• liest ein Systemverzeichnis
• erkennt Module, Workflows, Menüs, Rollen
• gibt stabiles JSON-Modell aus

Schritt 2

WorkflowCatalogBuilder implementieren.

Definition of done:

• extrahiert Workflows
• listet Events, Elemente, Modulbezüge
• gibt stabiles JSON-Modell aus

Schritt 3

Semantik-Konvention dokumentieren und Resolver anlegen.

Definition of done:

• Namensschema festgelegt
• Beispiel-Dateien dokumentiert
• Resolver kann Semantikdateien finden und laden

Schritt 4

Workflow-Testmatrix initial erzeugen.

Definition of done:

• Element-Typen inventarisiert
• erste Statuszuordnung vorhanden
• Szenariomatrix dokumentiert

Schritt 5

Erste Business-Test-Konvention für Systeme dokumentieren.

Definition of done:

• Speicherort definiert
• Fixture-Konzept definiert
• mindestens ein Beispielsystem als Referenz vorgesehen

Offene Entscheidungen

Diese Punkte müssen im Zuge der Umsetzung finalisiert werden:

• exakter Namespace und Speicherort der neuen Service-Klassen
• ob die CLI unter system oder bakery hängt
• ob semantische Dateien mittelfristig inline oder separat geführt werden
• wie systemnahe Tests technisch geladen werden
• wie viel statische Analyse der Workflows Slice 1 wirklich leisten soll

Definition of Done für Slice 1

Slice 1 ist abgeschlossen, wenn:

• ein Systeminventar für mindestens ein reales Brezel-System erzeugt werden kann
• ein Workflow-Katalog für mindestens ein reales Brezel-System erzeugt werden kann
• ein minimales semantisches Schema dokumentiert und auflösbar ist
• die Workflow-Testmatrix dokumentiert und im Core begonnen ist
• die Konvention für Business-Workflow-Tests auf Systemebene festgeschrieben ist

Unmittelbarer nächster Entwicklungsschritt

Der nächste Code-Slice nach diesem Dokument sollte sein:

1. SystemInventoryBuilder
2. CLI-Output für system inventory
3. Testfälle gegen ein reales Beispielsystem

Damit entsteht der erste ausführbare CompanyOS-Baustein im Core.