Fintutto Plattform — Dokumentation
Erstellt: 04. April 2026 · Übersicht über alle Schutzmaßnahmen, Workflows und Regeln, die heute implementiert wurden.

📘 Für Nicht-Techniker: Dieses Dokument erklärt, wie wir unsere Entwicklungsplattform günstiger, stabiler und sicherer gemacht haben. Stell dir vor: Ein Team baut ein Haus — wir haben jetzt Regeln eingeführt, damit niemand aus Versehen Wände einreißt, die andere gerade frisch gebaut haben.
Kontext
Das Problem, das wir gelöst haben
Die Fintutto-Plattform besteht aus 45 Apps in 2 Haupt-Repos (Translator + Portal) sowie 6 weiteren Repos. Jedes Mal, wenn ein Agent eine Änderung auf main gepusht hat, hat Vercel alle Apps gleichzeitig gebaut — unabhängig davon, ob sich in der jeweiligen App überhaupt etwas geändert hatte.
Unkontrollierte Builds
Jeder einzelne Debugging-Push löste 45 Builds aus — auch wenn nur 1 App betroffen war.
Explodierende Kosten
10 Pushes/Tag × 45 Builds = 450 Builds = ~$18–20 pro Tag → ~$2.500 in einer Monatshälfte.
Rückkehrende Bugs
Teuer gefixte Bugs kamen immer wieder zurück, weil Agenten nicht wussten, warum bestimmter Code so sein musste.
45
Apps gesamt
Über 8 Repos verteilt
$2.5K
Kosten/Monatshälfte
Vor der Optimierung
450
Builds/Tag
Bei 10 Pushes auf eine App

📘 Für Nicht-Techniker: Stell dir vor, du änderst einen Satz in einem Buch — und der Drucker druckt alle 45 Kapitel komplett neu, obwohl sich nur eines geändert hat. Genau das passierte bei uns. Jedes Mal.
Agenda: Was heute implementiert wurde
01
Teil 1: Vercel-Kostenoptimierung
ignoreCommand in allen vercel.json-Dateien → nur betroffene Apps bauen
02
Teil 2: Pilot-Branch-System
Shared-Code-Änderungen sicher testen, bevor alle 45 Apps neu gebaut werden
03
Teil 3: Regressionstests
113 automatische Tests schützen alle kritischen Funktionen dauerhaft
04
Teil 4–5: Bug-Dokumentation & AGENTS.md
Bekannte Bugs sind dokumentiert und jeder Agent weiß, was er nicht anfassen darf
05
Teil 6–8: CI-Workflow, Repo-Status & Next Steps
Automatische Qualitätssicherung bei jedem Push + sofortige Handlungsschritte
Teil 1
Vercel-Kostenoptimierung
In jeder vercel.json aller 8 Repos wurde ein ignoreCommand eingetragen. Dieser Befehl wird von Vercel vor jedem Build ausgeführt und entscheidet, ob ein Build wirklich notwendig ist.
{ "ignoreCommand": "git diff HEAD^ HEAD --quiet -- . ../../src/ || exit 1" }
Wie es funktioniert
exit 0
Keine Änderungen erkannt → Build wird übersprungen
exit 1
Änderungen erkannt → Build wird gestartet
Was verglichen wird
Eigene App
Verzeichnis der jeweiligen App (.)
Shared Code
Gemeinsam genutzter Code in ../../src/

📘 Für Nicht-Techniker: Der ignoreCommand ist wie ein intelligenter Portier: Er prüft, ob eine App wirklich Änderungen bekommen hat — und lässt den Build-Prozess nur dann rein, wenn das wirklich der Fall ist.
Teil 1 · Ergebnis
Kostenvergleich: Vorher vs. Nachher
~95%
Kostenersparnis
Von ~$2.500 auf ~$50–150 pro Monatshälfte
1
Build pro App-Push
Statt 45 gleichzeitiger Builds

⚠️ Kritische Regel: Der ignoreCommand darf niemals aus einer vercel.json entfernt werden. Diese Regel ist explizit in jeder AGENTS.md in jedem Repo dokumentiert.
Teil 2
Das Pilot-Branch-System
Wenn Shared Code (src/) geändert wird — z.B. die zentrale Übersetzungsfunktion — müssen alle 45 Apps neu gebaut werden. Während des Debuggings möchte man jedoch nicht bei jedem Push 450 Builds auslösen. Die Lösung: ein dedizierter pilot-Branch.
App: consumer
Auf pilot: Immer bauen (Pilot-App) Auf main: Nur wenn apps/consumer/ oder src/ geändert
Alle anderen 31 Apps
Auf pilot: Niemals bauen Auf main: Nur wenn eigene App oder src/ geändert

