braedonsaunders/codeflow: GitHub-Repositorys als interaktive Architekturkarte im Browser

Paste-to-Map: wie CodeFlow aus einer GitHub-URL eine Architekturkarte macht

Wer ein fremdes Codeprojekt öffnet, kennt das Gefühl der Orientierungslosigkeit. CodeFlow aus dem Repository braedonsaunders/codeflow will dieses Problem in Sekunden lösen: Man fügt eine GitHub-URL ein oder wählt lokale Dateien, und der Browser zeigt eine interaktive Architekturübersicht. Keine Installation, kein Konto, der Kernablauf liest sich als Kette Paste URL, Architektur ansehen, bessere Entscheidungen treffen. Öffentliche Repositories reichen als Eingabe von facebook/react bis zur vollständigen URL.

Das Projekt ist MIT-lizenziert, die Hauptsprache des Repos ist HTML, und die gehostete Instanz läuft unter codeflow-five.vercel.app. Mit über 5.000 Sternen ist die Sammlung beachtet, ein offenes Issue zeigt eine ruhige Issue-Wartung. Für private Repositories verlangt das Tool einen GitHub Personal Access Token mit repo-Berechtigung, der im Tokenfeld eingetragen wird und laut README nur im Browserspeicher lebt.

Ohne Build-Schritt: index.html, vendor/ und die pinned Deps

Das Selbsthosting fällt ungewöhnlich schlicht aus: git clone https://github.com/braedonsaunders/codeflow.git, danach open index.html. Kein Build-Prozess, kein npm install. Die Erklärung liegt im vendor/-Ordner, aus dem index.html gepinnte, im Repository eingecheckte Browser-Abhängigkeiten lädt, darunter React 18, D3.js 7 und Babel für JSX, jeweils mit Quell-URLs, SHA-256-Prüfsummen und Lizenzhinweisen dokumentiert.

Deshalb funktioniert ein frischer lokaler Start laut README auch ohne Netzwerkverbindung, und die lokale Dateianalyse läuft offline. Ein Skript namens scripts/vendor-browser-deps.mjs aktualisiert diese Abhängigkeiten, wenn sie erneuert werden müssen. Als dritter Weg dient die CLI: npx codeflow . bedient dieselbe index.html-Oberfläche, beobachtet den Ordner und öffnet ihn im Browser. Für Teams ohne Bereitschaft, Code durch fremde Hosts zu schicken, ist der geklonte Stand damit die einzige Konfiguration, die nötig ist.

Blast Radius und Health Score: die Analyseausgaben von CodeFlow

Der interaktive Abhängigkeitsgraph zeigt, wie Dateien verbunden sind; ein Klick auf einen Knoten hebt seine Abhängigkeiten hervor, Drag und Zoom erlauben das Erkunden. Die Code-Ansicht behält die Karte und öffnet die gewählte Datei samt verbundener Dateien als Ganzseiten-Karten auf der Leinwand, gruppiert nach Verzeichnis. Die Blast-Radius-Analyse beantwortet die Frage, was bricht, wenn man eine Datei ändert, mit der Zahl der betroffenen Dateien.

Dazu kommen Code-Eigentum aus der Git-Historie, also die Top-Beitragenden pro Datei, Mustererkennung für Singletons, Factories, Observer- und Ereignismuster, React Custom Hooks sowie Antipatterns wie God Objects und starke Kopplung. Der Health Score vergibt eine Note von A bis F auf Basis von totem Code, zirkulären Abhängigkeiten, Kopplungsmetriken und Sicherheitsbefunden. Eine Aktivitäts-Heatmap färbt Dateien nach Commit-Häufigkeit, und eine PR-Auswirkungsanalyse akzeptiert eine PR-URL, um den Blast Radius geplanter Änderungen zu berechnen.

Datenschutzmodell: GitHub-Token nur im Browser, Code bleibt lokal

