Architecture DE

Architektur

🌐 English · Deutsch

Die PDC Redbot Webapp ist eine SvelteKit-Anwendung, die als Backend-for-Frontend (BFF) vor einem Red-DiscordBot agiert. Der Browser spricht nie direkt mit dem Bot; stattdessen ruft er den SvelteKit-Server auf, der alle Geheimnisse hält und Anfragen über ein token-gesichertes JSON-RPC-Gateway des Companion-Cogs an den Bot weiterreicht. Diese Seite behandelt Stack, BFF-Muster, Gateway-Protokoll, Request-Flow und Projektstruktur.

Stack

Schicht	Technologie
Framework	SvelteKit (adapter-node)
Sprache	TypeScript
Styling	TailwindCSS (shadcn-svelte-Tokens)
Charts	Chart.js
Auth	Discord OAuth2 (serverseitig)
Transport zum Bot	JSON-RPC 2.0 über das Cog-Gateway
i18n	Deutsch + Englisch, vollständige UI-Übersetzung

Die zwei deploybaren Teile

┌──────────────────────────────┐        ┌─────────────────────────────────┐
│  Red-DiscordBot (Python)     │        │  Web-App (Node / SvelteKit)     │
│                              │        │                                 │
│  ┌────────────────────────┐  │ JSON-  │  ┌───────────────────────────┐  │
│  │ pdc_webdashboard (Cog)     │  │ RPC    │  │ SvelteKit-Server (BFF)    │  │
│  │  ├─ RPC-Gateway        │◄─┼─2.0────┼─►│  ├─ Discord OAuth2        │  │
│  │  │   (localhost+Token) │  │ +Token │  │  ├─ Session / Cookies     │  │
│  │  ├─ Integrations-Registry││        │  │  └─ RPC-Client            │  │
│  │  └─ Permission-Mapper  │  │        │  └───────────┬───────────────┘  │
│  └────────────────────────┘  │        │              │ /api/* (BFF)     │
│  ┌────────────────────────┐  │        │  ┌───────────▼───────────────┐  │
│  │ Dritt-Cogs             │  │        │  │ Svelte-SPA (Tailwind)     │  │
│  │  (Widgets/Panels/Listen)│ │        │  │  Widgets · Panels · Charts│  │
│  └────────────────────────┘  │        │  └───────────────────────────┘  │
└──────────────────────────────┘        └─────────────────────────────────┘

• pdc_webdashboard-Cog (in PDC_Redbot_Cogs) läuft im Bot-Prozess und stellt das RPC-Gateway sowie eine Integrations-Registry bereit, in der sich andere Cogs mit Widgets, Panels und Listen registrieren. Siehe Cog-Integration.
• PDC Redbot Webapp (dieses Repo) ist die SvelteKit-App. Ihr Server ist der BFF: Er erledigt Discord OAuth2, hält die Session und ist der einzige Client, der das Gateway-Token kennt. Das Svelte-SPA spricht nur mit dem SvelteKit-Server.

Das BFF-Muster

Die wichtigste Regel: Alle Geheimnisse liegen serverseitig. Sie werden zur Laufzeit aus $env/dynamic/private gelesen und nie in Client-Code gebündelt.

• lib/server/ ist die reine Server-Zone: Env (env.ts), Session (session.ts), OAuth2 (auth.ts) und der RPC-Client (rpc.ts). Nichts davon ist aus dem Browser importierbar.
• Der Browser ruft die eigenen /api/*-Endpunkte des BFF (und Seiten-load-Funktionen) auf. Diese rufen wiederum serverseitig das Gateway auf, mit angehängtem Gateway-Token.
• DISCORD_CLIENT_SECRET, GATEWAY_TOKEN und SESSION_SECRET erreichen den Client daher nie – der Browser hält nur ein signiertes Session-Cookie. Siehe Authentifizierung.

JSON-RPC über das Gateway

Der BFF spricht JSON-RPC 2.0 mit dem Cog. Anfragen sind HTTP-POSTs an ${GATEWAY_URL}/rpc mit X-Dashboard-Token-Header. Der Cog definiert zusätzlich einen WebSocket-Endpunkt unter /rpc für bidirektionale/Streaming-Nutzung; die aktuelle Web-App nutzt den HTTP-Transport.

Jeder Call trägt einen Auth-Kontext, den das Gateway serverseitig erneut prüft:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "core.guild_detail",
  "params": {
    "auth": { "user_id": "123", "guild_id": "456", "locale": "de-DE" },
    "args": { /* methodenspezifisch */ }
  }
}

