nexus/docs/PROJECT_ANALYSIS_2026-07-26.md

Nexus – Projektanalyse

Analysestand: 2026-07-26 Repository: https://git.noveria.net/bao/nexus.git Branch / Commit: main / 3bc7622977f4a6c2f2e98ab4aa856a2e45c3cf49 Version im Repository: 0.2.56 (v0.2.56-91-g3bc7622) Urteil: Gute technische Grundlage, aber wegen zweier P0-Zugriffskontrollrisiken und schwerer Frontend-/Responsive-Brüche aktuell nicht produktionsreif.

1. Kurzfassung

Nexus ist deutlich mehr als ein UI-Prototyp: Das Repository enthält ein geschichtetes ASP.NET-Core-Backend, eine persistente PostgreSQL-Domäne, OpenClaw-Adapter, eine strukturierte Agent-Task-Bridge, eine Vue-Anwendung sowie CI-, Deployment-, Backup- und Rollback-Workflows. Die Backend- und Operations-Basis ist der stärkste Teil des Projekts.

Die aktuelle Produktqualität wird jedoch von vier systemischen Problemen bestimmt:

1. Die API hat keine globale Authentifizierungsanforderung. Mehrere Controller sind dadurch ohne Token erreichbar; darunter befindet sich ein mutierender Agent-Command-Endpunkt.
2. Die öffentlich weitergeleitete Bridge akzeptiert eine bekannte X-Agent-Id allein als Identitätsnachweis.
3. Das Frontend besteht aus zwei visuell und technisch auseinanderlaufenden Shells. Dashboard-Navigation, Dateninitialisierung und mobile Breakpoints sind nicht konsistent.
4. Die Testabdeckung ist im Backend fokussiert, im Frontend mit einer Testdatei aber zu schmal für 18 registrierte Seiten und mehrere kritische Interaktionspfade.

Die vollständige Bewertung steht in PROJECT_EVALUATION_2026-07-26.md, das visuelle Seitenaudit in audits/2026-07-26/PAGE_AUDIT.md, und die Zugriffskontrollanalyse in SECURITY_SPOT_CHECK_2026-07-26.md.

2. Technischer Bestand

Bereich	Befund
Umfang	253 getrackte Dateien
Frontend	Vue 3, TypeScript, Pinia, Vue Router, Vite, Tailwind 4, Lucide
Backend	ASP.NET Core 10, EF Core 10, PostgreSQL 17
Integration	IAgentRuntime, OpenClaw-Adapter, MCP- und HTTP-Task-Bridge
Persistenz	9 fachliche EF-Core-Migrationen
Betrieb	Docker Compose, Nginx, Traefik, Gitea Actions
Backend-Code	107 C#-Dateien plus 12 C#-Testdateien
Frontend-Code	87 Dateien unter frontend/src, davon 51 Vue-Dateien
Frontend-Tests	1 Testdatei mit 2 Tests
CI-Baseline	.NET 10, Node.js 24, pnpm 10.12.1

3. Architektur

flowchart LR
    UI["Vue SPA<br/>Routes, Views, Pinia"] -->|JWT / REST / SSE| API["ASP.NET Core API"]
    API --> CTRL["Controller"]
    CTRL --> SVC["Domain and application services"]
    SVC --> REPO["Repositories / EF Core"]
    REPO --> DB["PostgreSQL"]
    SVC --> RUNTIME["IAgentRuntime"]
    RUNTIME --> OPENCLAW["OpenClaw adapter"]
    GATEWAY["Trusted agent gateway"] -->|Bridge commands| BRIDGE["GatewayBridgeController"]
    BRIDGE --> TASKBRIDGE["ITaskBridgeService"]
    TASKBRIDGE --> REPO

Backend

Positiv:

• Controller, Services und Repositories sind klar getrennt.
• Task-Mutationen werden über eine strukturierte ITaskBridgeService-Fassade gebündelt.
• EF-Core-Migrationen, Health Checks und DTOs sind vorhanden.
• JWT-Prüfung validiert Signatur, Issuer, Audience und Laufzeit.
• Refresh Tokens werden rotiert und gehasht gespeichert.
• Rate Limiting, CSP und weitere Security Header sind eingerichtet.

Risiken:

• AddAuthorization() besitzt keine Fallback Policy. Sicherheit hängt damit vollständig von jedem einzelnen [Authorize]-Attribut ab.
• Das Backend targetiert net10.0, aber es gibt kein global.json, das die erwartete SDK-Familie lokal festlegt.
• Produktionspfade für Workspace-Mounts und Deployment sind stark an einen konkreten Host gekoppelt.
• Das einmalige Bootstrap-Passwort wird in den Prozess-Logs ausgegeben. Das ist operativ bequem, erzeugt aber einen sensiblen Log-Artefakt.

Frontend

Positiv:

• API-Clients, Stores, Mapper, Views und UI-Komponenten sind grundsätzlich getrennt.
• Es gibt eigenständige Oberflächen für Tasks, Agenten, Memory, Dokumente, Security, Incidents, Calendar, Notifications und Settings.
• Settings und Teile der Legacy-Shell verhalten sich auf kleinen Viewports bereits brauchbar.

Risiken:

