Wie EntityFlow funktioniert

EntityFlow basiert auf einer kleinen Reihe architektonischer Entscheidungen, die sein Verhalten deterministisch, testbar und über die Web-App, den Server und den Desktop-Build hinweg identisch halten.

Core-/Shell-Trennung

Die gesamte deterministische Logik liegt in headless, frameworkfreien TypeScript-Paketen. Die React-App, der Node-Server und die Electron-App sind dünne Shells, die sie nutzen — sie enthalten keine eigene Geschäftslogik.

Die headless Pakete umfassen:

• die Schema-IR (Zwischendarstellung),
• das CRDT-Dokumentmodell,
• Geometrie und Kantenführung,
• SQL/DBML-Codegenerierung über vier Dialekte,
• Validierung,
• die Projektion (Lesemodell),
• den Canvas-Renderer,
• Autorisierung.

Da die Logik gemeinsam genutzt wird, stammen das, was du im Browser siehst, das, was der Server exportiert, und das, was die Desktop-App erzeugt, alle aus demselben Code.

Doppelte Persistenz (CQRS)

EntityFlow verwendet eine Trennung von Befehl und Abfrage mit zwei Repräsentationen jedes Diagramms:

• Das maßgebliche Schreibmodell ist ein Yjs CRDT, gespeichert als binärer Blob. Jede Bearbeitung verändert diesen Blob.
• Eine relationale Leseprojektion wird aus dem Blob für Abfragen, Suche und serverseitigen Export abgeleitet.

Der Ablauf verläuft strikt in eine Richtung:

CRDT blob  →  IR  →  projection rows

Die Projektion wird niemals in den Blob zurückgeschrieben. Sollte eine Projektionszeile jemals abweichen oder fehlschlagen, wird sie einfach erneut aus dem Blob abgeleitet — der Blob ist die einzige Quelle der Wahrheit.

Echtzeit

Ein Hocuspocus-WebSocket-Server läuft im selben Node-Prozess wie die API und synchronisiert das CRDT zwischen verbundenen Editoren. Die Live-Präsenz (Cursor, Auswahlen, wer online ist) wird über die Awareness von Yjs übertragen, die niemals persistiert wird — sie existiert nur für die Dauer einer Verbindung.

hinweis

Da der serverseitige Export aus der blob-abgeleiteten IR erzeugt wird, ist das von ihm produzierte SQL/DBML Byte für Byte identisch mit dem, was der Editor im Browser exportiert.

Horizontale Skalierung

Ein einzelner Knoten bewältigt allein eine erhebliche Arbeitslast. Um mehr als eine Serverreplik zu betreiben, aktiviere das Redis-Fan-out, damit sich Awareness und Dokumentaktualisierungen über die Pods hinweg verbreiten. Ohne dies driften die Replikate auseinander. Siehe Skalierung & Leistung für Details und SLO-Ziele.