docs: complete API error codes, deploy troubleshooting, monitoring/security rewrite, L2+L3 building blocks
This commit is contained in:
zwitschi committed
1 parent
0f81a81029
commit
db3bf96847
5 files changed
+267
-205
No files matched your search
+105
-2
@@ -259,11 +259,114 @@ Detailed black-box descriptions, level-2/3 views, and code locations are in `adr
|
||||
|
||||
### Level 2
|
||||
|
||||
Deferred to implementation (see ADR for component responsibilities, interfaces, quality attributes, and risks). Playout enforces normalization; Delivery layer focuses on cache rules and immutable naming.
|
||||
Detailed component diagram with code locations and persistence.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Cloudflare Edge"
|
||||
CF[CDN + WAF<br/>Cache Rules]
|
||||
R2[R2 Bucket<br/>media + HLS]
|
||||
PAGES[Pages<br/>SPA hosting]
|
||||
end
|
||||
|
||||
subgraph "Docker Host (Hetzner CX22)"
|
||||
NGINX[nginx<br/>:80/:443<br/>proxy + auth]
|
||||
CHAT[chat service<br/>:3000<br/>Go + gorilla/websocket]
|
||||
PLAYOUT[playout service<br/>:8081<br/>Go + FFmpeg]
|
||||
REDIS[Redis 7<br/>:6379<br/>presence/rate/pubsub]
|
||||
DB[PostgreSQL 15<br/>:5432<br/>chat history/moderation]
|
||||
end
|
||||
|
||||
subgraph "External"
|
||||
VIEWER[Viewer Browser<br/>hls.js + WebSocket]
|
||||
ADMIN[Admin Browser<br/>SPA + uploads]
|
||||
end
|
||||
|
||||
VIEWER -->|HTTPS| CF
|
||||
VIEWER -->|WSS| NGINX
|
||||
ADMIN -->|HTTPS| CF
|
||||
CF --> NGINX
|
||||
NGINX --> CHAT
|
||||
NGINX --> PLAYOUT
|
||||
NGINX -->|/hls/*| R2
|
||||
CHAT --> REDIS
|
||||
CHAT --> DB
|
||||
PLAYOUT --> R2
|
||||
PLAYOUT -->|reads| R2
|
||||
```
|
||||
|
||||
#### Playout Service (`backend/playout/src/playlist.go`)
|
||||
|
||||
- **Role**: Continuous HLS encoding loop using FFmpeg concat demuxer
|
||||
- **Input**: `data/playlist/playlist.txt` — ordered list of MP4 file paths
|
||||
- **Output**: HLS segments (`.ts`) + live manifest (`.m3u8`) written to `data/hls/`, mirrored to R2
|
||||
- **Resilience**: Restart counter (>5/60s → activate slate), Prometheus metrics on port 8081
|
||||
- **Validation**: ffprobe gate on all ingested files (codec, fps, resolution, keyframe interval)
|
||||
|
||||
#### Chat Service (`backend/chat/src/main.go`)
|
||||
|
||||
- **Role**: WebSocket chat with rooms, DMs, moderation, admin API
|
||||
- **Persistence**: PostgreSQL 15 via GORM (messages, moderation logs, media metadata). SQLite for dev fallback
|
||||
- **Redis**: Presence tracking, rate limiting, pub/sub for multi-instance fan-out
|
||||
- **Auth**: Session-cookie admin auth with Redis-backed expiry
|
||||
- **Metrics**: Connected clients, stored messages, DMs, moderation actions on `/metrics`
|
||||
|
||||
#### Frontend SPA (`frontend/`)
|
||||
|
||||
- **Viewer**: `src/main.ts` — hls.js player, WebSocket chat, presence indicators, schedule overlay
|
||||
- **Admin**: `src/admin.ts` — 9 dynamic tabs (dashboard, upload, playlist, schedule, moderation, chat-log, users, analytics, system)
|
||||
- **Build**: Vite → static output in `frontend/dist/`
|
||||
|
||||
#### Reverse Proxy (`infrastructure/nginx/nginx.conf`)
|
||||
|
||||
- auth_request gate on `/admin` and `/api/admin`
|
||||
- WebSocket upgrade for `/ws`
|
||||
- HLS CORS headers + OPTIONS preflight
|
||||
- `/health` JSON endpoint, `/nginx-status` stub_status
|
||||
|
||||
### Level 3
|
||||
|
||||
Deferred to implementation (see ADR for component responsibilities, interfaces, quality attributes, and risks). Playout enforces normalization; Delivery layer focuses on cache rules and immutable naming.
|
||||
Module-level breakdown per service.
|
||||
|
||||
#### Chat Service Modules
|
||||
|
||||
| Module | File/Lines | Responsibility |
|
||||
| ---------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| **Connection Manager** | `main.go` (hub, clients map) | Track active WebSocket connections per room, fan-out messages |
|
||||
| **Message Parser** | `main.go` (readPump, handleMessage) | Parse JSON envelope `{type, room?, ...}`, validate fields, route to handler |
|
||||
| **Room Registry** | `main.go` (rooms map, room broadcasts) | Map room name → client set, handle join/leave/close |
|
||||
| **DM Router** | `main.go` (handleDirectMessage) | Resolve target user in clients map, deliver private message |
|
||||
| **Persistence Layer** | `main.go` (GORM models: Message, DirectMessage, ModerationLog) | Store/retrieve chat messages, DMs, moderation events |
|
||||
| **Redis Subsystem** | `main.go` (redisClient, rate limiting, pub/sub, presence) | INCR+EXPIRE rate limit, SETEX presence, PSUBSCRIBE room fan-out |
|
||||
| **Auth Handler** | `main.go` (handleAdminLogin, adminAuthMiddleware) | Session cookie creation/validation, login rate limiting |
|
||||
| **Admin API Router** | `main.go` (handleAdmin\*) | Upload, playlist CRUD, schedule overrides, moderation actions, analytics, system summary |
|
||||
| **Metrics Exporter** | `main.go` (prometheus.MustRegister) | Expose connected_clients, messages_total, dms_total, moderation_actions, redis_up |
|
||||
|
||||
#### Playout Service Modules
|
||||
|
||||
| Module | File/Lines | Responsibility |
|
||||
| -------------------- | ---------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| **Playlist Parser** | `playlist.go` (parsePlaylist) | Read `playlist.txt`, skip comments/blank lines, resolve file paths |
|
||||
| **FFmpeg Manager** | `playlist.go` (runPlayout, restart logic) | Spawn/monitor FFmpeg concat process, restart on crash |
|
||||
| **Slate Controller** | `playlist.go` (activateSlate, deactivateSlate) | Switch output to slate loop on excessive failures |
|
||||
| **R2 Sync** | `playlist.go` (syncToR2) | Upload HLS segments + manifest to R2 bucket |
|
||||
| **Health Endpoint** | `playlist.go` (healthHandler) | `/health` → JSON with mode, segment count, uptime |
|
||||
| **Metrics Exporter** | `playlist.go` (prometheus) | Expose restarts_total, mode (live/slate) |
|
||||
|
||||
#### Frontend Modules
|
||||
|
||||
| Module | File | Responsibility |
|
||||
| ----------------------- | ----------------------------------------------- | ----------------------------------------------------------------- |
|
||||
| **HLS Player** | `src/main.ts` | hls.js initialization, attach to video element, error recovery |
|
||||
| **WebSocket Client** | `src/main.ts` | Connect/disconnect, parse envelope, dispatch to UI handlers |
|
||||
| **Chat UI** | `src/main.ts` | Message list rendering, room tabs, DM panel, presence dots |
|
||||
| **Schedule Overlay** | `src/main.ts` | Poll `/api/schedule`, render current/next program |
|
||||
| **Admin Router** | `src/admin.ts` | Tab-based navigation, dynamic page loading |
|
||||
| **Upload Manager** | `src/admin.ts` | Multipart upload with chunk progress, ffprobe validation feedback |
|
||||
| **Playlist Editor** | `src/admin.ts` | Drag-reorder, add/remove items, save to `/api/admin/playlist` |
|
||||
| **Moderation Panel** | `src/admin.ts` + `public/admin/moderation.html` | Inline mute/ban, action log viewer |
|
||||
| **Analytics Dashboard** | `src/admin.ts` + `public/admin/analytics.html` | Message counts, top rooms, moderation stats |
|
||||
| **System Config** | `src/admin.ts` + `public/admin/system.html` | Service health, config metadata, restart buttons |
|
||||
|
||||
## Runtime View
|
||||
|
||||
|
||||
Reference in new issue
Block a user