linearvoid/README.md

# Linear Void

A self-managed **24/7 linear video channel** for a primarily US audience. It runs a continuous playlist of self-owned videos with true/near-true synchronization, a custom lightweight viewer SPA (hls.js player + chat), and full independence from third-party platforms (YouTube, Twitch, etc.).

The architecture (detailed in [`docs/architecture/README.md`](docs/architecture/README.md)) uses:

- Hetzner Ashburn VPS for playout (FFmpeg + MediaMTX/SRS) and chat.
- Cloudflare R2 + CDN with aggressive immutable caching of HLS `.ts` segments ($0 egress).
- Lightweight static frontend and WebSocket chat backend.

See [`docs/architecture/adr/ADR-001.md`](docs/architecture/adr/ADR-001.md) for the consolidated decision record, storage calculations, cache rules, cost model, and implementation plan.

## Key Features

- Continuous synchronized playback from a playlist (standard HLS, 15–35s latency).
- Self-hosted custom SPA with embedded chat (public rooms + private 1:1 DMs, moderation).
- Extreme cost efficiency via Cloudflare R2 edge caching.
- Video normalization, monitoring, fallback slate, and easy playlist management.
- US-centric performance (Ashburn origin + Cloudflare POPs).

## Project Structure

```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
├── .env.example
├── .gitignore
├── docker-compose.yml         # Top-level for dev (playout + chat + nginx)
├── README.md
└── LICENSE
```

### Folder Explanations

- **`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 + ADR-001 (the single source of truth for all architectural decisions).

This structure directly reflects the building blocks, runtime flows, deployment view, and cross-cutting concepts defined in the arc42 documentation.

## Getting Started

1. `cp .env.example .env` and configure secrets (R2 keys, Cloudflare, etc.).
2. Prepare normalized videos (`scripts/normalize-video.sh`).
3. Run locally: `docker compose up` (or individual services).
4. Deploy: Provision Hetzner VPS, push to R2, configure Cloudflare cache rules (see `infrastructure/cloudflare/` and ADR-001).
5. Full setup and operational runbooks are in the [architecture docs](docs/architecture/README.md).

## Development

- Use Docker Compose for local development (playout + chat + frontend).
- Normalize all source videos before adding to playlist (see ADR-001 for exact codec/fps/keyframe requirements).
- Monitor cache hit ratio and R2 operations closely — they determine real cost.

## Architecture Documentation

The architecture is fully documented using the [arc42 template](docs/architecture/README.md) (with populated sections, Mermaid context and building-block diagrams, deployment view, cross-cutting concepts, quality goals, risks, and glossary).

**Decision Records** (in `docs/architecture/adr/`):

- **[ADR-001](docs/architecture/adr/ADR-001.md)**: Overall system architecture, HLS + Cloudflare R2 caching strategy, storage calculations, cost model, risks, and implementation plan.
- **[ADR-002](docs/architecture/adr/ADR-002-module-structure.md)**: Chosen project folder/module structure (frontend, backend/playout, backend/chat, infrastructure, scripts, monitoring) and mapping to arc42 building blocks.
- **[ADR-003](docs/architecture/adr/ADR-003-tech-stack.md)**: Technology stack, language choices per module (TypeScript for frontend, Go preferred for chat and playout wrapper, Bash/Python for scripts), Docker-first approach, and all implicit assumptions (mandatory video normalization, Cloudflare-centric delivery, monitoring focus, etc.).

These three ADRs together provide complete traceability for all major design decisions. Future ADRs will cover Docker Compose layout, API contracts, monitoring strategy, and access control.

See the [architecture README](docs/architecture/README.md) for the big-picture view and the individual ADR files for detailed rationale, alternatives, and consequences.

Contributions, issues, and further evolution (LL-HLS, ABR, multi-channel, E2EE) should reference the architecture documentation.