# 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`](PROJECT_EVALUATION_2026-07-26.md), das
visuelle Seitenaudit in
[`audits/2026-07-26/PAGE_AUDIT.md`](audits/2026-07-26/PAGE_AUDIT.md), und die
Zugriffskontrollanalyse in
[`SECURITY_SPOT_CHECK_2026-07-26.md`](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

```mermaid
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.