• /dashboard verwendet NexusLayout und FlowBoard; fast alle anderen Seiten verwenden AppSidebar, AppHeader und teils ModuleView. Das führt zu einem sichtbaren Design- und Navigationsbruch.
• Die neue Sidebar verlinkt /orchestration, /research, /hosts und /costs, obwohl keine dieser Routen registriert ist. Der Wildcard-Redirect maskiert den Fehler und führt zurück zum Dashboard.
• AgentDetailView navigiert über /team; auch diese Route existiert nicht.
• Der Operations Store wird in App.vue nur beim ersten Mount aktualisiert, wenn zu diesem Zeitpunkt bereits Authentifizierung vorliegt. Nach normalem Login bleiben Projects, Models und Activity zunächst leer, bis der Nutzer manuell „Refresh“ auswählt.
• liveSync.ts und live-sync.ts implementieren denselben Pinia-Store mit derselben ID. Das ist ein unnötiger Drift- und Importfehler-Risikofaktor.
• Task-Daten unterstützen Critical; die Prioritätsauswahl in Task Board und Task Detail bietet aber nur High, Medium und Low. Ein bestehender Critical-Wert erscheint deshalb als leere Auswahl.
• Mehrere sichtbare Controls sind Platzhalter: Suche, „Ask Iris“ und Logout in der neuen Dashboard-Shell haben keine vollständige Aktion.
• Zahlreiche Icon-Buttons besitzen keinen zugänglichen Namen.

4. Daten- und Produktfluss

Der zentrale Betriebsfluss ist sinnvoll modelliert:

1. Das Frontend lädt einen Operations-Snapshot und spezialisierte Detailressourcen.
2. Nutzer ändern Projekte und Tasks über authentifizierte API-Routen.
3. Agenten sollen strukturierte Commands über die Bridge an ITaskBridgeService senden.
4. Services validieren Zustände und schreiben über Repositories in PostgreSQL.
5. Activity- und Live-Updates werden wieder in der Oberfläche dargestellt.

Die Schwäche liegt nicht im Domänenfluss, sondern an seinen Grenzen: Browser-Authentifizierung, Service-Authentifizierung und UI-Initialisierung sind nicht durchgehend als verbindliche Verträge umgesetzt.

5. Qualität nach Bereich

Architektur und Wartbarkeit

Die Backend-Struktur ist nachvollziehbar und erweiterbar. Der aktuelle Frontend-Zustand deutet dagegen auf eine laufende V2-Migration ohne klares Migrationsende hin. Zwei Shells, tote Routen, ein verwaistes TeamView und doppelte Stores erhöhen die Änderungs- und Regressionkosten.

Tests

Die zwölf Backend-Testdateien decken insbesondere Auth-, Task-, Bridge- und MCP-Verhalten ab. Die Frontend-Suite besteht aktuell aus einer Testdatei mit zwei Tests. Es fehlen mindestens:

• Router- und Navigationsverträge,
• Store-Hydration nach Login,
• Critical-Priority-Roundtrip,
• Keyboard-/Accessible-Name-Prüfungen,
• Komponenten- und Viewport-Regressionstests,
• visuelle Smoke-Checks für alle Kernrouten.

CI/CD und Betrieb

Die Gitea-Pipeline ist für die Projektgröße gut ausgebaut:

• getrennte Backend-, Frontend- und Security-Jobs,
• Build und Tests vor Deployment,
• serielles Production Deployment,
• separate Backup- und Rollback-Workflows.

Der Security-Job sucht jedoch nur heuristisch nach Secrets. Er ersetzt weder Dependency-/Container-Scanning noch eine Zugriffskontrollprüfung. Außerdem deployt ein grüner Push auf main automatisch; deshalb müssen P0-Sicherheits- und UI-Regressionsgates vor einem Merge verbindlich sein.

Dokumentation

README, Phasen-, Architektur- und Betriebsdokumentation sind umfangreich, aber teilweise nicht mehr synchron mit dem Code:

• README behauptet Authentifizierung für alle /api/v1-Operationsrouten, die Controller-Attribute erfüllen diesen Vertrag nicht.
• Frontend-Routen und Komponentenbeschreibungen spiegeln die V2-/Legacy-Mischung nicht vollständig.
• VERSION ist 0.2.56, das Frontend-Paket meldet 0.1.0, und der aktuelle Commit liegt 91 Commits hinter dem letzten Tag.

6. Validierungsstand

Erfolgreich ausgeführt:

• pnpm test: 1 Datei, 2 Tests bestanden.
• pnpm build: TypeScript-/Vue-Typecheck und Vite-Production-Build bestanden.
• dotnet test im offiziellen .NET-10-SDK-Container: 189 Tests bestanden, 0 fehlgeschlagen, 0 übersprungen.
• Browser-Audit aller 18 registrierten Seiten mit repräsentativen lokalen API-Fixtures.
• Responsive Sichtprüfung bei 320, 375, 768, 1024, 1440 und 1920 Pixeln.

Nicht als bestanden gewertet:

• Kein Live-End-to-End-Test gegen PostgreSQL, OpenClaw, SSE und die Produktions-Proxykette.
• Kein Penetrationstest und keine vollständige WCAG-Konformitätsprüfung.

Der Windows-Host stellt direkt nur .NET SDK 9.0.301 bereit. Der erfolgreiche Backend-Lauf erfolgte deshalb reproduzierbar im offiziellen mcr.microsoft.com/dotnet/sdk:10.0-Container.

7. Empfehlung

Nexus sollte nicht neu gebaut werden. Die vorhandene Backend- und Operationsbasis ist wertvoll. Sinnvoll ist eine fokussierte Stabilisierungsphase:

1. Zugriffskontrollen schließen und durch negative Tests absichern.
2. Eine einzige Frontend-Shell und eine einzige kanonische Navigation festlegen.
3. Login-Hydration, tote Routen, Critical-Priority und doppelte Stores beheben.
4. Dashboard und Task Board für 375–1024 px strukturell neu ordnen.
5. Frontend-Tests und visuelle Route-/Breakpoint-Gates etablieren.
6. README, Versionierung und SDK-Pinning auf den tatsächlichen Stand bringen.