Architecture Decision Records (ADRs)
This document captures the key architectural and design decisions made during the development of RUSEON Core, along with the context, alternatives considered, and rationale.
ADR-001: Pure Go Implementation (Zero CGO)
- Context: Video servers traditionally rely on C/C++ for performance, but suffer from memory safety bugs (use-after-free, buffer overflows) and complex cross-compilation toolchains.
- Decision: Implement RUSEON Core entirely in pure Go without CGO dependencies.
- Consequences: Deterministic memory safety, trivial cross-compilation to Linux ARM64/AMD64 and Windows, seamless goroutine concurrency, and single-binary portability.
ADR-002: Zero-Transcoding Transmuxing Architecture
- Context: Transcoding 1080p/4K video consumes significant CPU/GPU resources, limiting server stream density and inflating power consumption.
- Decision: Enforce pure transmuxing (repackaging compressed NAL units into destination container formats like RTP, fMP4, and HLS) without decoding pixels.
- Consequences: Over 90% CPU reduction, enabling a standard 12-core CPU to handle 600+ streams while preserving native camera video quality.
ADR-003: Fragmented MP4 (fMP4) Video Archiving
- Context: Standard monolithic MP4 files write the indexing header (
moovatom) at the end of the file. Sudden power loss corrupts the entire recording. - Decision: Store all recordings in Fragmented MP4 (
moof+mdatfragments per GOP). - Consequences: 100% crash resilience; every flushed keyframe interval is immediately playable without post-processing.
ADR-004: Linux Sliding Window Direct I/O (POSIX_FADV_DONTNEED)
- Context: Continuous video recording of hundreds of streams causes the Linux kernel to buffer gigabytes of dirty pages in RAM Page Cache, leading to system lockups and OOM crashes.
- Decision: Implement a direct cache-dropper calling
unix.SyncFileRangefor non-blocking disk flush andunix.Fadvise(..., FADV_DONTNEED)for page eviction. - Consequences: Completely eliminates Page Cache thrashing; RAM usage remains flat (~471 MB RSS under 600 cameras).
ADR-005: Embedded BadgerDB v4 LSM Engine
- Context: Using external database servers (PostgreSQL/MySQL) complicates deployment, adds operational maintenance overhead, and introduces network latency.
- Decision: Embed BadgerDB v4 (pure Go LSM key-value store with 16MB MemTable).
- Consequences: Single-binary deployment, sub-millisecond timeline range queries, and atomic snapshot backups with zero external dependencies.
ADR-006: WHEP (WebRTC HTTP Egress Protocol)
- Context: Custom WebSocket signaling protocols for WebRTC are proprietary, difficult to load-balance, and hard to integrate with third-party web clients.
- Decision: Adopt the standardized IETF WHEP HTTP signaling protocol (
POST /stream/webrtc/whep/:id). - Consequences: Standard RESTful signaling, seamless reverse proxy traversal, single-port UDP multiplexing, and native compatibility with modern WebRTC players.
ADR-007: Adaptive Linux Kernel sendmmsg UDP Batching
- Context: Sending thousands of individual RTP UDP packets per second over WebRTC causes severe context-switching and CPU overhead in the Linux kernel.
- Decision: Wrap UDP egress in
BatchingUDPMuxConnusingsendmmsgto batch up to 32 packets or flush immediately on RFC 6184 Marker bit ($M=1$). - Consequences: Reduces kernel syscall overhead by 85–90%, enabling thousands of concurrent WebRTC viewers with zero added latency.