update CI/CD workflows, fix YAML formatting, and enhance documentation with ADR references

.gitea/workflows/cd.yml

@@ -7,7 +7,7 @@ on:
 
 jobs:
   deploy:
-    runs-on: [self-hosted, linux, docker]
+    runs-on: [self-hosted, linux, docker, ubuntu-latest]
     environment: production
     steps:
       - name: Checkout code

.gitea/workflows/ci.yml

@@ -8,7 +8,7 @@ on:
 
 jobs:
   test:
-    runs-on: [self-hosted, linux, docker]
+    runs-on: [self-hosted, linux, docker, ubuntu-latest]
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

.gitea/workflows/dependency-updates.yml

@@ -2,12 +2,12 @@ name: Dependency Updates
 
 on:
   schedule:
-    - cron: '0 2 * * 1'  # Every Monday at 2 AM UTC
+    - cron: "0 2 * * 1" # Every Monday at 2 AM UTC
   workflow_dispatch:
 
 jobs:
   update-dependencies:
-    runs-on: [self-hosted, linux, docker]
+    runs-on: [self-hosted, linux, docker, ubuntu-latest]
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -18,8 +18,8 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: "20"
-          cache: 'npm'
+          cache: "npm"
           cache-dependency-path: frontend/package-lock.json
 
       - name: Update Frontend Dependencies
@@ -31,7 +31,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.22'
+          go-version: "1.22"
           cache: true
 
       - name: Update Go Dependencies
@@ -43,8 +43,8 @@ jobs:
         uses: peter-evans/create-pull-request@v5
         with:
           token: ${{ secrets.GITEA_TOKEN }}
-          commit-message: 'chore: update dependencies'
+          commit-message: "chore: update dependencies"
-          title: 'chore: weekly dependency updates'
+          title: "chore: weekly dependency updates"
           body: |
             Automated weekly dependency updates.
 

.gitea/workflows/release.yml

@@ -13,7 +13,7 @@ on:
 
 jobs:
   release:
-    runs-on: [self-hosted, linux, docker]
+    runs-on: [self-hosted, linux, docker, ubuntu-latest]
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

CONTRIBUTING.md

@@ -11,6 +11,12 @@ Thank you for considering contributing to Linear Void!
 5. **Commit Messages**: Reference the relevant ADR (e.g., "feat(playout): add R2 sync per ADR-001").
 6. **Test with Docker**: Run `docker compose up --build` to test changes.
 
