Proposal: Web-UI zum Verstehen & Navigieren des Codes

Status: Diskussionsgrundlage (noch keine Implementierung). Dieses Dokument hält die abgestimmte Vision, Architektur, die nötigen Backend-Voraussetzungen und einen Milestone-Plan fest. Sprache: Deutsch (Diskussionskontext); bei Bedarf auf Englisch umstellbar — der Rest von x-docs/ ist englisch.

1. Ziel & Kontext

Eine React/TypeScript-Weboberfläche, die den AgenticCode-Graphen für Menschen begreifbar macht: durch Legacy-Quellen (v. a. Software AG Natural) navigieren, den Code sehen (Call-Graph, Datenfluss, DB-Zugriffe) und ihn verstehen. Sie setzt auf der bestehenden REST-API auf (/api/projects/{p}/…).

Primärer Nutzer & Hauptziel (abgestimmt): Entwickler, die Legacy-Natural verstehen, um es nach Java zu migrieren. Der Wert liegt darin, das Verhalten eines Moduls schnell vollständig zu erfassen: Wer ruft es? Was ruft es (inkl. dynamischer CALLNAT)? Welche Felder fließen wohin? Welche DB-Tabellen liest/schreibt es? Was bricht, wenn ich etwas ändere?

2. Abgestimmte Entscheidungen (prägen die Architektur)

Frage	Entscheidung	Konsequenz
Primärnutzer/Ziel	Migration Natural→Java	Leitmotiv „Migrations-Dossier" pro Modul (M3/M4)
Projektgröße	Groß (`upms` ~1000–6000+ Module)	Query-getrieben, WebGL-Viz, serverseitiger Subgraph
API-Vertrag	OpenAPI zuerst	SmallRye-OpenAPI am Server + generierter TS-Client (kein Typ-Drift)
Lazy-Ingest	Automatisch + Statusanzeige	Navigation triggert Deep-Ingest transparent; Status/Ladezustände überall

3. Architektur-Grundsätze

Query-getrieben, nie „ganzen Graphen laden". Bei 6000+ Modulen wird immer nur eine begrenzte Nachbarschaft um den aktuellen Knoten geladen.
WebGL-Graph-Rendering. Sigma.js (auf graphology) für Tausende Knoten flüssig. React Flow bleibt für kuratierte Kleindiagramme (ein Datenfluss-Pfad, eine direkte Nachbarschaft), ist aber für den großen Graphen ungeeignet (DOM-basiert).
OpenAPI-first. Der Server bekommt eine OpenAPI-Spec; der TS-Client wird generiert (openapi-typescript + openapi-fetch). Ein stabiler Vertrag statt handgepflegter Typen.
Auto-Ingest mit Statusanzeige. Klick auf ein noch flaches Modul triggert den Deep-Ingest transparent; die UI zeigt INGESTING und lädt nach. Refresh explizit verfügbar.
Stabile Identität statt Node-ID. Node-ids werden bei Re-Ingest neu vergeben — die UI keyed auf name + sourceFile und refetcht nach einem Ingest.

4. Technischer Stack (Vorschlag)

React + TypeScript + Vite, React Router (URL-getriebener State → teilbare Deep-Links auf einen Knoten/eine Ansicht).
Datenschicht: TanStack Query über den generierten OpenAPI-Client.
Graph-Viz: Sigma.js/graphology (+ graphology-layout-forceatlas2/dagre-artige Layouts); React Flow für Kleindiagramme.
Code-Viewer: CodeMirror 6 mit eigenem Natural-Sprachmodus (kein OSS-Highlighting vorhanden) + Java eingebaut.
Styling: Tailwind oder CSS-Module (Detail offen).

5. Backend-Voraussetzungen (die die UI erzwingt)

Diese Punkte sind Bring-Schulden am Server, bevor die UI tragfähig ist:

OpenAPI-Spec (quarkus-smallrye-openapi) + saubere Annotation der Response-DTOs.
Ego-Graph-Endpoint — GET /modules/{name}/graph?depth=&direction=&limit=, der einen begrenzten Subgraphen (Nodes + Edges) um einen Knoten liefert. Heute gibt es nur call-tree/callers/callees getrennt; die Viz braucht einen echten, gebündelten Nachbarschafts-Endpoint. (Neuer Roadmap-Kandidat.)
Ingest-Status im Response — die UI muss ingestStatus/ingestDepth je Modul kennen (großteils vorhanden über moduleIngestState/inspect_node).
CORS/Serving — SPA-Auslieferung + CORS-Konfiguration am Quarkus-Server.
Später: Auth/Multi-User (heute keine), Cross-Project-Sichten.

