docs: enhance architecture documentation with detailed sections on requirements, quality goals, context, and scaling strategy
This commit is contained in:
zwitschi committed
1 parent
c10d98f3b4
commit
f650a3a94e
1 file changed
+66
-175
+66
-175
@@ -4,17 +4,77 @@
|
|||||||
|
|
||||||
## Table of Contents
|
## Table of Contents
|
||||||
|
|
||||||
- [Introduction and Goals](#introduction-and-goals)
|
- [Architecture Documentation for Linear Void](#architecture-documentation-for-linear-void)
|
||||||
|
- [Table of Contents](#table-of-contents)
|
||||||
- [Companion Documentation](#companion-documentation)
|
- [Companion Documentation](#companion-documentation)
|
||||||
|
- [Introduction and Goals](#introduction-and-goals)
|
||||||
|
- [Requirements Overview](#requirements-overview)
|
||||||
|
- [Quality Goals](#quality-goals)
|
||||||
|
- [Stakeholders](#stakeholders)
|
||||||
- [Architecture Constraints](#architecture-constraints)
|
- [Architecture Constraints](#architecture-constraints)
|
||||||
- [Context and Scope](#context-and-scope)
|
- [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)
|
- [Solution Strategy](#solution-strategy)
|
||||||
- [Building Block View](#building-block-view)
|
- [Building Block View](#building-block-view)
|
||||||
|
- [Whitebox Overall System](#whitebox-overall-system)
|
||||||
|
- [Level 2](#level-2)
|
||||||
|
- [Level 3](#level-3)
|
||||||
- [Runtime View](#runtime-view)
|
- [Runtime View](#runtime-view)
|
||||||
|
- [Playout \& Delivery Scenario](#playout--delivery-scenario)
|
||||||
- [Deployment View](#deployment-view)
|
- [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)
|
- [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)
|
- [Architecture Decisions](#architecture-decisions)
|
||||||
- [Quality Requirements](#quality-requirements)
|
- [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)
|
- [Risks and Technical Debts](#risks-and-technical-debts)
|
||||||
- [Glossary](#glossary)
|
- [Glossary](#glossary)
|
||||||
|
|
||||||
@@ -115,13 +175,6 @@ flowchart TD
|
|||||||
Chat --> VPS
|
Chat --> VPS
|
||||||
VPS -->|Proxy / Static| Pages
|
VPS -->|Proxy / Static| Pages
|
||||||
CDN -->|Origin Pull on Miss| R2
|
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**:
|
**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.
|
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.
|
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 --> DB
|
||||||
DOCKER --> PROM
|
DOCKER --> PROM
|
||||||
DOCKER --> GRAF
|
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:**
|
**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. |
|
| 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.
|
**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
|
|
||||||
|
|
||||||
**_\<Overview Diagram\>_**
|
|
||||||
|
|
||||||
Motivation
|
|
||||||
|
|
||||||
: _\<text explanation\>_
|
|
||||||
|
|
||||||
Contained Building Blocks
|
|
||||||
|
|
||||||
: _\<Description of contained building block (black boxes)\>_
|
|
||||||
|
|
||||||
Important Interfaces
|
|
||||||
|
|
||||||
: _\<Description of important interfaces\>_
|
|
||||||
|
|
||||||
#### \<Name black box 1\>
|
|
||||||
|
|
||||||
_\<Purpose/Responsibility\>_
|
|
||||||
|
|
||||||
_\<Interface(s)\>_
|
|
||||||
|
|
||||||
_\<(Optional) Quality/Performance Characteristics\>_
|
|
||||||
|
|
||||||
_\<(Optional) Directory/File Location\>_
|
|
||||||
|
|
||||||
_\<(Optional) Fulfilled Requirements\>_
|
|
||||||
|
|
||||||
_\<(optional) Open Issues/Problems/Risks\>_
|
|
||||||
|
|
||||||
#### \<Name black box 2\>
|
|
||||||
|
|
||||||
_\<black box template\>_
|
|
||||||
|
|
||||||
#### \<Name black box n\>
|
|
||||||
|
|
||||||
_\<black box template\>_
|
|
||||||
|
|
||||||
#### \<Name interface 1\>
|
|
||||||
|
|
||||||
...
|
|
||||||
|
|
||||||
#### \<Name interface m\>
|
|
||||||
|
|
||||||
### Level 2
|
|
||||||
|
|
||||||
#### White Box _\<building block 1\>_
|
|
||||||
|
|
||||||
_\<white box template\>_
|
|
||||||
|
|
||||||
#### White Box _\<building block 2\>_
|
|
||||||
|
|
||||||
_\<white box template\>_
|
|
||||||
|
|
||||||
...
|
|
||||||
|
|
||||||
#### White Box _\<building block m\>_
|
|
||||||
|
|
||||||
_\<white box template\>_
|
|
||||||
|
|
||||||
### Level 3
|
|
||||||
|
|
||||||
#### White Box \<\_building block x.1\_\>
|
|
||||||
|
|
||||||
_\<white box template\>_
|
|
||||||
|
|
||||||
#### White Box \<\_building block x.2\_\>
|
|
||||||
|
|
||||||
_\<white box template\>_
|
|
||||||
|
|
||||||
#### White Box \<\_building block y.1\_\>
|
|
||||||
|
|
||||||
_\<white box template\>_
|
|
||||||
|
|
||||||
## Runtime View
|
|
||||||
|
|
||||||
### \<Runtime Scenario 1\>
|
|
||||||
|
|
||||||
- _\<insert runtime diagram or textual description of the scenario\>_
|
|
||||||
|
|
||||||
- _\<insert description of the notable aspects of the interactions
|
|
||||||
between the building block instances depicted in this diagram.\>_
|
|
||||||
|
|
||||||
### \<Runtime Scenario 2\>
|
|
||||||
|
|
||||||
### ...
|
|
||||||
|
|
||||||
### \<Runtime Scenario n\>
|
|
||||||
|
|
||||||
## Deployment View
|
|
||||||
|
|
||||||
### Infrastructure Level 1
|
|
||||||
|
|
||||||
**_\<Overview Diagram\>_**
|
|
||||||
|
|
||||||
Motivation
|
|
||||||
|
|
||||||
: _\<explanation in text form\>_
|
|
||||||
|
|
||||||
Quality and/or Performance Features
|
|
||||||
|
|
||||||
: _\<explanation in text form\>_
|
|
||||||
|
|
||||||
Mapping of Building Blocks to Infrastructure
|
|
||||||
|
|
||||||
: _\<description of the mapping\>_
|
|
||||||
|
|
||||||
### Infrastructure Level 2
|
|
||||||
|
|
||||||
#### _\<Infrastructure Element 1\>_
|
|
||||||
|
|
||||||
_\<diagram + explanation\>_
|
|
||||||
|
|
||||||
#### _\<Infrastructure Element 2\>_
|
|
||||||
|
|
||||||
_\<diagram + explanation\>_
|
|
||||||
|
|
||||||
...
|
|
||||||
|
|
||||||
#### _\<Infrastructure Element n\>_
|
|
||||||
|
|
||||||
_\<diagram + explanation\>_
|
|
||||||
|
|
||||||
## Cross-cutting Concepts
|
|
||||||
|
|
||||||
### _\<Concept 1\>_
|
|
||||||
|
|
||||||
_\<explanation\>_
|
|
||||||
|
|
||||||
### _\<Concept 2\>_
|
|
||||||
|
|
||||||
_\<explanation\>_
|
|
||||||
|
|
||||||
...
|
|
||||||
|
|
||||||
### _\<Concept n\>_
|
|
||||||
|
|
||||||
_\<explanation\>_
|
|
||||||
|
|
||||||
## Architecture Decisions
|
|
||||||
|
|
||||||
## Quality Requirements
|
|
||||||
|
|
||||||
### Quality Requirements Overview
|
|
||||||
|
|
||||||
### Quality Scenarios
|
|
||||||
|
|
||||||
## Risks and Technical Debts
|
|
||||||
|
|
||||||
## Glossary
|
|
||||||
|
|
||||||
+----------------------+-----------------------------------------------+
|
|
||||||
| Term | Definition |
|
|
||||||
+======================+===============================================+
|
|
||||||
| _\<Term-1\>_ | _\<definition-1\>_ |
|
|
||||||
+----------------------+-----------------------------------------------+
|
|
||||||
| _\<Term-2\>_ | _\<definition-2\>_ |
|
|
||||||
+----------------------+-----------------------------------------------+
|
|
||||||
Reference in new issue
Block a user