📘 Für Nicht-Techniker: Der pilot-Branch ist wie ein Testflug. Bevor ein Pilot alle 45 Passagiermaschinen mit einem neuen Navigationssystem ausstattet, testet er es zuerst an einer einzigen Maschine. Erst wenn alles funktioniert, wird das System flottenweit ausgerollt.
Teil 2 · Workflow
Workflow: Shared-Code-Änderungen
Dieser Workflow stellt sicher, dass Shared-Code-Änderungen immer erst an einer einzigen Pilot-App getestet werden, bevor sie in main landen und alle 45 Apps neu gebaut werden. Jeder Fehler kostet so nur ~$0.04 statt ~$1.80.

📘 Für Nicht-Techniker: Erst testen, dann ausrollen. Klingt selbstverständlich — war es bei uns bisher aber nicht. Jetzt ist es strukturell erzwungen.
Teil 2 · Workflow
Workflow: Einzel-App-Änderungen
Bei Änderungen an einer einzelnen App wird ein Feature-Branch angelegt. Sowohl beim Push auf den Feature-Branch als auch beim Merge in main baut Vercel ausschließlich die betroffene App — dank des ignoreCommand. Alle anderen 44 Apps bleiben unberührt.

📘 Für Nicht-Techniker: Jede App bekommt ihre eigene "Baustelle". Die anderen 44 Hotels im Verbund werden nicht gesperrt, nur weil in einem Zimmer renoviert wird.
Teil 3
Regressionstests: Bugs kommen nicht zurück
Bugs, die teuer gefixt wurden, kamen immer wieder zurück. Ein Agent hat eine Kern-Datei angefasst, die Logik neu geschrieben und dabei einen früheren Fix stillschweigend entfernt — weil er nicht wusste, warum er so sein muss. Die Lösung: 113 automatische Regressionstests schützen alle kritischen Funktionen dauerhaft.

📘 Für Nicht-Techniker: Stell dir vor, du reparierst ein Auto — und nach jeder Reparatur läuft automatisch ein Checkprogramm durch alle 113 bekannten Fehlerquellen. Schlägt eines an, weißt du sofort: Hier wurde etwas Kritisches versehentlich beschädigt.
Teil 3 · Übersicht
113 Tests — Repo-Übersicht
Alle Tests befinden sich in src/test/regression/core-logic.test.ts bzw. src/__tests__/regression/ im Translator-Repo.
Teil 3 · Regeln
Kritische Regel für alle Agenten
1
npm test ausführen
Vor jeder Änderung an einer kritischen Datei: alle Tests müssen grün sein.
2
Änderung vornehmen
Die geplante Änderung an der kritischen Datei umsetzen.
3
Nochmal npm test
Nach der Änderung erneut alle Tests ausführen.
4
Roter Test = Fix korrigieren
Wenn ein Test rot wird: den Fix korrigieren — niemals den Test löschen oder deaktivieren.

📘 Für Nicht-Techniker: Ein Test ist wie ein Rauchmelder. Wenn er Alarm schlägt, löst man das Problem — man entfernt nicht den Rauchmelder, weil er stört.
Teil 4
Bekannte kritische Bugs — Dokumentiert & Geschützt
Die folgenden Bugs wurden teuer identifiziert und gefixt. Jeder ist durch einen automatischen Regressionstest abgesichert, sodass er nie wieder unbemerkt zurückkehren kann.
REG-001 / REG-002
Enterprise Session-Crash
Symptom
Enterprise-User gibt einen bestehenden Session-Code ein und klickt "Live gehen" → Absturz oder falsche Ansicht (Listener-UI statt Speaker-UI).
Ursache
LiveSessionPage.tsx hat bei state.role=speaker + existierendem Code nicht den richtigen Pfad genommen.
Fix
createSession akzeptiert jetzt einen optionalen existingCode-Parameter. LiveSessionPage ruft createSession(existingCode) auf, wenn state.role=speaker und ein Code vorhanden ist.
Geschützt durch
Tests REG-001 und REG-002 in src/__tests__/regression/session-critical.test.ts
Betroffene Dateien
src/pages/LiveSessionPage.tsx src/hooks/useLiveSession.ts

📘 Für Nicht-Techniker: Ein Enterprise-Nutzer, der eine laufende Sitzung übernehmen wollte, landete in der falschen Ansicht — als wäre er Zuhörer statt Sprecher. Das System hat seinen Status nicht korrekt erkannt. Jetzt tut es das zuverlässig.
REG-003 / REG-004
Audio-Sequenz-Reset & Session-Code-Format
REG-003: Audio-Sequenz-Reset
Symptom
Nach dem Stoppen einer Session sendete das nächste Audio-Paket eine falsche Sequenznummer → Empfänger verwarf Pakete.
Fix
seqRef.current wird in stopAudioStream auf 0 zurückgesetzt.
REG-004: Session-Code-Format
Symptom
Session-Codes hatten falsches Format → QR-Code-Scan schlug fehl.
Fix
generateSessionCode gibt immer TR-XXXX zurück (TR- Präfix + 4 alphanumerische Zeichen).

