Architektur

Diese Seite erklärt die Komponenten des sellx Hub und wie sie zusammenspielen - Tauri-Shell, React-Frontend, .NET-Sidecar und die Anbindung an JTL-Wawi sowie sellx Central.

Entwickler-Handbuch · Architektur

Komponenten-Übersicht

textarchitektur-uebersicht.txt

┌─────────────────────────────────────────────────────────────────┐
│ sellx Hub (auf Kunden-Server)                                   │
│                                                                 │
│  ┌──────────────────────┐    ┌──────────────────────────────┐  │
│  │ Tauri Shell (Rust)   │    │ .NET 8 Sidecar (Kestrel)    │  │
│  │  - WebView2 Fenster  │    │  - Port 0 (OS wählt)        │  │
│  │  - Sidecar-Spawning  │◄──►│  - SQL Executor             │  │
│  │  - IPC-Bridge        │    │  - License Validator        │  │
│  │  - Auto-Updater      │    │  - Plugin Engine            │  │
│  └──────────┬───────────┘    │  - EF Core SQLite (lokal)   │  │
│             │                └──────────┬───────────────────┘  │
│             │                           │                      │
│  ┌──────────▼───────────┐               │                      │
│  │ React Frontend       │               │                      │
│  │  - shadcn/ui         │               │                      │
│  │  - Zustand State     │               │                      │
│  │  - TanStack Query    │               │                      │
│  │  - Recharts          │               │                      │
│  └──────────────────────┘               │                      │
│                                          │                      │
└──────────────────────────────────────────┼──────────────────────┘
                                           │
                  ┌────────────────────────┼──────────────┐
                  │                        │              │
                  ▼                        ▼              ▼
        ┌──────────────────┐    ┌──────────────────┐   ┌──────────────┐
        │ JTL-Wawi SQL     │    │ sellx Central    │   │ Lokale       │
        │ Server           │    │ (Cloud)          │   │ SQLite       │
        │ (extern)         │    │                  │   │              │
        │                  │    │ - Katalog        │   │ %APPDATA%   │
        │ - eazybusiness   │    │ - Lizenzen       │   │ sellx-hub   │
        │ - tArtikel,      │    │ - Heartbeat      │   │ data.db      │
        │   tKunde, ...    │    │ - Updates        │   │              │
        └──────────────────┘    └──────────────────┘   └──────────────┘

Drei Schichten

Schicht 1 — Tauri Shell (Rust)

Datei: sellx-hub/src-tauri/src/main.rs

Verantwortlichkeiten:

Erzeugt das native WebView2-Fenster
Startet und überwacht den .NET-Sidecar-Prozess (tokio::process::Command)
Stellt IPC-Bridge bereit (#[tauri::command]-Funktionen)
Verwaltet Auto-Updates

Wichtige Konstanten:

Konstante	Wert	Bedeutung
sidecar-dir	<exe-dir>/sellx-sidecar/	Pfad zum Sidecar
sidecar-port-file	%APPDATA%/sellx-hub/sidecar-port.txt	Sidecar schreibt hier seinen Port hinein
sidecar-startup-timeout	15 Sekunden	30 Versuche × 500 ms

Schicht 2 — React Frontend (WebView2)

Verzeichnis: sellx-hub/src/

Verantwortlichkeiten:

Rendert die gesamte Benutzeroberfläche
Kommuniziert über Tauri-IPC oder lokales HTTP mit dem Sidecar
Enthält keine Geschäftslogik — reine Darstellungsschicht

Stack:

Bibliothek	Version	Zweck
React	18	UI-Framework
Vite	6	Build-Tool, Dev-Server
TypeScript	5.6	Typsicherheit
Tailwind CSS	4	Styling
shadcn/ui	aktuell	UI-Komponenten (kopiert, nicht installiert)
Zustand	5	Client-State (mit Persist)
TanStack Query	5	Server-State-Caching
TanStack Table	8	Sortier-/filterbare Tabellen
Recharts	2	Diagramme (für Dashboard-Plugins, geplant)
React Router	7	Navigation

Schicht 3 — .NET 8 Sidecar

Verzeichnis: sellx-sidecar/SellxSidecar/

Verantwortlichkeiten:

Lokaler HTTP-Server (Kestrel, zufälliger Port)
SQL-Executor gegen JTL-Wawi
Plugin-Engine (Loader, Encryptor, Executor)
Lizenz-Validator (JWT)
Hardware-Fingerprint-Berechnung
Lokaler Plugin-Store (verschlüsselte SQL-Files)
Heartbeat-Endpoint (gegen sellx Central)

Wichtige Services:

Service	Zweck
SqlExecutorService	Führt SQL-Queries gegen JTL-DB aus
SqlSecurityValidator	Validiert SQL vor Ausführung
LicenseService	JWT-Validierung, Token-Version-Check
CentralMockService	Mock für sellx Central (im MVP)
PluginLoader	`.sellxpkg` entpacken, installieren
HubDbContext	EF Core gegen lokale SQLite

Datenflüsse

Frontend → Sidecar

textdatenfluss-frontend-sidecar.txt

React invoke("execute_plugin", { pluginId, queryId, parameters })
       │
       ▼
Tauri-IPC: main.rs::execute_plugin()
       │
       ▼
HTTP POST http://localhost:{port}/api/plugins/{id}/execute
       │
       ▼
SqlExecutorService.ExecuteAsync()
       │
       ▼
Microsoft.Data.SqlClient → JTL-Wawi SQL Server
       │
       ▼ (rows)
Response → React → DataTable

Sidecar → sellx Central

textdatenfluss-sidecar-central.txt

Heartbeat-Trigger (alle 24h oder konfiguriert)
       │
       ▼
HTTPS POST https://central.sellx.de/api/hub/heartbeat
       │
       ▼
JWT refresh, Token-Version-Update, Update-Check

Plugin-Installation

textdatenfluss-plugin-install.txt

React: User wählt .sellxpkg-Datei
       │
       ▼
Tauri: install_plugin(filePath)
       │
       ▼
Sidecar: /api/plugins/install
       │
       ▼
1. ZIP entpacken
2. manifest.json parsen + validieren
3. SQL-Files mit AES-256-GCM verschlüsseln
4. In Plugin-Store ablegen (SQLite + Filesystem)

Hardware-Fingerprint

Siehe ADR-0001 (wird nachgepflegt) für die Policy-Entscheidung.

Der Fingerprint setzt sich zusammen aus:

Komponente	Quelle
MachineGUID	HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid
SQL Server Instance Name	aus Connection-String
Installationspfad-Hash	SHA-256 von `<INSTALL_DIR>`

Ergebnis: hexadezimaler String, der die Lizenz an diese spezifische Installation bindet.

Datenpersistenz

Daten	Speicherort
Hub-Config (DB-String, Lizenz-Token, Master-Key-Seed)	%APPDATA%\sellx-hub\data.db (Tabelle hub_config)
Plugin-Metadaten	%APPDATA%\sellx-hub\data.db (Tabelle plugins)
Verschlüsselte SQL-Queries	%APPDATA%\sellx-hub\plugins\<id>\*.sql.enc
Open-Tabs-State	%APPDATA%\sellx-hub\data.db (Tabelle open_tabs)
Lizenz-Token (Cache)	%APPDATA%\sellx-hub\license.jwt
Logs	%APPDATA%\sellx-hub\logs\<date>.log

Sicherheits-Layer

Layer	Schutz
SQL-Validator	Single-Statement, keine EXEC/xp_/sp_/OPENROWSET, keine Kommentare
Parametrisierung	Alle `@{Key}` → ADO.NET-Parameter, kein String-Concatenation
Hardware-Fingerprint	Lizenz an Maschine gebunden
Token-Version	Sofortige Revocation ohne JWT-Ablauf
Grace-Period	30 Tage Offline-Toleranz nach Subscription-Ende
AES-256-GCM	Verschlüsselung der Plugin-SQL-Queries