Verfügbar & wiederverwendbar (heute): list_modules, module_context, callers/callees, call-tree, db-accesses/sql-statements, data-structures/ fields/columns, dispatch-table, search/identifier|value|annotation, variables/{n}/reads|writes|flow-forward|flow-backward|field-flow, nodes/{id}, modules|nodes/{…}/source, refresh.

6. Kern-Ansichten (was der Mensch tun können soll)

Projekt- & Modul-Explorer — Liste/Baum, Filter (Sprache, moduleKind, sourceFile), globale Suche.
Modul-Detail — module_context gebündelt: Funktionen, Caller/Callee, DB-Zugriffe, Datenstrukturen, Ingest-Status, Refresh.
Quelltext-Viewer mit Graph-Overlay — Syntax-Highlighting; klickbare Identifier → Definition/Referenzen; CALLNAT/PERFORM-Ziele als Links; dynamische/unaufgelöste Referenzen markiert.
Interaktiver Call-Graph (Sigma/WebGL) — Ego-Graph, Expand/Collapse, Dispatch- & unresolved-Styling, Auto-Layout.
Datenfluss-Visualisierung — flow-forward/backward/field-flow als Pfad/Sankey.
DB-Zugriffs-Karte — Matrix/Graph Modul ↔ Tabelle (READ/WRITE), Dispatch-Tabellen, SQL.
Impact-Analyse — „Feld/Tabelle ändern → betroffene Module".
Migrations-Dossier — pro Modul alle obigen Facetten gebündelt als „Portier-Steckbrief".

7. Milestones

M0 · Fundament + API-Vertrag — OpenAPI am Server + generierter TS-Client; Ego-Graph-Endpoint; CORS/SPA-Serving; React/Vite-Grundgerüst; Projekt-/Modul-Liste
- Suche; Ingest-Status-Badges + Refresh. → Browsen & Lesen; kritischer Pfad.
M1 · Navigation — Quelltext-Viewer (CodeMirror 6 + Natural-Modus), klickbare Identifier (Def/Refs), Caller/Callee-Panels, lazy Call-Tree, Deep-Links.
M2 · Call-Graph-Visualisierung — Ego-Graph interaktiv (Sigma), Expand/Collapse, Dispatch/Unresolved-Styling, Layout.
M3 · Migrations-Dossier — Datenstrukturen/Felder, DB-Zugriffs-Matrix, Dispatch-Tabellen, SQL — pro Modul gebündelt.
M4 · Datenfluss & Impact — Flow-Visualisierung, Impact-Analyse „was bricht?".
M5 · Verständnis-Booster — Quelle + geparste Struktur nebeneinander, Notizen/ gespeicherte Views, Diff nach Refresh, optional LLM-Zusammenfassungen aus module_context.
M6 · Skalierung & Politur — Virtualisierung/Große-Graph-Performance, Multi-Projekt, Auth, Theming, Export (SVG/PNG/Report).

Kritischer Pfad: M0 (OpenAPI + Ego-Graph-Endpoint) trägt alles Weitere.

8. Risiken & offene Punkte

Latenz durch Auto-Ingest bei großen Projekten: Erkunden triggert Deep-Ingests; der Concurrency-Cap (Default 2) kann unter Mehr-Nutzer-Last transient flachere Antworten liefern. Für 1 Analyst ok; sonst Cap konfigurierbar/erhöhen.
STALE_SOURCE & Warm-Nebenwirkung: eine wärmende Abfrage (z. B. search_identifier) re-ingestiert und re-hasht ein Modul und löscht damit dessen Staleness — die UI muss Ingest-Status als „wahr im Moment der Abfrage" behandeln.
Node-ID-Instabilität nach Re-Ingest (Keying auf name+sourceFile).
Natural-Highlighting existiert nicht fertig — eigener CodeMirror-Modus nötig.
Auth/Multi-User und Deploy-Modell (Standalone-SPA vs. eingebettet) noch offen.

9. Nicht in diesem Vorhaben

Änderungen an der Parser-/Ingest-Semantik (die UI ist ein Konsument).
Schreibender Zugriff auf den Code (read-only Verständnis-Tool; Notizen sind UI-seitig).

7.6 KiB Raw Permalink Blame History Unescape Escape