@tuskira/gateway-web

Admin-Konsole für das Tuskira AI Agent Gateway. React 19 + Vite + TypeScript (strict) + Tailwind CSS 4 + shadcn/ui.

Entwickeln

Erfordert Node 26+ und npm 11+ (kein pnpm).

npm install
npm run dev

Der Dev-Server leitet /api an http://localhost:8081 weiter (siehe vite.config.ts), also betreibe das Gateway auf :8081 parallel zur UI. Melde dich unter /login mit einem API-Schlüssel (gk_…) an, der vom Gateway ausgestellt wurde.

Vom Repo-Root aus kannst du stattdessen ausführen:

make ui-install
make ui-dev

Build

npm run build

Erzeugt ein Produktions-Bundle in dist/. In der Produktion serviert das Gateway selbst dieses Bundle unter / auf :8081, sodass die App same-origin mit der API kommuniziert — kein Proxy nötig.

make ui-build   # vom Repo-Root aus

Qualitätsprüfungen

npm run lint        # eslint
npm run typecheck    # tsc --noEmit (project references)
npm run test         # vitest
npm run format:check # prettier --check

Hinzufügen einer shadcn/ui-Komponente

npx shadcn@latest add <component>

Die components.json dieses Projekts zielt auf das Vite-Template, die radix-Basis, die neutral-Basisfarbe und CSS-Variablen für das Theming ab, wobei der Import-Alias @/* auf src/* aufgelöst wird. Neue Komponenten werden nach src/components/ui/ geschrieben.

Design-Tokens

tokens.json (Repo-Root) ist die einzige Quelle der Wahrheit für das Design-System — Farben, Abstände, Radien, Schatten, Schriften. Führe nach der Bearbeitung npm run gen:tokens aus, um Folgendes neu zu generieren:

• src/styles/tokens.css — die rohen Tokens als CSS-Custom-Properties (:root für Light-Werte, .dark für Dark-Overrides), wobei die eigenen Token-Namen des Designers beibehalten werden (--indigo-9, --sev-high, --r-4, --shadow-1, ...).
• src/styles/tokens.ts — dieselben kategorischen Farbskalen (colors.indigo, colors.slate, colors.sev, colors.status, colors.brand) plus fonts, radii, shadows, für Nicht-CSS-Konsumenten (z. B. recharts-Serienfarben).

src/index.css mappt shadcns semantische Variablen (--background, --primary, --sidebar, ...) auf diese Tokens und registriert Tailwind v4 @theme-Einträge, sodass Utilities wie bg-indigo-9, text-text-muted, border-border-strong, shadow-1, rounded-r-4 und font-mono überall in der App verfügbar sind. Bearbeite src/styles/tokens.css / src/styles/tokens.ts nicht manuell — sie werden vom Generator überschrieben. src/test/tokens.test.ts stellt sicher, dass jeder tokens.ts-Eintrag eine passende Deklaration in tokens.css hat.

Ordnerstruktur

web/
├── index.html
├── vite.config.ts        # React + Tailwind plugins, /api dev proxy, vitest config
├── components.json        # shadcn/ui config
├── tokens.json             # design-token source of truth (see Design tokens)
├── scripts/
│   └── gen-tokens.mjs        # tokens.json -> src/styles/tokens.{css,ts}
├── src/
│   ├── main.tsx            # ReactDOM root
│   ├── App.tsx              # QueryClientProvider, AuthProvider, RouterProvider
│   ├── index.css            # Tailwind entrypoint + semantic token mapping
│   ├── styles/
│   │   ├── tokens.css         # generated — raw design tokens as CSS vars
│   │   └── tokens.ts           # generated — same tokens for non-CSS use
│   ├── auth/
│   │   ├── AuthContext.tsx    # AuthProvider / useAuth — principal, signIn, signOut
│   │   └── RequireAuth.tsx    # route guard for the authenticated shell
│   ├── components/
│   │   ├── ui/                 # shadcn/ui primitives (generated, don't hand-edit)
│   │   ├── layout/              # AppShell, Sidebar, TopBar
│   │   └── app/                  # ComingSoon, StatCard
│   ├── hooks/
│   │   └── use-theme.ts          # light/dark toggle, class strategy, localStorage
│   ├── lib/
│   │   ├── api.ts                 # fetch wrapper: bearer auth, 401 handling, ApiError
│   │   ├── nav.ts                  # single source of truth for sidebar nav + routes
│   │   ├── queries.ts                # react-query hooks (useHealth)
│   │   ├── query-client.ts            # QueryClient instance
│   │   ├── types.ts                    # Principal, HealthResponse, ApiErrorBody
│   │   └── utils.ts                     # cn() (shadcn)
│   ├── routes/
│   │   ├── router.tsx                    # createBrowserRouter (data router)
│   │   ├── LoginPage.tsx
│   │   ├── OverviewPage.tsx
│   │   └── DocsPage.tsx
│   └── test/
│       ├── setup.ts
│       ├── LoginPage.test.tsx
│       ├── Sidebar.test.tsx
│       ├── SignOut.test.tsx
│       └── tokens.test.ts