Das Datenschutzmodell ist konsequent auf den Browser verlagert: CodeFlow läuft vollständig clientseitig, macht GitHub-API-Aufrufe direkt aus dem Browser und speichert laut README weder Code noch Tokens, Analytics oder Tracking fehlen ganz. Der GitHub-Token, falls verwendet, liegt nur im Browserspeicher und wird beim Schließen des Tabs gelöscht. Die lokale Dateianalyse verarbeitet Ordner und Dateien vollständig im Browser, per Klick auf Open Folder oder per Drag and Drop, sodass der Code die Maschine nie verlässt.

Vor dem Scan werden generierte Abhängigkeiten und Caches automatisch beschnitten, etwa node_modules, .next, .turbo, .local, dist und playwright-report; eigene Ausschlussmuster für Upload- und Cache-Verzeichnisse oder Bilddateien wie PNG lassen sich vor dem Scan ergänzen. Einzelne Dateien über 2 MB bleiben in den Ergebnissen sichtbar, ihr Inhalt wird aber nicht geparst. Nach der Analyse erzeugt ein Share-Button einen Link, über den jeder dieselbe Analyse erneut ausführen kann; Exporte stehen als JSON, Markdown, einfacher Text, SVG und PDF bereit.

Die CodeFlow Card als GitHub Action im README

Neben der Web-Oberfläche enthält das Repository eine GitHub Action namens CodeFlow Card. Sie legt eine sich selbst aktualisierende SVG-Karte auf das eigene README, die bei jedem Merge vom selben Analyzer neu berechnet wird, der auch die Web-App antreibt. Angezeigt werden Gesundheitsnote, Umfang, Fragilität und versteckte Kosten, dokumentiert im Verzeichnis card/.

Die Karte bietet fünf Stile mit Akzentfarben-Voreinstellungen, passt sich automatisch an das helle oder dunkle Theme der Betrachter an und kann optional PR-Kommentare im Quittungsstil absetzen. Ein Datenschutzmodus für öffentliche Repositories verbirgt die Note, wenn man sie nicht öffentlich zeigen will. Für Repositories, die ihre Codegesundheit als sichtbares Signal pflegen möchten, ist das der praktischste Einstieg, weil die Action ohne eigene Infrastruktur auskommt und bei jedem Merge erneut rechnet.

Heuristische Grenzen von CodeFlow und die Offline-Alternative

Die README macht die Genauigkeitsgrenzen explizit. Funktionen werden nach Namen abgeglichen, doppelte Namen nur über Datei und explizite Imports eingegrenzt; dynamische Imports oder umbenannte Laufzeitreferenzen können übersehen werden. Die Pascal-Unterstützung ist als heuristisch markiert und erkennt Routinen, uses-Unit-Abhängigkeiten und Kommentarfilterung, ohne formale Spezifikation.

Auch der Security-Scanner arbeitet mit Ausschlüssen: Testdateien, Fixtures, docs/ und Tooling-Verzeichnisse wie .github/, .claude/ und scripts/ bleiben von den XSS- und Shell-Prüfungen außen vor, weil Funde dort nicht die Angriffsfläche des Produkts spiegeln. Die Prüfung auf hartcodierte Geheimnisse erfasst dagegen weiterhin CI-Workflows, Hooks und Deploy-Skripte, weil ein echtes Credential dort ein echtes Leck ist. Ohne Token liegt das GitHub-API-Limit bei 60 Anfragen pro Stunde, mit Personal Access Token bei 5.000; wer große Repositories analysiert, sollte daher einen Token eintragen. Als Offline-Alternative gilt der geklonte Stand mit index.html und den vendor-Abhängigkeiten, der ohne Netzwerk die gesamte lokale Analyse anbietet.

Redaktionelles Fazit

CodeFlow eignet sich für Entwickler, die sich vor Code-Reviews oder beim Onboarding schnell einen Überblick über eine fremde Codebasis verschaffen wollen, ohne Werkzeuge zu installieren. Weniger geeignet ist es als formales Analysewerkzeug, denn die Abhängigkeitsfindung ist heuristisch und liefert keine Genauigkeitsgarantien. Vor dem Vertrauen sollte man die Karte an einem eigenen Repository mit bekannter Struktur prüfen und kontrollieren, ob die erkannten Abhängigkeiten zu den tatsächlichen Imports passen.

Offizielle Quellen

1. Official documentation
2. Official README
3. Project repository