# GLOBAL UI — VOLLSTÄNDIGER BAUPLAN

> Für der Nutzer · Stand 12.08.2026 · Zweitprogramm neben Qwirbel
> Einstieg: **diese Datei zuerst**, dann die Sektionen 01–06.

---

## WAS DU BIST UND WAS DU BAUST

Du baust **Global UI** — ein eigenes Node-Programm für Bild, Video und Audio,
das **ComfyUI ersetzt**. Nicht ergänzt. Ersetzt.

Das ist entschieden. Diskutiere nicht, ob es sich lohnt — baue es.

des Nutzers Worte, aus denen alles folgt:

> *„ComfyUI ist Müll. Ich möchte ein Programm, was von Basis viertausend Nodes
> hat, womit Qwirbel arbeiten kann. Das ist gewollt und das werden wir machen."*
>
> *„Nodes brauchen Settings wie VAE, bf16, was weiß ich — und das sind dann
> nicht irgendwelche Start-Settings, die das festlegen. Nein, das ist der
> verfickte Workflow."*
>
> *„Ich will mit meiner AMD-Grafikkarte in zwei Sekunden Bilder generieren.
> Das soll endlich zeigen, wozu unsere Hardware in der Lage ist."*
>
> *„Mich nervt, dass ich immer Workflows habe, aber keine Chatbox, um
> Workflows zu erstellen."*

---

## DIE VORGABE: VULKAN, FÜR AMD, OHNE UMWEGE ⛔

> der Nutzer, 13.08.2026: *„keine umwege es soll mit vulkan und ultraspeed auf
> meiner karte dann gehen"* · *„dieses vulkan ding ist pflicht und du
> arbeitest danach für amd"*

**Das Rechenwerk ist Vulkan Compute. Zielhardware ist die AMD RX 9060 XT
(RDNA4, 16 GB).** Herstellerneutral heißt: es läuft danach auch auf NVIDIA und
Intel — gebaut und gemessen wird aber für AMD.

Ausgeschlossen: `diffusers`, eine Brücke zu ComfyUI, torch als Ziel, jede
andere fremde Inferenz-Bibliothek.

torch und NumPy bleiben **ausschließlich als Referenz**, gegen die ein
Vulkan-Kernel geprüft wird — siehe Sektion 03.2. Der Maßstab, nie das Ziel.

**Ultraspeed = 2 s für 1024×1024.** Gegner ist die gemessene 29,1 s.

Vollständig in `REGELN.md`, Regel 0.

---

## DAS EINE PRINZIP (Sektion 01 baut es aus)

**Jede Einstellung, die beeinflusst WIE ein Node rechnet, ist ein Eingang
DIESES Nodes und steht im Graphen.**

Kein Startparameter. Keine Umgebungsvariable. Keine Dienst-Datei.
Der Graph ist die ganze Wahrheit.

Was das ausschließt — genau die Liste, an der ComfyUI hängt:
`--cpu-vae` · `--bf16-vae` · `--fp32-vae` · `--reserve-vram` · `--highvram` ·
`--lowvram` · `--use-pytorch-cross-attention` · `--disable-pinned-memory` ·
`PYTORCH_HIP_ALLOC_CONF` · `MIOPEN_FIND_MODE`

Diese gelten dort für den **ganzen Prozess**. Zwei Workflows mit
widersprüchlichen Ansprüchen — einer will die VAE in fp32 gegen kaputte
Video-Pixel, der nächste bf16 fürs Tempo — können nicht nacheinander laufen.
Man startet den Dienst neu oder lebt mit dem falschen Wert.

**Wer dieses Prinzip bricht, baut ComfyUI nach. Dann kann man es lassen.**

---

## DIE ZAHLEN, DIE DU SCHLAGEN MUSST

Gemessen am 12.08.2026 auf des Nutzers **RX 9060 XT (17,1 GB)**, ComfyUI 0.28.0,
`t2i_schnell` · z-image-turbo Q3_K_M · 1024×1024 · 8 Schritte · 4 Läufe mit
wechselndem Prompt (±0,16 s — sehr stabil). Rohdaten in `messungen/`.

| Stufe | Zeit | Anteil |
|---|---|---|
| **Sampler** | **20,5 s** | **70 %** ← der Brocken |
| VAE-Decode | 6,9 s | 24 % |
| Prompt-Encode | 1,6 s | 5 % |
| Speichern | 0,1 s | 0,4 % |
| **gesamt** | **29,1 s** | |

