Struktur, Doku und S0-Toolchain fuer das abdulive-Toolkit
Monorepo-Geruest fuer neun Streamer-Tools plus den Ingest-Daemon, der unter sechs davon liegt. Enthaelt: - docs/: Ueberblick, Architektur, Twitch-Integration, Datenmodell, Roadmap, Setup, Hebel-Analyse und den MVP-Plan "Clip-Knopf" - docs/projects/: je eine Spezifikation pro Tool - docs/decisions/: vier ADRs (TS-Monorepo, SQLite, EventSub/IRC, Docker) - docker/: Image mit ffmpeg und whisper.cpp, abhaengigkeitsfreier Entrypoint mit check-env, fetch-model und calibrate - config/layout.yaml: aus einem VOD-Screenshot eingemessener Facecam-Ausschnitt (440x330 oben links, Chat-Overlay ab x=1270) Noch kein Anwendungscode - Scheibe S0 aus docs/07-mvp-plan.md. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013VTGjd92LsDDWF3frd9FTB
This commit is contained in:
ZeasyAlexandClaude Opus 5 committed
commit
d09e2b945a
98 files changed
+3273
No files matched your search
@@ -0,0 +1,123 @@
|
||||
# Architektur
|
||||
|
||||
## Bild
|
||||
|
||||
```
|
||||
Twitch OBS
|
||||
┌──────────────────┐ ┌───────────┐
|
||||
│ EventSub (WS) │ │ obs- │
|
||||
│ IRC / Chat │ │ websocket │
|
||||
│ Helix REST │ └─────┬─────┘
|
||||
└────────┬─────────┘ │
|
||||
│ │
|
||||
┌────────▼────────────────────────▼────────┐
|
||||
│ apps/ingest (Daemon) │
|
||||
│ normalisiert alles zu Events │
|
||||
└────────┬─────────────────────┬───────────┘
|
||||
│ │
|
||||
schreibt │ │ publiziert
|
||||
▼ ▼
|
||||
┌─────────────────┐ ┌──────────────────────┐
|
||||
│ SQLite │ │ Event-Bus │
|
||||
│ data/db/ │ │ (in-proc + WS 4790) │
|
||||
└────────┬────────┘ └──────────┬───────────┘
|
||||
│ │
|
||||
┌───────────┬───────┼───────────┬───────────┼───────────┬──────────┐
|
||||
▼ ▼ ▼ ▼ ▼ ▼ ▼
|
||||
dashboard recap raid-scout vod-chapters community overlay- clipper
|
||||
server │
|
||||
│ │
|
||||
overlay-web ffmpeg
|
||||
(Browser- whisper
|
||||
Source) │
|
||||
data/clips
|
||||
│
|
||||
broadcaster
|
||||
```
|
||||
|
||||
## Prozesse
|
||||
|
||||
Der Verbund besteht aus wenigen langlaufenden Prozessen und mehreren
|
||||
Kurzläufern, gestartet über `docker compose up -d`.
|
||||
|
||||
> **Im MVP gilt das noch nicht.** Dort laufen Ingest und Clipper als *ein*
|
||||
> Prozess in *einem* Container; die Aufteilung unten ist der Zielzustand ab
|
||||
> Meilenstein M3, wenn es mehr als einen Konsumenten gibt. Siehe
|
||||
> [`07-mvp-plan.md`](07-mvp-plan.md).
|
||||
|
||||
**Langläufer (laufen immer, auch offline):**
|
||||
|
||||
| Prozess | Port | Aufgabe |
|
||||
|---------|------|---------|
|
||||
| `ingest` | 4790 (WS) | EventSub, IRC, OBS-WS, Viewer-Polling → DB + Bus |
|
||||
| `overlay-server` | 4791 (HTTP+WS) | liefert Overlay-Seiten, nimmt Chat-Commands entgegen |
|
||||
| `dashboard` | 4792 (HTTP) | Analytics-UI |
|
||||
|
||||
**Kurzläufer (event- oder zeitgetriggert):**
|
||||
|
||||
| Prozess | Trigger |
|
||||
|---------|---------|
|
||||
| `clipper` | Clip-Event vom Bus, oder manuell über CLI |
|
||||
| `broadcaster` | `stream.online` |
|
||||
| `recap` | `stream.offline` (+ 5 min Karenz) |
|
||||
| `vod-chapters` | `stream.offline` |
|
||||
| `raid-scout` | manuell / Chat-Command `!raidziel` |
|
||||
|
||||
`community` und `loyalty` sind keine eigenen Prozesse, sondern Module, die im
|
||||
`overlay-server` mitlaufen — sie brauchen dieselbe Chat-Verbindung und
|
||||
denselben WS-Kanal zum Overlay.
|
||||
|
||||
## Event-Bus
|
||||
|
||||
Der Ingest normalisiert alles auf ein einheitliches Event-Format:
|
||||
|
||||
```ts
|
||||
type StreamEvent = {
|
||||
id: string; // ULID
|
||||
ts: string; // ISO-8601, UTC
|
||||
type: EventType; // 'chat.message' | 'stream.online' | ...
|
||||
streamId: string | null;
|
||||
userId: string | null;
|
||||
payload: unknown; // typisiert pro EventType
|
||||
};
|
||||
```
|
||||
|
||||
Transport: In-Prozess ein `EventEmitter`, prozessübergreifend ein
|
||||
WebSocket-Broadcast auf `ws://127.0.0.1:4790`. Kein Kafka, kein Redis. Wenn ein
|
||||
Konsument abstürzt, holt er sich beim Neustart die verpassten Events aus der
|
||||
`events`-Tabelle über `ts > lastSeen`.
|
||||
|
||||
Vollständige Event-Liste: siehe [`03-data-model.md`](03-data-model.md).
|
||||
|
||||
## Pakete
|
||||
|
||||
| Paket | Inhalt |
|
||||
|-------|--------|
|
||||
| `packages/shared` | Typen, Event-Definitionen, Zod-Schemas |
|
||||
| `packages/core` | Config-Laden, Logger, Event-Bus, Scheduler, Retry |
|
||||
| `packages/twitch` | OAuth-Token-Store, Helix-Client, EventSub-WS, IRC-Client |
|
||||
| `packages/db` | SQLite-Verbindung, Migrationen, Repositories |
|
||||
|
||||
Regel: Apps dürfen von Paketen abhängen, Pakete nie von Apps. Apps hängen nicht
|
||||
voneinander ab — Kommunikation läuft über Bus und DB.
|
||||
|
||||
## Technologie
|
||||
|
||||
- **TypeScript / Node 22**, pnpm-Workspaces — siehe
|
||||
[ADR-0001](decisions/ADR-0001-monorepo-typescript.md)
|
||||
- **SQLite** über `better-sqlite3` — siehe [ADR-0002](decisions/ADR-0002-sqlite.md)
|
||||
- **EventSub über WebSocket**, nicht Webhooks — siehe
|
||||
[ADR-0003](decisions/ADR-0003-eventsub-websocket.md)
|
||||
- **ffmpeg** (CLI) für Videoverarbeitung
|
||||
- **whisper.cpp** (CLI) für Untertitel — kein Python, keine GPU
|
||||
- **Vite + Preact** für Dashboard und Overlay-Seiten
|
||||
- **Docker Compose** für den Betrieb — siehe [ADR-0004](decisions/ADR-0004-docker.md)
|
||||
|
||||
## Fehlerverhalten
|
||||
|
||||
- Jeder Netzwerkaufruf hat Retry mit exponentiellem Backoff (`packages/core/retry`).
|
||||
- Der Ingest darf niemals wegen eines Konsumentenfehlers sterben. Konsumenten
|
||||
laufen in eigenen Prozessen; ein Fehler dort schreibt in `logs/` und wird im
|
||||
Dashboard als Warnung angezeigt.
|
||||
- Wenn EventSub die Verbindung verliert: Reconnect mit Session-Resume, danach
|
||||
Lücke über Helix-Polling schließen (`stream.online`-Status, Follower-Liste).
|
||||
Reference in new issue
Block a user