Das Gateway leitet die Red-Berechtigungsstufe des Nutzers aus auth ab und erzwingt die geforderte Stufe bei jedem Call. Siehe API & Gateway zum Methodenkatalog.

Request-Flow

Browser ──▶ BFF (SvelteKit-Server) ──▶ Gateway (Cog, localhost+Token) ──▶ Red-Bot
   │  Seiten-Load / /api/*-Fetch     │  JSON-RPC + X-Dashboard-Token      │  Config / discord.py
   │                                 │                                    │  Permission-Recheck
   ◀── HTML / JSON ──────────────────◀── Ergebnis / Fehler ──────────────◀──

1. Der Browser fordert eine Seite an oder trifft einen /api/*-Endpunkt.
2. hooks.server.ts liest und prüft das signierte Session-Cookie (und prüft die Session-Epoch, ~60 s gecacht).
3. Der BFF baut den Auth-Kontext und ruft das Gateway per JSON-RPC mit dem Token auf.
4. Der Cog erzwingt Berechtigungen, führt die Methode gegen Red aus und liefert ein Ergebnis.
5. Der BFF rendert oder gibt JSON an den Browser zurück.

Projektstruktur

src/
  hooks.server.ts            Session aus Cookie + Epoch-Check bei jeder Anfrage
  lib/server/                NUR serverseitig (Secrets!):
    env.ts                   $env/dynamic/private, fail-closed bei schlechtem SESSION_SECRET
    session.ts               HMAC-SHA256-signierte Cookie-Sessions
    auth.ts                  Discord OAuth2 (Authorize-URL, Code-Tausch, User-Fetch)
    rpc.ts                   JSON-RPC-Client (Token-Header, Auth-Kontext)
  lib/components/            Widget, PanelForm, ListManager, ModuleTabs, CommandPalette
    charts/                  Chart.js-Wrapper (Line/Bar/Donut + SeriesToggle)
    ui/                      shadcn-svelte-Primitives
  lib/i18n/                  de + en (vollständige UI-Übersetzung)
  lib/markdown.ts            Sicherer Markdown→HTML-Renderer (Custom Pages)
  routes/
    +page.svelte             Landing/Übersicht (öffentlich)
    commands/                Öffentliche Befehlsliste
    guilds/[id]/settings/    Server-Übersicht + Bot-Einstellungen pro Gilde
    cogs/                    Cog-Verwaltung (Cogs/Slash/Downloader/Global)
    stats/                   Server-Statistiken (braucht pdc_webdashboard_stats)
    settings/                Globale Settings + Branding + globale Panels
    pages/  p/[slug]/        Custom Pages (Editor + öffentliche Ansicht)
    announce/                Ankündigungs-/Embed-Builder
    audit/  system/          Audit-Log + Health/Self-Update (Owner)
    auth/… logout            OAuth2-Flow
    api/…                    BFF-Endpunkte, die das Gateway aufrufen

Schlüsselkomponenten

Komponente	Rolle
hooks.server.ts	Prüft Session-Cookie und Session-Epoch bei jeder Anfrage; fail-open, wenn das Gateway offline ist.
Widget.svelte	Rendert die schreibgeschützten Widget-Daten eines Cogs (KPI/Liste/Status).
PanelForm.svelte	Rendert das deklarative Panel-Formular eines Cogs und sendet es ab.
ListManager.svelte	Zeilen einer Listen-Contribution ansehen/hinzufügen/bearbeiten/löschen.
ModuleTabs.svelte	Bündelt Widgets/Panels/Listen eines Cogs in ein einziges Tab-Modul.
lib/i18n	Deutsche + englische Message-Stores.
lib/markdown.ts	XSS-sicherer Markdown-Renderer für Custom Pages.

Verwandte Seiten

• Authentifizierung – die Sicherheitsseite des BFF-Musters
• API & Gateway – der JSON-RPC-Methodenkatalog
• Cog-Integration – wie Cogs das Dashboard füttern