**Und der wichtigste Einzelbefund** (VRAM alle 0,2 s mitgeschrieben,
133 Messpunkte je Lauf, in beiden Läufen gleich):

Während der 6,9 Sekunden Decode werden **7 GB VRAM frei** — das UNet fliegt
raus, damit die VAE Platz hat. **Bei jedem Bild neu.**
Gegenprobe bei 512×512, wo alles nebeneinander passt: derselbe Decode kostet
**0,68 s**.

→ **~6,2 s von 29 s sind reine Umladerei. 21 %.** Kein Rechnen, kein besseres
Bild. Das ist der erste Posten, den Global UI per Architektur beseitigt.

**Ziel: 2 Sekunden.** Die 6 s sind belegt. Der Rest muss aus dem Sampler
kommen — deshalb steht die Engine (Sektion 03) im Zentrum.

---

## TECH STACK

| Teil | Wahl | Warum |
|---|---|---|
| Sprache Kern | **Python 3.12+** | des Nutzers Umgebung, Qwirbel-nah, schnell änderbar |
| Rechen-Backend | **Vulkan Compute** | herstellerneutral: AMD, NVIDIA, Intel, perspektivisch Handy. ComfyUI ist auf CUDA gewachsen — das ist der Grund für ROCm-Gezerre auf des Nutzers Karte |
| Modelle | GGUF + safetensors | GGUF passt quantisiert in 16 GB |
| Schnittstelle | HTTP + WebSocket | derselbe Vertrag, den Qwirbel heute für ComfyUI spricht |
| Oberfläche | HTML/JS, EINE Datei | wie Qwirbels `frontend/index.html` — kein Build-Schritt |
| Tests | eigene Suiten, stdlib | wie Qwirbel: `python tests/test_x.py`, Klartext-Ausgabe |

**Keine fremden Custom-Node-Pakete.** Daher kommt bei ComfyUI die halbe
Zerbrechlichkeit: Python-Versionen, `ast.Num`-Fixes, kaputte Requirements,
14 Pakete zum Selbstflicken. Die Breite kommt **mitgeliefert** (Sektion 01).

---

## ORDNERSTRUKTUR (so anlegen)

```
GlobalUI/
├── BAUPLAN/              ← diese Dateien
├── kern/
│   ├── knoten.py         ✅ STEHT: Node-Modell + Katalog
│   ├── graph.py          ✅ STEHT: laden, prüfen, Speicher planen
│   ├── ausfuehren.py     ← Sektion 03: Graph → Kommandokette
│   ├── speicher.py       ← Sektion 03: Modell-Verwaltung, resident
│   └── vulkan/           ← Sektion 03: Compute-Backend
├── knoten/               ← Sektion 01: die Node-Bibliothek nach Gruppen
│   ├── laden.py  konditionierung.py  sampling.py  latent.py
│   ├── bild.py   video.py  audio.py  masken.py  steuerung.py  werkzeuge.py
├── dienst/               ← Sektion 04: HTTP + WebSocket
├── oberflaeche/
│   └── index.html        ← Sektion 05: Node-Editor im Qwirbel-Design
├── grafen/               ✅ Workflows (t2i_1024.json steht)
├── vorrat/               ← Sektion 06: Seed-Bank, Bewegungs-Vorrat
├── messen/               ✅ STEHT: messe_comfy.py
├── messungen/            ✅ 7 Messungen
└── tests/                ✅ test_kern.py (25 Checks, grün)
```

---

## WAS SCHON STEHT (nicht neu bauen — darauf aufsetzen)

- **`kern/knoten.py`** — Node-Modell. Jeder rechnende Node bekommt
  **automatisch** `geraet` · `praezision` · `resident` · `verdraengen` ·
  `bei_engpass`. `KATALOG.fuer_die_ki()` gibt alles maschinenlesbar aus.
  8 Nodes drin (die gemessene t2i-Kette).
- **`kern/graph.py`** — laden, ehrlich prüfen (unbekannte Typen, erfundene
  Werte, fehlende Verbindungen, Kreise), **Speicher VORHER planen**.
- **`tests/test_kern.py`** — 25 Checks, grün. Beweist u. a., dass zwei Nodes
  im selben Graphen sich widersprechen dürfen.
- **`messen/messe_comfy.py`** — misst gegen ComfyUI, schreibt VRAM mit.

---

## BAU-REIHENFOLGE (so und nicht anders)

