From f650a3a94e4053da85f8767113676fa29df97986 Mon Sep 17 00:00:00 2001 From: zwitschi Date: Wed, 5 Aug 2026 10:20:33 +0200 Subject: [PATCH] docs: enhance architecture documentation with detailed sections on requirements, quality goals, context, and scaling strategy --- docs/architecture/README.md | 265 +++++++++++------------------------- 1 file changed, 78 insertions(+), 187 deletions(-) diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 848456a..063b282 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -4,19 +4,79 @@ ## Table of Contents -- [Introduction and Goals](#introduction-and-goals) -- [Companion Documentation](#companion-documentation) -- [Architecture Constraints](#architecture-constraints) -- [Context and Scope](#context-and-scope) -- [Solution Strategy](#solution-strategy) -- [Building Block View](#building-block-view) -- [Runtime View](#runtime-view) -- [Deployment View](#deployment-view) -- [Cross-cutting Concepts](#cross-cutting-concepts) -- [Architecture Decisions](#architecture-decisions) -- [Quality Requirements](#quality-requirements) -- [Risks and Technical Debts](#risks-and-technical-debts) -- [Glossary](#glossary) +- [Architecture Documentation for Linear Void](#architecture-documentation-for-linear-void) + - [Table of Contents](#table-of-contents) + - [Companion Documentation](#companion-documentation) + - [Introduction and Goals](#introduction-and-goals) + - [Requirements Overview](#requirements-overview) + - [Quality Goals](#quality-goals) + - [Stakeholders](#stakeholders) + - [Architecture Constraints](#architecture-constraints) + - [Context and Scope](#context-and-scope) + - [Business Context](#business-context) + - [High-Level Context Diagram (Mermaid)](#high-level-context-diagram-mermaid) + - [Technical Context](#technical-context) + - [Solution Strategy](#solution-strategy) + - [Building Block View](#building-block-view) + - [Whitebox Overall System](#whitebox-overall-system) + - [Level 2](#level-2) + - [Level 3](#level-3) + - [Runtime View](#runtime-view) + - [Playout \& Delivery Scenario](#playout--delivery-scenario) + - [Deployment View](#deployment-view) + - [CI/CD Pipeline Architecture](#cicd-pipeline-architecture) + - [Infrastructure Level 1](#infrastructure-level-1) + - [Infrastructure Level 2](#infrastructure-level-2) + - [Cross-cutting Concepts](#cross-cutting-concepts) + - [Caching \& Cost Optimization](#caching--cost-optimization) + - [Video Normalization \& Playout](#video-normalization--playout) + - [Required Source Profile (Linear Void v1)](#required-source-profile-linear-void-v1) + - [Reference Normalization Command](#reference-normalization-command) + - [Verification Gate (ffprobe)](#verification-gate-ffprobe) + - [Monitoring \& Resilience](#monitoring--resilience) + - [Prometheus Baseline](#prometheus-baseline) + - [Grafana Dashboards](#grafana-dashboards) + - [Alerting Rules (Prometheus Rule Groups)](#alerting-rules-prometheus-rule-groups) + - [API Documentation Reference](#api-documentation-reference) + - [Chat WebSocket API](#chat-websocket-api) + - [Playout and Delivery REST API](#playout-and-delivery-rest-api) + - [Admin REST API](#admin-rest-api) + - [Cloudflare Configuration Reference](#cloudflare-configuration-reference) + - [DNS and Zone Routing](#dns-and-zone-routing) + - [Cache Rules Baseline](#cache-rules-baseline) + - [Edge Security and Controls](#edge-security-and-controls) + - [Worker and Header Policy](#worker-and-header-policy) + - [Operations and Validation](#operations-and-validation) + - [Security \& Moderation](#security--moderation) + - [Transport and Edge Protection](#transport-and-edge-protection) + - [Reverse Proxy Enforcement (nginx)](#reverse-proxy-enforcement-nginx) + - [Admin Authentication and Session Security](#admin-authentication-and-session-security) + - [Rate Limiting and Abuse Controls](#rate-limiting-and-abuse-controls) + - [CORS and Cross-Origin Behavior](#cors-and-cross-origin-behavior) + - [Moderation and Privacy](#moderation-and-privacy) + - [Chat](#chat) + - [Architecture Decisions](#architecture-decisions) + - [Quality Requirements](#quality-requirements) + - [Performance Benchmarks and Capacity Planning](#performance-benchmarks-and-capacity-planning) + - [Baseline SLO Targets (v1)](#baseline-slo-targets-v1) + - [Workload Assumptions](#workload-assumptions) + - [Initial Capacity Model](#initial-capacity-model) + - [Benchmark Plan](#benchmark-plan) + - [Capacity Triggers and Actions](#capacity-triggers-and-actions) + - [Scaling Strategy](#scaling-strategy) + - [Phase 1: Vertical + Cache-First (Current Baseline)](#phase-1-vertical--cache-first-current-baseline) + - [Phase 2: Service Separation](#phase-2-service-separation) + - [Phase 3: Multi-Origin Resilience](#phase-3-multi-origin-resilience) + - [Phase 4: Regional and Throughput Expansion](#phase-4-regional-and-throughput-expansion) + - [Scaling Triggers](#scaling-triggers) + - [Disaster Recovery and Backup Procedures](#disaster-recovery-and-backup-procedures) + - [Recovery Targets](#recovery-targets) + - [Backup Scope](#backup-scope) + - [Backup Cadence](#backup-cadence) + - [Recovery Runbook (Minimum)](#recovery-runbook-minimum) + - [Failure Modes and Strategy](#failure-modes-and-strategy) + - [Risks and Technical Debts](#risks-and-technical-debts) + - [Glossary](#glossary) ## Companion Documentation @@ -115,13 +175,6 @@ flowchart TD Chat --> VPS VPS -->|Proxy / Static| Pages CDN -->|Origin Pull on Miss| R2 - - classDef cloud fill:#f0f0ff,stroke:#4263eb - classDef vps fill:#f0fff0,stroke:#2e7d32 - classDef user fill:#fff0f0,stroke:#c62828 - class Cloudflare,CDN,Pages,R2 cloud - class VPS,Playout,Chat vps - class Viewers,Admins user ``` **External Interfaces**: @@ -204,7 +257,11 @@ graph TD Detailed black-box descriptions, level-2/3 views, and code locations are in `adr/ADR-001.md` and future implementation ADRs. -### Level 2 & 3 +### 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. + +### 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. @@ -259,13 +316,6 @@ flowchart LR DOCKER --> DB DOCKER --> PROM DOCKER --> GRAF - - classDef ci fill:#e1f5fe,stroke:#0288d1 - classDef reg fill:#fff3e0,stroke:#f57c00 - classDef prod fill:#e8f5e9,stroke:#388e3c - class CI,CD ci - class REGISTRY reg - class DOCKER,PLAYOUT,CHAT,NGINX,REDIS,DB,PROM,GRAF prod ``` **Pipeline Sequence:** @@ -739,162 +789,3 @@ Document and rehearse this runbook quarterly; recovery that is not exercised is | Tiered Cache | Cloudflare feature reducing origin requests by checking upper-tier caches first. | **References**: Cloudflare R2/Cache docs, MediaMTX/SRS/FFmpeg HLS guides, Hetzner pricing, hls.js documentation, standard video bitrate calculators. All original root `ADR-001-*.md` files have been consolidated and can be archived/deleted. - -### Whitebox Overall System - -**_\_** - -Motivation - -: _\_ - -Contained Building Blocks - -: _\_ - -Important Interfaces - -: _\_ - -#### \ - -_\_ - -_\_ - -_\<(Optional) Quality/Performance Characteristics\>_ - -_\<(Optional) Directory/File Location\>_ - -_\<(Optional) Fulfilled Requirements\>_ - -_\<(optional) Open Issues/Problems/Risks\>_ - -#### \ - -_\_ - -#### \ - -_\_ - -#### \ - -...​ - -#### \ - -### Level 2 - -#### White Box _\_ - -_\_ - -#### White Box _\_ - -_\_ - -...​ - -#### White Box _\_ - -_\_ - -### Level 3 - -#### White Box \<\_building block x.1\_\> - -_\_ - -#### White Box \<\_building block x.2\_\> - -_\_ - -#### White Box \<\_building block y.1\_\> - -_\_ - -## Runtime View - -### \ - -- _\_ - -- _\_ - -### \ - -### ...​ - -### \ - -## Deployment View - -### Infrastructure Level 1 - -**_\_** - -Motivation - -: _\_ - -Quality and/or Performance Features - -: _\_ - -Mapping of Building Blocks to Infrastructure - -: _\_ - -### Infrastructure Level 2 - -#### _\_ - -_\_ - -#### _\_ - -_\_ - -...​ - -#### _\_ - -_\_ - -## Cross-cutting Concepts - -### _\_ - -_\_ - -### _\_ - -_\_ - -...​ - -### _\_ - -_\_ - -## Architecture Decisions - -## Quality Requirements - -### Quality Requirements Overview - -### Quality Scenarios - -## Risks and Technical Debts - -## Glossary - -+----------------------+-----------------------------------------------+ -| Term | Definition | -+======================+===============================================+ -| _\_ | _\_ | -+----------------------+-----------------------------------------------+ -| _\_ | _\_ | -+----------------------+-----------------------------------------------+