📘 Für Nicht-Techniker: REG-003: Die Audiodaten kamen beim Empfänger in der falschen Reihenfolge an — wie Seiten eines Buches, die nach dem Drucken falsch nummeriert wurden. REG-004: Der QR-Code hatte ein falsches Format — wie eine Telefonnummer ohne Vorwahl, die kein Telefon wählen kann.
Teil 5
AGENTS.md — Die Schaltzentrale
Jedes Repo hat eine AGENTS.md im Root-Verzeichnis. Diese Datei ist die einzige Quelle der Wahrheit für jeden Agenten, der an diesem Repo arbeitet. Kein Agent darf Code ändern, ohne sie zuerst gelesen zu haben.
Abschnitt 0: Vercel-Schutz & Tests
Pflichtlektüre, Priorität über alles andere — ignoreCommand und Regressionstest-Regeln
Kritische Stellen
Jede kritische Codestelle mit Erklärung, warum sie so sein muss wie sie ist
Bekannte Bugs (REG-Nummern)
Symptom, Fix und zugehöriger Test für jeden dokumentierten Bug
Deployment-Workflow
Feature-Branch → Test → Merge — der verbindliche Entwicklungsprozess

📘 Für Nicht-Techniker: Die AGENTS.md ist das Handbuch für jeden Mitarbeiter, der in einer Abteilung anfängt. Wer es nicht liest, riskiert, wichtige Regeln zu brechen — ohne es zu wissen. Für Claude gibt es zusätzlich eine CLAUDE.md, die auf dieselbe Quelle verweist.
Teil 6
CI-Workflow aktivieren (einmalige Aktion)
Die CI-Workflow-Dateien liegen als Templates in docs/workflows/ci-with-regression-guard.yml in jedem Repo. Sie müssen einmalig nach .github/workflows/ci.yml kopiert werden. Am einfachsten über die GitHub-Weboberfläche:
1
GitHub aufrufen
github.com/alexanderdeibel-Fintutto/ öffnen und zum jeweiligen Repo navigieren
2
Template kopieren
docs/workflows/ci-with-regression-guard.yml öffnen → "Copy raw contents"
3
Neue Datei erstellen
Zu .github/workflows/ navigieren → "Add file" → "Create new file"
4
Speichern
Name: ci.yml, Inhalt einfügen, committen

💡 Alternative: Mit einem Token mit workflow
Teil 6 · Was der CI-Workflow leistet
CI-Workflow: Automatische Qualitätssicherung
Der CI-Workflow sorgt dafür, dass kein fehlerhafter Code jemals den Weg in den main-Branch findet. Wenn auch nur ein einziger Regressionstest fehlschlägt, wird der Build blockiert — und damit auch der Merge. Entwickler werden sofort benachrichtigt, welcher Test gescheitert ist.

📘 Für Nicht-Techniker: Stell dir eine Qualitätskontrolle am Fabrikausgang vor: Kein Produkt verlässt die Fabrik, ohne geprüft worden zu sein. Fehlerhafte Ware wird automatisch zurückgehalten — bevor sie den Kunden erreicht.
Teil 7
Übersicht aller Repos und ihr Status
Alle 8 Repos sind vollständig geschützt. Vercel-Schutz, AGENTS.md, Regressionstests und CI-Template sind überall vorhanden — der CI-Workflow muss noch in jedem Repo manuell aktiviert werden (siehe Teil 6).
Teil 8
Was du als Nächstes tun solltest
⚡ Sofort (heute)
CI-Workflow aktivieren
In allen 8 Repos — Anleitung in Teil 6
Pilot-Branch in Vercel einrichten
Vercel Dashboard → translator/consumer → Settings → Git → Preview Branches → pilot hinzufügen
📅 Diese Woche
Neuer Bug gemeldet?
Agenten anweisen, den Fix immer mit einem REG-Test abzusichern
Shared-Code-Arbeit?
Immer auf dem pilot-Branch starten — nie direkt auf main

📘 Wenn ein Agent einen neuen Bug fixt: (1) Test in src/test/regression/core-logic.test.ts schreiben, (2) Bug in AGENTS.md Abschnitt "Bekannte Bugs" dokumentieren, (3) Commit-Message mit [REG-XXX] kennzeichnen (nächste freie Nummer).
Zusammenfassung
Vorher
Jeder Push
→ alle 45 Apps bauen → ~$2.500 in einer Monatshälfte
Bugs kehren zurück
Agenten wissen nicht, was kritisch ist → Fixes werden überschrieben
Jetzt ✅
Nur betroffene App baut
~95% Kostenersparnis — $50–150 statt $2.500
Shared Code: erst Pilot
Testen an 1 App → dann alle — kontrolliert und günstig
113 Tests schützen alles
Kein kritischer Bug kehrt je unbemerkt zurück
AGENTS.md zuerst
Jeder Agent weiß, was er nicht anfassen darf
Die Plattform ist jetzt so strukturiert, dass 10 verschiedene Agenten gleichzeitig daran arbeiten können — ohne sich gegenseitig zu beschädigen. Strukturell erzwungen, dokumentiert und durch automatische Tests dauerhaft gesichert.