> For the complete documentation index, see [llms.txt](https://crossban.thelukez.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://crossban.thelukez.com/de/dokumentation/under-the-hood.md).

# Unter der Haube

Dieses Dokument bietet eine detaillierte, technische Aufschlüsselung darüber, wie der CrossBan Discord-Bot funktioniert, mit Fokus auf seine Code-Struktur, Ausführungsabläufe und zentrale Komponenten. Es richtet sich an Entwickler oder Personen mit Programmierkenntnissen. Der Bot ist in TypeScript unter Verwendung von Discord.js und PostgreSQL geschrieben.

## Übersicht

CrossBan synchronisiert Banns über mehrere Discord-Server hinweg. Er hört auf Bann-/Entbann-Ereignisse über Discords Audit-Logs, speichert Daten in einer PostgreSQL-Datenbank und propagiert Aktionen an verbundene Gilden basierend auf Konfigurationen. Er verwendet Docker für das Deployment und handhabt Logging über Webhooks und Nachrichten in Kanälen.

Wesentliche Technologien:

* **Discord.js**: Für die Interaktion mit der Discord-API.
* **PostgreSQL**: Für persistente Speicherung.
* **Node.js/TypeScript**: Laufzeit und Sprache.
* **Docker**: Containerisierung.

Der Kern des Bots ist ereignisgesteuert, mit Modulen, die beim Start dynamisch geladen werden.

## Architektur

Der Bot ist modular:

* **Haupteinstieg (index.ts)**: Initialisiert den Client, lädt Befehle/Komponenten/Ereignisse und startet den Bot.
* **Module**:
  * **Befehle**: Slash-Befehle (z. B. config).
  * **Komponenten**: Interaktive Elemente (z. B. Buttons für Entbann-Überprüfungen).
  * **Ereignisse**: Handler für Discord-Ereignisse (z. B. Audit-Log-Einträge).
* **Hilfsfunktionen**: Logger, Bann-Sync-Manager, Entbann-Logger.
* **Datenbank**: Manager für Abfragen und Schema-Initialisierung.
* **Konfiguration**: Umgebungsbasierte Einstellungen.

Dateien werden dynamisch geladen mithilfe von `require()` basierend auf Dateiendungen (`.ts` in der Entwicklung, `.js` in der Produktion).

## Startprozess

Der Bot startet in `index.ts` via einer async IIFE (Immediately Invoked Function Expression).

### Client-Initialisierung

```typescript
const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMembers, ...],
  // ... andere Optionen
});
```

* Erstellt einen Discord-Client mit Intents für Gilden, Mitglieder, Nachrichten und Moderation.
* Begrenzt den Cache für Performance (z. B. 128 Nachrichten pro Manager).

### Modul-Laden

Funktionen wie `loadCommands()`, `loadComponents()`, und `loadEvents()` scannen Verzeichnisse und laden Dateien:

* **`loadCommands()`**: Liest `commands/` Ordner, filtert nach Endung, require()t jede Datei und prüft auf `data` und `run` Eigenschaften. Speichert in einer Collection.
* **`loadComponents()`**: Ähnlich für `components/`, prüft auf `prefix` und `run`.
* **`loadEvents()`**: Durchsucht `events/` Unterordner (passend zum Discord Events-Enum), lädt Handler.

Beispiel für Befehle:

```typescript
for (const file of commandFiles) {
  try {
    const command = require(file);
    if (typeof command == "object" && "data" in command && "run" in command) {
      // Zur Collection hinzufügen
    }
  } catch (error) {
    console.error(`Error loading command file ${file}`, { error });
  }
}
```

#### Einrichtungs des Interaction-Handlers

```typescript
function setupInteractionHandlers() {
  client.on("interactionCreate", new InteractionHandler(client, commands, components).handler());
}
```

* Hängt einen Handler für Interaktionen an (Befehle, Buttons, Selects).

#### Client Ready Event

```typescript
client.once("clientReady", async (_client) => {
  // Befehle bereitstellen, Aktivität setzen, etc
});
```

* Stellt Slash-Befehle bereit mithilfe von `deployCommands()`.
* Initialisiert den Entbann-Logger und den Bann-Sync-Manager.
* Setzt die Bot-Aktivität, um die Anzahl der Server anzuzeigen.
* Lädt Wahrheitsquellen aus der DB in die Konfiguration.

#### Datenbank-Initialisierung

* Ruft auf `dbManager.initialize()` um SQL-Schemata aus `schemas/` Ordner auszuführen.
* Bereinigt veraltete Gilden/Wahrheitsquellen.
* Lädt Wahrheitsquellen in den Arbeitsspeicher.

#### Einloggen und Funktionen aktivieren

* `client.login(config.botToken)` verbindet mit Discord.
* Aktiviert den Bann-Sync-Manager.
* Im Dev-Modus aktiviert es Logging.

### Ereignisbehandlung

Ereignisse werden über `guildAuditLogEntryCreate` in `banEventHandler.ts`.

#### Bann/Entbann-Erkennung

```typescript
function shouldIgnore(entry: GuildAuditLogsEntry, guildId: string) {
  if (entry.action !== AuditLogEvent.MemberBanAdd && entry.action !== AuditLogEvent.MemberBanRemove) return true;
  if (!config.guildIds.includes(guildId)) return true;
  if (!entry.executorId || entry.executorId === config.clientId || !config.isTruthSourceFor(guildId, entry.executorId))
    return true; // Nur von Wahrheitsquellen verarbeiten
  return false;
}
```

* Ignoriert Nicht-Bann-Ereignisse, nicht konfigurierte Gilden, Bot-Aktionen oder Executor(en), die keine Wahrheitsquellen sind.

#### Verarbeitung von Banns

Für `MemberBanAdd`:

* Ruft auf `banSyncManager.handleBan()` mit Benutzer-ID, Quell-Gilde, Executor und Grund.
* Erstellt ein `BanEvent` in der DB.
* Synchronisiert zu Gilden mit aktiviertem Auto-Bann.

Für `MemberBanRemove`:

* Ruft auf `banSyncManager.removeBan()` um in Gilden zu entbannen.

## Bann-Synchronisation

Behandelt von banSyncManager.ts.

#### Behandlung von Banns

```typescript
async handleBan(data: BanEventInsert): Promise<void> {
  const banEvent = await dbManager.addBanEvent(data);
  await dbManager.createGuildBan({ /* Quell-Bann */ });
  await this.syncBanToGuilds(banEvent, data.sourceGuild);
}
```

* Fügt das Bann-Ereignis in `ban_events` Tabelle ein.
* Erstellt einen Gilden-Bann-Datensatz für die Quelle.
* Synchronisiert zu Zielgilden.

#### Synchronisation zu Gilden

```typescript
private async syncBanToGuilds(event: BanEvent, sourceGuildId: string): Promise<void> {
  const autoBanGuilds = await dbManager.getGuildConfigsForAutoban();
  const targetGuilds = autoBanGuilds.filter((config) => config.guildId !== sourceGuildId);
  for (const guildConfig of targetGuilds) {
    const guild = this.client?.guilds.cache.get(guildConfig.guildId);
    if (guild) {
      await guild.bans.create(event.userId, { reason: `Synced ban...` });
      await dbManager.createGuildBan({ /* Ziel-Bann */ });
    }
  }
}
```

* Holt Gilden mit aktiviertem Auto-Bann.
* Bannt den Benutzer in jeder Zielgilde über die Discord-API.
* Erfasst Einträge in der DB.

#### Behandlung von Entbannungen

```typescript
async removeBan(data: { userId: string; sourceGuild: Guild; executorId: string }): Promise<void> {
  await dbManager.removeGuildBan(data.userId, data.sourceGuild.id);
  await this.syncUnbanToGuilds(ban, data.sourceGuild, data.executorId);
}
```

* Kennzeichnet den Bann in der DB als inaktiv.
* Synchronisiert Entbann: Automatisches Entbannen oder sendet ein Review-Log.

Für den Review-Modus:

* Verwendet `unbanLogger` um eine Nachricht mit einem Auswahlmenü für Entbann/Ignore zu senden.

## Datenbank-Interaktionen

Gemanagt von `manager.ts` unter Verwendung von `pg` (PostgreSQL-Client).

#### Initialisierung

* Liest `.sql` Dateien aus `schemas/` und führt sie aus, um Tabellen zu erstellen (z. B. `guilds`, `ban_events`, `guild_bans`, `truth_sources`).

#### Wesentliche Operationen

* **Gilden-Konfigurationen**: CRUD für Einstellungen (aktiviert, Auto-Bann, Entbann-Modus, Logging-Kanal).
* **Bann-Ereignisse**: Einfügen und Abfragen globaler Banns.
* **Gilden-Banns**: Verfolgt Bann-Status pro Gilde.
* **Wahrheitsquellen**: Verwalten vertrauenswürdiger Benutzer pro Gilde.

Beispielabfrage:

```typescript
async getBan(userId: string): Promise<BanEvent | null> {
  const result = await this.query("SELECT * FROM ban_events WHERE user_id = $1 ORDER BY created_at DESC LIMIT 1", [userId]);
  // ...
}
```

## Logging und Entbann-Verarbeitung

### Allgemeines Logging

`logger.ts` verwendet eine Warteschlange für sequentielle Webhook-Sends:

```typescript
async function sendLogInternal(data: any): Promise<void> {
  if (!wh) return;
  // Formatiert Daten als JSON oder String, sendet an den Webhook.
}
```

* Reihenfolge der Logs, um Rate-Limits zu vermeiden.
* Aktiviert wenn `LOGGING_WEBHOOK` in `.env`.

### Entban-Logging

`gesetzt ist` unbanLogger.ts

```typescript
baut Nachrichten unter Verwendung von Discords Component-Buildern:
  public buildLogMessage<T extends UnbanMessageType>(type: T, details: UnbanDetails<T>): RESTPostAPIChannelMessageJSONBody {
  const builder = new UnbanMessageBuilder<T>();
    return {
    flags: ComponentsV2Flags,
    // ...
  };
}
```

* components: builder.build(details, type),
* Erstellt Container mit Text, Trennern, Thumbnails für Entbann-Details.
* Für den Review-Typ fügt es ein Auswahlmenü für Aktionen hinzu.

## Sendet rohen Payload via REST-API an den Logging-Kanal.

`Konfigurationsverwaltung` config.ts `.env` lädt aus

* Dateien: `Parst` GUILDS
* als Array.
* Verwaltet Wahrheitsquellen im Speicher (Map von Sets).

Bietet Methoden zum Hinzufügen/Entfernen von Quellen und zum Prüfen, ob ein Benutzer eine Wahrheitsquelle ist.

```typescript
Beispiel:
  addTruthSource(guildId: string, source: string) {
  const _sources = this._truthSources.get(guildId) || new Set<string>();
  _sources.add(source);
}
```

## this.\_truthSources.set(guildId, \_sources);

* Fehlerbehandlung und Randfälle
* Unbehandelte Rejections/Exceptions werden geloggt.
* Datenbankabfragen verwenden parametrisierte Statements, um SQL-Injection zu verhindern.
* Der Client prüft die Verfügbarkeit bevor Aktionen ausgeführt werden.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://crossban.thelukez.com/de/dokumentation/under-the-hood.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
