mirror of
https://github.com/yusufipk/YTChatHub.git
synced 2026-09-11 19:06:14 +00:00
22 lines
2.3 KiB
Markdown
22 lines
2.3 KiB
Markdown
# System Patterns
|
|
|
|
## Architecture Overview
|
|
- **Project Layout:** Single pnpm package with three top-level folders: `client/` (Next.js dashboard + overlay), `backend/` (Node ingestion + realtime gateway), and `shared/` (typescript definitions shared between both).
|
|
- **Data Flow:**
|
|
1. Backend worker polls YouTube Live chat through the Innertube (`youtubei.js`) API, maintaining continuation tokens.
|
|
2. Messages are stored in-memory (optionally persisted later) and emitted over an internal event bus.
|
|
3. Client dashboard fetches chat data via REST and pushes selection updates via REST.
|
|
4. Overlay page consumes a Server-Sent Events stream to stay in sync with the selected message.
|
|
- **Realtime Delivery:** SSE for one-directional updates to OBS browser source; leave room to switch to WebSockets if we need bidirectional control later.
|
|
|
|
## Key Patterns & Practices
|
|
- Abstract ingestion behind a module (`backend/src/ingestion/youtubei.ts`) so alternate providers (official API, headless browser) can be swapped in quickly.
|
|
- Cache Innertube visitor data and API keys locally when we extend functionality, keeping startup fast and resilient to key rotations.
|
|
- Use shared TypeScript definitions via the `@shared` path alias to maintain type safety across backend and client.
|
|
- Centralized logging in the backend with structured payloads for easier debugging during long streams.
|
|
- Graceful degradation: backoff strategies for fetch failures and mock-data fallback keep the UI usable even without credentials.
|
|
- **Timezone Context Pattern**: React context provider (`TimezoneContext`) manages browser timezone detection and shares across components for consistent timestamp formatting.
|
|
- **Selection State Management**: Three-tier visual state system (active/selected, normal, previously-selected) with CSS class composition for clear user feedback.
|
|
- **Timestamp Resolution**: Backend uses `timestamp_usec` (microseconds) from YouTube data, converts to milliseconds, and frontend formats in user's local timezone.
|
|
- **Image Proxy Pattern**: Backend `/proxy/image` endpoint caches YouTube CDN images (avatars, badges, emojis) with MD5-hashed keys, 24hr TTL, and 1000-image LRU eviction. Returns stale cache on 429 errors or network failures. Frontend `proxyImageUrl()` helper transparently rewrites YouTube CDN URLs to use proxy.
|