+## Repository
+
+- **Primary**: [git.allucanget.biz/zwitschi/linearvoid](https://git.allucanget.biz/zwitschi/linearvoid)
+- **Container Registry**: `git.allucanget.biz/zwitschi/linearvoid/<service>:latest`
+- **CI/CD**: Gitea Actions with self-hosted runners (see `.gitea/workflows/`)
+
 ## Code Style
 
 - Go: Use standard formatting (`go fmt`).
@@ -19,6 +25,7 @@ Thank you for considering contributing to Linear Void!
 
 ## Pull Requests
 
+- Open PRs on [Gitea](https://git.allucanget.biz/zwitschi/linearvoid).
 - Reference the related ADR in the PR description.
 - Ensure all tests pass and documentation is updated.
 - The CI workflow will validate normalization, linting, and Docker builds.

README.md

@@ -2,13 +2,22 @@
 
 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.).
 
+**Repository**: [git.allucanget.biz/zwitschi/linearvoid](https://git.allucanget.biz/zwitschi/linearvoid)
+
+[![Build Status](https://git.allucanget.biz/zwitschi/linearvoid/actions/workflows/ci.yml/badge.svg)](https://git.allucanget.biz/zwitschi/linearvoid/actions)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Gitea](https://img.shields.io/badge/Gitea-1.27.1-blue)](https://git.allucanget.biz)
+
+## Architecture
+
 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.
+- Gitea self-hosted CI/CD (Actions) and Container Registry.
 
-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.
+See [`docs/architecture/adr/`](docs/architecture/adr/) for the full set of decision records (ADR-001 through ADR-007) covering architecture, storage calculations, cache rules, cost model, module structure, tech stack, admin interfaces, data storage, and caching strategy.
 
 ## Key Features
 
@@ -55,7 +64,13 @@ linearvoid/
 │   └── architecture/
 │       ├── README.md          # arc42 template (fully populated)
 │       └── adr/
-│           └── ADR-001.md     # Consolidated decision record
+│           ├── 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)
@@ -72,17 +87,22 @@ linearvoid/
 - **`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).
+- **`docs/architecture/`**: Complete arc42 documentation + ADRs 001-007 (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.).
+```bash
-2. Prepare normalized videos (`scripts/normalize-video.sh`).
+git clone https://git.allucanget.biz/zwitschi/linearvoid.git
-3. Run locally: `docker compose up` (or individual services).
+cd linearvoid
-4. Deploy: Provision Hetzner VPS, push to R2, configure Cloudflare cache rules (see `infrastructure/cloudflare/` and ADR-001).
+cp .env.example .env
-5. Full setup and operational runbooks are in the [architecture docs](docs/architecture/README.md).
+docker compose up --build
+```
+
+Full setup guide: [`SETUP.md`](SETUP.md).
+
+See the [architecture docs](docs/architecture/README.md) for detailed architecture and ADRs.
 
 ## Development
 
@@ -98,10 +118,26 @@ The architecture is fully documented using the [arc42 template](docs/architectur
 
 - **[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.).
+- **[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.
-
+- **[ADR-004](docs/architecture/adr/ADR-004-admin-video.md)**: Video admin web interface (upload, playlist management, schedule overrides, normalization enforcement).
-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.
+- **[ADR-005](docs/architecture/adr/ADR-005-admin-moderation-analytics.md)**: Web admin interfaces for user management, moderation dashboard, analytics, and system configuration.
+- **[ADR-006](docs/architecture/adr/ADR-006-data-storage.md)**: Data storage strategy (SQLite vs PostgreSQL for v1, migration path, admin interface capabilities).
+- **[ADR-007](docs/architecture/adr/ADR-007-redis-usage.md)**: Redis usage (exact use cases, TTL policies, persistence, fallback behavior, admin configuration).
 
 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.
+
+## Resources
+
+- [CHANGELOG.md](CHANGELOG.md) - Version history and completed features.
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Guidelines for contributing to the project.
+- [SETUP.md](SETUP.md) - Complete setup guide with prerequisites, environment configuration, running the application, and troubleshooting.
+- [Architecture Documentation](docs/architecture/README.md) - Full arc42 template with diagrams and decisions.
+- [ADRs](docs/architecture/adr/) - Detailed decision records (ADR-001 to ADR-007).
+
+**CI/CD**: [View workflows](https://git.allucanget.biz/zwitschi/linearvoid/actions) on Gitea Actions.
+
+**Container Registry**: `git.allucanget.biz/zwitschi/linearvoid/<service>:latest`
+
+The project is ready for use. See [`SETUP.md`](SETUP.md) for detailed installation instructions.

docs/architecture/README.md

@@ -274,17 +274,22 @@ The primary decisions are captured in the following consolidated ADRs (all locat
 
 - **[ADR-001](./adr/ADR-001.md)**: Overall architecture, HLS + Cloudflare R2 caching strategy, storage calculations, cost model, risks.
 - **[ADR-002](./adr/ADR-002-module-structure.md)**: Chosen project folder/module structure (frontend, backend/playout, backend/chat, infrastructure, scripts, monitoring) and rationale.
-- **[ADR-003](./adr/ADR-003-tech-stack.md)**: Technology stack, programming language choices per module (TypeScript frontend, Go for chat/playout wrapper, Bash/Python scripts), Docker-first approach, and explicit documentation of all implicit assumptions (normalization requirement, Cloudflare-centric delivery, monitoring focus, etc.).
+- **[ADR-003](./adr/ADR-003-tech-stack.md)**: Technology stack, programming language choices per module (TypeScript frontend, Go for chat/playout wrapper, Bash/Python scripts), Docker-first approach, and explicit documentation of all implicit assumptions.
+- **[ADR-004](./adr/ADR-004-admin-video.md)**: Video admin web interface (upload, playlist management, schedule overrides, normalization enforcement).
+- **[ADR-005](./adr/ADR-005-admin-moderation-analytics.md)**: Web admin interfaces for user management, moderation dashboard, analytics, and system configuration.
+- **[ADR-006](./adr/ADR-006-data-storage.md)**: Data storage strategy (SQLite vs PostgreSQL for v1, migration path, admin interface capabilities).
+- **[ADR-007](./adr/ADR-007-redis-usage.md)**: Redis usage (exact use cases, TTL policies, persistence, fallback behavior, admin configuration).
 
-These ADRs together form the canonical decision log. Future ADRs (e.g., Docker Compose layout, API contracts, monitoring strategy) will be added to the same folder and referenced here.
+These ADRs together form the canonical decision log.
 
-**Summary of Key Decisions** (from ADR-001/002/003):
+**Summary of Key Decisions** (from ADR-001 through ADR-007):
 
 - Self-managed US-East playout (Hetzner Ashburn) with FFmpeg + MediaMTX/SRS → HLS → Cloudflare R2 + edge caching.
 - Module structure that directly reflects the arc42 building blocks and context diagram.
 - Go preferred for performance-critical services; TypeScript for frontend; Docker for all deployment.
-
+- Admin interfaces for video management, moderation, analytics, and system configuration using HTMX + Tailwind.
-See the individual ADR files for full context, alternatives considered, consequences, and references.
+- SQLite as primary database for v1 with PostgreSQL migration path if needed.
+- Redis for rate limiting, presence, pub/sub, session storage with defined TTL policies and fallback behavior.
 
 ## Quality Requirements