From 926a663c23d8f6611f239f1f404a0cd762111de4 Mon Sep 17 00:00:00 2001 From: zwitschi Date: Sat, 8 Aug 2026 14:52:19 +0200 Subject: [PATCH] Add comprehensive documentation for Linear Void project - Created README.md in docs folder outlining project structure and documentation links. - Added SECURITY.md detailing the security model, threat model, authentication, transport security, network isolation, and incident response procedures. - Introduced SETUP.md providing a detailed setup guide for local and production environments, including prerequisites, environment setup, and Gitea integration. - Added STREAMING.md outlining the streaming pipeline, including production flow, source-media contract, playout and HLS packaging, cache contract, player behavior, and monitoring. - Updated architecture documentation to include links to new SETUP.md and STREAMING.md files for better navigation. --- README.md | 12 ++++---- API.md => docs/API.md | 0 DEPLOYMENT.md => docs/DEPLOYMENT.md | 2 +- DEVELOPMENT.md => docs/DEVELOPMENT.md | 2 -- MONITORING.md => docs/MONITORING.md | 0 docs/README.md | 41 +++++++++++++++++++++++++++ SECURITY.md => docs/SECURITY.md | 0 SETUP.md => docs/SETUP.md | 0 STREAMING.md => docs/STREAMING.md | 0 docs/architecture/README.md | 10 ++++--- 10 files changed, 54 insertions(+), 13 deletions(-) rename API.md => docs/API.md (100%) rename DEPLOYMENT.md => docs/DEPLOYMENT.md (99%) rename DEVELOPMENT.md => docs/DEVELOPMENT.md (98%) rename MONITORING.md => docs/MONITORING.md (100%) create mode 100644 docs/README.md rename SECURITY.md => docs/SECURITY.md (100%) rename SETUP.md => docs/SETUP.md (100%) rename STREAMING.md => docs/STREAMING.md (100%) diff --git a/README.md b/README.md index 3381527..edab013 100644 --- a/README.md +++ b/README.md @@ -206,11 +206,11 @@ Contributions, issues, and further evolution (LL-HLS, ABR, multi-channel, E2EE) - [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. -- [API.md](API.md) - Implemented WebSocket and REST API reference. -- [DEPLOYMENT.md](DEPLOYMENT.md) - Production deployment and operations guide. -- [MONITORING.md](MONITORING.md) - Prometheus and Grafana setup and troubleshooting. -- [SECURITY.md](SECURITY.md) - Security controls, hardening checklist, and incident baseline. +- [SETUP.md](docs/SETUP.md) - Complete setup guide with prerequisites, environment configuration, running the application, and troubleshooting. +- [API.md](docs/API.md) - Implemented WebSocket and REST API reference. +- [DEPLOYMENT.md](docs/DEPLOYMENT.md) - Production deployment and operations guide. +- [MONITORING.md](docs/MONITORING.md) - Prometheus and Grafana setup and troubleshooting. +- [SECURITY.md](docs/SECURITY.md) - Security controls, hardening checklist, and incident baseline. - [Scaling Playbook](docs/operations/scaling-performance-playbook.md) - Performance test method, thresholds, and scaling decision flow. - [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). @@ -232,4 +232,4 @@ Since this is a linear project, we also rely on a linear development and release [MIT License](LICENSE) -The project is ready for use. See [`SETUP.md`](SETUP.md) for detailed installation instructions. +The project is ready for use. See [`SETUP.md`](docs/SETUP.md) for detailed installation instructions. diff --git a/API.md b/docs/API.md similarity index 100% rename from API.md rename to docs/API.md diff --git a/DEPLOYMENT.md b/docs/DEPLOYMENT.md similarity index 99% rename from DEPLOYMENT.md rename to docs/DEPLOYMENT.md index db6d532..e6c83f1 100644 --- a/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -135,7 +135,7 @@ See .env.example and SETUP.md for full variable reference. ## Pull-and-Run Deployment -Images are built and pushed automatically by the CI and release workflows (see [CONTRIBUTING.md](CONTRIBUTING.md#versioning-and-releases) for the release procedure). +Images are built and pushed automatically by the CI and release workflows (see [CONTRIBUTING.md](../CONTRIBUTING.md#versioning-and-releases) for the release procedure). Every push to `main` triggers CI (builds `:main` and `:latest` tags) and CD (deploys `:latest` to test lab) in parallel. Semantic version tags (`*.*.*`, e.g. `1.0.9`) trigger the release workflow which builds `:X.Y.Z`, `:X.Y`, and `:latest` tags and creates a Gitea Release. diff --git a/DEVELOPMENT.md b/docs/DEVELOPMENT.md similarity index 98% rename from DEVELOPMENT.md rename to docs/DEVELOPMENT.md index b2c5ec6..39e65e7 100644 --- a/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -1,7 +1,5 @@ # DEVELOPMENT.md — Linear Void Remaining Tasks -> Auto-generated 2026-08-07. All completed items moved to `.github/instructions/DONE.md`. - ## Test Fixtures (BLOCKED — requires ffmpeg) - [ ] Create test media fixtures in `backend/playout/testdata/`: diff --git a/MONITORING.md b/docs/MONITORING.md similarity index 100% rename from MONITORING.md rename to docs/MONITORING.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..6dd9152 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,41 @@ +# Docs Folder + +This folder contains the documentation for the Linear Void project. The documentation is organized into several markdown files, each covering different aspects of the project. + +## Architecture + +- [Architecture](architecture/README.md) - High-level system architecture and component interactions. + +## API + +- [API](API.md) - Implemented WebSocket and REST API reference. + +## Deployment + +- [Deployment](DEPLOYMENT.md) - Production deployment and operational runbook. + +## Monitoring + +- [Monitoring](MONITORING.md) - Metrics, dashboards, and monitoring troubleshooting. + +## Security + +- [Security](SECURITY.md) - Security model, controls, and hardening baseline. + +## Setup + +- [Setup](SETUP.md) - Test lab setup, local development, and CI/CD workflow. + +## Streaming + +- [Streaming](STREAMING.md) - Streaming architecture, playout, and delivery details. + +## Development + +- [Development](DEVELOPMENT.md) - Remaining tasks and test fixtures for development. + +## Additional Resources + +- [Marketing](marketing/README.md) - Marketing materials and resources. +- [Operations](operations/README.md) - Operational procedures and checklists. +- [Incident Runbook](incident-runbook.md) - Incident response and disaster recovery procedures. diff --git a/SECURITY.md b/docs/SECURITY.md similarity index 100% rename from SECURITY.md rename to docs/SECURITY.md diff --git a/SETUP.md b/docs/SETUP.md similarity index 100% rename from SETUP.md rename to docs/SETUP.md diff --git a/STREAMING.md b/docs/STREAMING.md similarity index 100% rename from STREAMING.md rename to docs/STREAMING.md diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 3a726fd..6d1134e 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -87,10 +87,12 @@ ## Companion Documentation -- [API.md](../../API.md) - Implemented WebSocket and REST API reference. -- [DEPLOYMENT.md](../../DEPLOYMENT.md) - Production deployment and operational runbook. -- [MONITORING.md](../../MONITORING.md) - Metrics, dashboards, and monitoring troubleshooting. -- [SECURITY.md](../../SECURITY.md) - Security model, controls, and hardening baseline. +- [API.md](../API.md) - Implemented WebSocket and REST API reference. +- [DEPLOYMENT.md](../DEPLOYMENT.md) - Production deployment and operational runbook. +- [MONITORING.md](../MONITORING.md) - Metrics, dashboards, and monitoring troubleshooting. +- [SECURITY.md](../SECURITY.md) - Security model, controls, and hardening baseline. +- [SETUP.md](../SETUP.md) - Test lab setup, local development, and CI/CD workflow. +- [STREAMING.md](../STREAMING.md) - Streaming architecture, playout, and delivery details. ## Introduction and Goals