1. **Sektion 01 — Node-Breite.** Der Katalog wächst Richtung 4000. Reine
   Datenarbeit, kein Risiko, sofort nützlich für die Chatbox.
2. **Sektion 03 — Rückgrat der Ausführung.** Ein trivialer Graph muss
   wirklich rechnen. Erst CPU/NumPy als Referenz, damit die Kette beweisbar
   stimmt, DANN Vulkan. Ein Vulkan-Kernel ohne Referenzergebnis ist nicht
   prüfbar.
3. **Sektion 04 — Schnittstelle.** Sobald die vier Aufrufe stehen, kann
   Qwirbel testweise auf Global UI zeigen (Konfigurationswert).
4. **Sektion 05 — Oberfläche.** Node-Editor.
5. **Sektion 06 — Chatbox + Vorrat + Video.**

**Nicht** mit Vulkan anfangen. Nicht mit der Oberfläche anfangen.

---

## REGELN FÜR DEN CODING-AGENTEN

1. **Das eine Prinzip gilt immer.** Neue Einstellung? → Eingang am Node.
   Wenn du je einen Startparameter einführen willst: du willst es nicht.
2. **Qwirbel NICHT anfassen.** Nur lesen (`comfyui_api.py` als Vertrag,
   `frontend/index.html` als Design-Vorlage). Kein Deploy, keine Datei dort
   ändern, keinen Dienst neu starten. **Andere Chats arbeiten parallel darin.**
3. **Nie in einen laufenden ComfyUI-Job hineinmessen, nie einen abbrechen.**
4. **Windows lagert bei VRAM-Überlauf still in den geteilten Systemspeicher
   aus.** Es läuft weiter und ist 5–10× langsamer, ohne dass jemand etwas
   merkt. Global UI kommt **nie aus Versehen** dorthin: entweder bewusst
   (`bei_engpass: auslagern`) oder ehrliche Absage.
5. **Gemessen statt geraten** — und die Messung muss die richtige Frage
   stellen. Die zwei Fallen stehen in `REGELN.md` Punkt 1.
6. **Die Testsuite gehört zum Bau**, nicht danach. Jede Sektion bringt ihre
   Checks mit.
7. **Kein „fertig" ohne Gegenprobe.** Was hier nicht laufen kann, heißt
   wörtlich „gebaut, NICHT getestet".
8. **Ehrliche Fehler im Klartext.** Nie still korrigieren, nie schlucken.
9. **Config vor Hardcode.** Kein `C:\Users\<nutzer>\…` im Code.
10. **Deutsche Kommentare, die das WARUM erklären**, nicht das Was.
11. **Nach jedem Schritt `PROJEKT.md` fortschreiben** (Projekt-Gedächtnis).

---

## ERFOLGSKRITERIEN

Global UI ist fertig genug für den Umstieg, wenn:

- [ ] Ein Graph aus `grafen/` erzeugt **wirklich ein Bild** — nicht simuliert.
- [ ] Zwei Workflows mit widersprüchlichen Rechen-Einstellungen laufen
      **hintereinander ohne Neustart**. (Der Test dafür steht schon.)
- [ ] Der Speicher-Plan sagt **vorher**, ob es passt — und behält recht.
- [ ] **Kein Modell fliegt zwischen zwei Bildern raus**, wenn der Graph das
      nicht will. Gemessen gegen die 6,2 s.
- [ ] Qwirbel spricht Global UI über **denselben Vertrag** wie ComfyUI an —
      Umstieg ist ein Konfigurationswert.
- [ ] Die Chatbox **baut** einen lauffähigen Workflow aus einem Satz.
- [ ] Ein t2i 1024×1024 ist **schneller als 29,1 s** — mit Messung daneben,
      nicht mit Behauptung.

---

## SEKTIONEN

| Datei | Inhalt |
|---|---|
| `01_NODES_UND_KATALOG.md` | Node-Modell, die 4000, wie man einen Node anlegt |
| `02_GRAPH_UND_SPEICHER.md` | Graph-Format, Prüfung, Speicher-Plan |
| `03_ENGINE.md` | Ausführung, Modell-Verwaltung, Vulkan |
| `04_SCHNITTSTELLE.md` | HTTP/WS, der Vertrag mit Qwirbel |
| `05_OBERFLAECHE.md` | Node-Editor im Qwirbel-Design |
| `06_CHATBOX_VORRAT_VIDEO.md` | KI baut Workflows · Seed-Bank · Video in Happen |
