zwitschi/linearvoid
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity

docs: fix filename typo and add Cloudflare Pages deploy details across docs

Browse Source
This commit is contained in:
zwitschi committed 2026-08-11 11:10:33 +02:00
1 parent 7be66a703c
commit 1019972e25
13 files changed
+393 -403
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+161 -55
View File
@@ -48,67 +48,173 @@ flowchart TD
## Project Structure
This structure directly reflects the building blocks, runtime flows, deployment view, and cross-cutting concepts defined in the arc42 documentation.
```text
linearvoid/
├── frontend/ # Static Single-Page Application (HTML/CSS/JS)
│ ├── src/
│ │ ├── components/ # Video player, chat sidebar, now-playing overlay
│ │ ├── js/ # hls.js integration, WebSocket client, UI logic
│ │ └── styles/ # Tailwind / custom CSS
│ ├── index.html
│ └── package.json # Build tools (Vite recommended)
├── backend/
│ ├── playout/ # Continuous HLS generation from playlist
│ │ ├── src/ # FFmpeg orchestration, playlist manager
│ │ ├── config/
│ │ └── Dockerfile
│ ├── chat/ # Real-time WebSocket service
│ │ ├── src/ # Rooms, DMs, moderation, presence (Node/Go)
│ │ ├── config/
│ │ └── Dockerfile
│ └── shared/ # Common utilities, types, normalization helpers
├── infrastructure/ # Deployment, IaC, Cloudflare configs
│ ├── docker-compose.yml # Local/dev orchestration
│ ├── nginx/ # Proxy, static serving, HLS delivery
│ ├── cloudflare/ # Cache rule examples, Workers
│ └── terraform/ # (optional) provisioning
├── scripts/ # Automation scripts
│ ├── normalize-video.sh # Pre-process MP4s (codec, keyframes, CRF)
│ ├── sync-to-r2.sh # Upload segments/manifests to R2
│ └── backup.sh
├── monitoring/ # Dashboards, alerts, logging
│ ├── grafana/
│ └── prometheus/
├── docs/
│ └── architecture/
│ ├── README.md # arc42 template (fully populated)
│ └── adr/
│ ├── ADR-001.md # Consolidated decision record
│ ├── ADR-002-module-structure.md
│ ├── ADR-003-tech-stack.md
│ ├── ADR-004-admin-video.md
│ ├── ADR-005-admin-moderation-analytics.md
│ ├── ADR-006-data-storage.md
│ └── ADR-007-redis-usage.md
├── .env.example
├── .gitignore
├── docker-compose.yml # Top-level for dev (playout + chat + nginx)
├── README.md
└── LICENSE
├── docs/ # see Documentation section below
├── backend/ # see Backend section below
├── frontend/ # see Frontend section below
├── infrastructure/ # see Infrastructure section below
├── monitoring/ # see Monitoring section below
├── scripts/ # see Scripts section below
├── .editorconfig # EditorConfig for consistent coding styles
├── .env.example # Example environment variables for local development
├── .gitignore # Ignore node_modules, build artifacts, etc.
├── .prettierignore # Ignore files for Prettier formatting
├── CHANGELOG.md # Release notes and version history
├── CONTRIBUTING.md # Contribution guidelines
├── docker-compose.prod.yml # Production deployment (Hetzner + Cloudflare)
├── docker-compose.yml # Top-level for dev (playout + chat + nginx)
└── README.md # This file
```
### Folder Explanations
### Documentation
- **`frontend/`**: The viewer experience — minimal, modern SPA with Tailwind + Alpine.js (or vanilla). Uses `hls.js` for playback and a WebSocket client for chat.
- **`backend/playout/`**: Core linear engine. FFmpeg consumes a normalized playlist and outputs continuous HLS. Includes normalization validation.
- **`backend/chat/`**: Independent WebSocket service (Node.js/Socket.io or Go). Handles public rooms, private DMs, presence (Redis), persistence (PostgreSQL/SQLite), rate limiting, and moderation.
- **`backend/shared/`**: Reusable code (types, utils, video validation).
- **`infrastructure/`**: Everything needed to deploy and configure the stack (Docker, Nginx, Cloudflare rules, future Terraform).
- **`scripts/`**: One-off and CI-friendly scripts for video preparation, R2 sync, backups, and playlist management.
- **`monitoring/`**: Grafana dashboards, Prometheus rules, logging configuration.
- **`docs/architecture/`**: Complete arc42 documentation + ADRs 001-007 (the single source of truth for all architectural decisions).
- `docs/`: Folder containing all documentation for the project, including architecture, ADRs, operational procedures, and setup guides.
- `docs/architecture/`: Architecture documentation, including high-level system architecture, component interactions, and decision records (ADRs).
This structure directly reflects the building blocks, runtime flows, deployment view, and cross-cutting concepts defined in the arc42 documentation.
see [README.md](docs/README.md) for full architecture, ADRs, and operational documentation.
### Backend
- `backend/playout/`: Core linear engine. FFmpeg consumes a normalized playlist and outputs continuous HLS. Includes normalization validation.
- `backend/chat/`: Independent WebSocket service (Node.js/Socket.io or Go). Handles public rooms, private DMs, presence (Redis), persistence (PostgreSQL/SQLite), rate limiting, and moderation.
- `backend/shared/`: Reusable code (types, utils, video validation).
```text
backend/
├── chat/ # WebSocket chat service (Node.js or Go)
│ ├── src/ # Chat service source code (rooms, DMs, moderation)
| | ├── auth/ # Admin authentication and session management
| | | ├── auth_test.go # Unit tests for authentication
| | | └── auth.go # Authentication logic (login, session validation)
| | ├── config/ # Configuration files for chat service
| | | ├── config_test.go # Unit tests for configuration
| | | └── config.go # Configuration loading and validation
| | ├── db/ # Database access and models
| | | ├── db_test.go # Unit tests for database access
| | | ├── db.go # Database connection and query logic
| | | ├── models.go # Database models (users, messages, rooms)
| | | └── redis.go # Redis connection and presence management
| | ├── handlers/ # WebSocket message handlers
| | | ├── handlers_test.go # Unit tests for WebSocket message handlers
| | | └── handlers.go # WebSocket message handling logic
| | ├── media/ # Media-related utilities (e.g., video validation)
| | | ├── media_test.go # Unit tests for media-related utilities
| | | └── media.go # Media-related utility functions
| | ├── metrics/ # Prometheus metrics endpoints
| | | ├── metrics_test.go # Unit tests for Prometheus metrics
| | | └── metrics.go # Prometheus metrics collection and exposition
| | ├── ratelimit/ # Rate limiting logic (Redis-based)
| | | ├── ratelimit_test.go # Unit tests for rate limiting
| | | └── ratelimit.go # Rate limiting logic using Redis
| | ├── ws/ # WebSocket handlers
| | | ├── ws_test.go # Unit tests for WebSocket handlers
| | | └── ws.go # WebSocket connection and message handling
| | └── main.go # Entry point for chat service
| ├── Dockerfile # Dockerfile for chat service
| ├── go.mod # Go module file for chat service
| └── go.sum # Go checksum file for chat service
└── playout/ # Continuous HLS generation from playlist (Go)
├── demodata/ # Sample media and playlist files for testing
| ├── media/ # Sample media files for testing
| └── playlist/ # Sample playlist files for testing
├── src/ # Playout service source code (FFmpeg orchestration)
| ├── go.mod # Go module file for playout service
| ├── go.sum # Go checksum file for playout service
| ├── playlist_test.go # Unit tests for playlist management
| └── playlist.go # Playlist management logic
└── testdata/ # Test data for playout service (sample playlists, media)
| ├── comments_only.txt # Sample playlist with comments only
| ├── empty_playlist.txt # Sample empty playlist
| ├── invalid_24fps.mp4 # Sample invalid 24fps video for testing
| ├── invalid_h265.mp4 # Sample invalid H.265 video for testing
| ├── mixed_valid_invalid.txt # Sample playlist with mixed valid and invalid entries
| ├── valid_720p30.mp4 # Sample valid 720p30 video for testing
| └── valid_playlist.txt # Sample valid playlist for testing
├── Dockerfile # Dockerfile for the playout service
└── start-playout.sh # Script to start the playout service
```
### Frontend
The viewer experience — minimal, modern SPA with custom CSS + vanilla JS. Uses `hls.js` for playback and a WebSocket client for chat.
```text
frontend/
├── admin/ # Admin SPA (playlist management, moderation, analytics)
│ ├── login/ # Login page for admin authentication
| | └── index.html # Admin login page
| └── index.html # Admin SPA
├── public/ # Static assets (favicon, images, etc.)
│ ├── admin/ # Admin static assets
| | ├── analytics.html # Analytics dashboard page
| | ├── chat-log.html # Chat log viewer page
| | ├── dashboard.html # Admin dashboard page
| | ├── moderation.html # User moderation page
| | ├── playlist.html # Playlist management page
| | ├── schedule.html # Schedule overrides page
| | ├── system.html # System configuration page
| | ├── upload.html # Video upload page
| | └── users.html # User management page
│ ├── favicon.ico # Favicon for the SPA
| └── icons.svg # SVG icons for the SPA
├── src/ # Source code for the SPA
│ ├── assets/ # Images, fonts, and other static assets
| | ├── hero.png # Hero image for the SPA
| | ├── typescript.svg # TypeScript logo for the SPA
| | └── vite.svg # Vite logo for the SPA
│ ├── admin.test.ts # Admin frontend tests (Vitest)
│ ├── admin.ts # Admin SPA logic (playlist, moderation, analytics)
│ ├── counter.ts # Counter component for testing
│ ├── main.test.ts # Main frontend tests (Vitest)
│ ├── main.ts # Main SPA logic (hls.js player, WebSocket chat)
│ └── style.css # Custom CSS for the SPA
├── .gitignore # Ignore node_modules, build artifacts, etc.
├── index.html # Main SPA entry point
├── package-lock.json # Lockfile for npm dependencies
├── package.json # Build tools (Vite recommended)
├── tsconfig.json # TypeScript configuration
├── vite.config.ts # Vite configuration
└── vitest.config.ts # Vitest configuration
```
### Infrastructure
Everything needed to deploy and configure the stack (Docker, Nginx, Cloudflare rules, future Terraform).
- Cloudflare
- [worker.js](infrastructure/cloudflare/worker.js) — adds immutable cache headers to HLS segments
- Nginx
- [Dockerfile](infrastructure/nginx/Dockerfile) — builds Nginx with custom config
- [nginx.conf](infrastructure/nginx/nginx.conf) — reverse proxy, static SPA, HLS delivery
### Monitoring
Grafana dashboards, Prometheus rules, logging configuration.
- Grafana
- dashboards
- [dashboard.json](monitoring//grafana/dashboards/dashboard.json) — operational dashboards for playout, chat, and Redis
- [dashboard.yml](monitoring//grafana/dashboards/dashboard.yml) — operational dashboards for playout, chat, and Redis
- datasources
- [datasource.yml](monitoring/grafana/datasources/datasource.yml) — Prometheus datasource configuration
- [dashboard.json](monitoring/grafana/dashboard.json) — operational dashboards for playout, chat, and Redis
- Prometheus
- [alerts.yml](monitoring/prometheus/alerts.yml) — alerting rules for playout, chat, Redis, and system health
- [prometheus.yml](monitoring/prometheus/prometheus.yml) — scrape targets for playout, chat, Redis, and system metrics
### Scripts
One-off and CI-friendly scripts for video preparation, R2 sync, backups, and playlist management.
- loadtest/
- [admin-api.js](scripts/loadtest/admin-api.js) — admin API load test script
- [run-loadtests.ps1](scripts/loadtest/run-loadtests.ps1) — PowerShell script to run load tests
- [summarize-artillery.ps1](scripts/loadtest/summarize-artillery.ps1) — PowerShell script to summarize Artillery load test results
- [summarize-k6.ps1](scripts/loadtest/summarize-k6.ps1) — PowerShell script to summarize k6 load test results
- [ws-chat.yml](scripts/loadtest/ws-chat.yml) — WebSocket chat load test configuration
## Getting Started