Use Streaming Media Platform as the Foundational Architecture Pattern
Deterministic ADR derived from topology, simulation, and advisor intelligence for Streaming Media Platform. Traceable to YAML knowledge entities.
Context
Video platforms have a fundamentally asymmetric I/O profile: writes happen at upload time (large sequential blobs, one writer per upload) but reads happen at playback time (small random segments, millions of concurrent readers). A transcoding pipeline that saturates on upload spikes will delay content availability. A CDN that serves 95% of traffic hides the backend until a cache miss or content update propagates: at that moment, origin servers must absorb a thundering herd without collapsing. Viewing history is write-heavy and time-ordered, making it a poor fit for PostgreSQL at scale, but it must be queryable for recommendations and compliance. The operational challenge is managing these three distinct I/O profiles (upload burst, playback steady-state, history write volume) under a single deployment. Primary operational risks include: Transcoding queue saturation during upload bursts: a viral event or scheduled batch upload can push thousands of multi-gigabyte files into the Kafka transcoding topic simultaneously; if worker capacity cannot absorb the burst, queue lag grows and content availability SLA is breached for all uploaders, not just the burst source; CDN cold start thundering herd: when a high-traffic video is first published or when CDN nodes are invalidated after an update, simultaneous playback requests miss the CDN and hit the MinIO origin directly; without rate limiting at the origin layer, this creates an I/O spike that degrades delivery for all content; Cassandra hot partition on popular content: viewing history writes for a single viral video concentrate on the Cassandra partition keyed by content_id; unbalanced partition load exhausts I/O on one or two nodes while others are idle.
Decision
We will adopt the **Streaming Media Platform** architecture pattern. This is a high-complexity architecture appropriate for teams at experienced backend team level or above. The advisor rates this pattern as 'advanced' operational maturity.
Rationale
A video and audio streaming architecture where content ingestion triggers an async multi-variant transcoding pipeline, CDN delivery handles 95%+ of playback traffic, and Cassandra absorbs the write volume of per-user viewing history. Kafka decouples upload events from transcoding workers; MinIO stores raw and encoded assets; Redis maintains playback session state and view counters. The architecture must handle upload spikes without blocking delivery, and cache cold starts without cascading database load. Core technology stack: kafka, cassandra, postgresql, redis, minio.
Accepted Tradeoffs
- ⚠Kafka-backed transcoding decouples upload acceptance from worker capacity, allowing uploads to succeed while workers process at a controlled rate: but the queue becomes the visible indicator of content availability lag, and operators must size the consumer group to meet SLA rather than leaving queue depth unmonitored
- ⚠Cassandra absorbs viewing history writes at scale without lock contention, but Cassandra's read model is query-pattern-driven at schema design time; ad-hoc analytical queries (e.g., "total views by region last 30 days") require either a separate analytics pipeline or pre-designed materialized tables
- ⚠CDN caching eliminates origin load for popular content but creates a correctness hazard during content updates: cache invalidation must be synchronous and verified, not fire-and-forget, or users see stale or partially-updated content
- ⚠MinIO as object storage provides on-premises cost control and avoids per-GB egress charges, but operational burden (disk management, replication, erasure coding configuration) is entirely on the platform team rather than a managed provider
- ⚠Storing multiple transcoded variants (360p, 720p, 1080p, 4K HLS) multiplies storage costs 3–5x per original asset; retention policy must be explicit and automated or storage growth will exceed budget within months at moderate upload volume
Risks
Message queue or event stream consumer processing rate falls below producer write rate, causing consumer lag to grow unboundedly: eventually leading to increased end-to-end latency, producer backpressure, data expiry, or queue resource exhaustion.
When a popular cached key expires or a service recovers from downtime, all requests that were waiting or arrive simultaneously miss the cache and hit the origin database concurrently, producing a request spike that can overwhelm the database within seconds.
The storage device reaches its IOPS or throughput ceiling, causing all disk- dependent database operations to queue behind I/O requests, driving latency from sub-millisecond to hundreds of milliseconds and degrading all database operations simultaneously.
One partition (a database shard, a Kafka topic partition, a Redis hash slot) receives traffic so far above its peers that it saturates while the others sit idle. Aggregate capacity looks healthy, but the hot partition throttles or lags, and everything routed to it degrades. The cause is skew in how keys map to partitions, and the fix depends on whether the skew is spread across many keys or concentrated in one.
A failure or degradation in one service causes increased load, held resources, or error propagation in its callers, which in turn degrade their callers, until the failure front propagates through the entire dependency graph and brings down services with no direct dependency on the original failure point.
Alternatives Considered
AI Retrieval-Augmented Generation Platform shares core technology (kafka, postgresql) with the chosen architecture but applies different structural patterns; Streaming Media Platform is a better fit for the identified workload profile.
Analytics Data Platform shares core technology (kafka, postgresql) with the chosen architecture but applies different structural patterns; Streaming Media Platform is a better fit for the identified workload profile.
API Gateway Platform shares core technology (kafka, postgresql) with the chosen architecture but applies different structural patterns; Streaming Media Platform is a better fit for the identified workload profile.
Audit and Compliance Platform shares core technology (kafka, postgresql) with the chosen architecture but applies different structural patterns; Streaming Media Platform is a better fit for the identified workload profile.
Scaling Thresholds
Signals indicating the architecture is approaching its scaling limits:
Tier 1: Transcoding Worker Throughput
Signal: Kafka consumer group lag on the transcoding topic growing during peak upload hours; content availability delay > 10 minutes for newly uploaded videos; transcoding worker CPU consistently above 85% across all instances
Evolution: Increase transcoding consumer instances up to the transcoding topic partition count; tune partition count to match the maximum desired worker parallelism (set this at topic creation, not after lag appears); implement per-uploader upload rate limits to smooth burst input; consider priority queuing so premium-tier content does not wait behind bulk ingest jobs
Tier 2: CDN Origin Thundering Herd
Signal: MinIO GET request rate spikes > 10x baseline immediately after content publish or CDN invalidation; MinIO p99 latency > 500ms; CDN miss ratio > 5% on popular content
Evolution: Implement origin request coalescing (single origin fetch per CDN node per object, queue subsequent requestors for the in-flight response); pre-warm CDN edges for anticipated high-traffic content before publish; add rate limiting at the origin gateway to cap per-second origin requests per content_id
Tier 3: Cassandra Partition Hot Spot
Signal: Cassandra node CPU imbalance > 40% across cluster; write latency p99 spiking on specific nodes; nodetool tpstats showing dropped mutations on hot nodes
Evolution: Add a write_bucket component to the partition key (e.g., content_id + time bucket modulo N) to distribute writes across N partitions per content_id; tune N based on expected peak write rate per content item; read queries must fan out across all N buckets and merge, which increases read complexity but eliminates write hotspots
Tier 4: Multi-Region Delivery Reach
Signal: Playback start latency > 2s for users > 100ms RTT from origin; CDN miss rate growing due to content catalog size exceeding CDN edge cache capacity; regulatory requirements for content localization or data residency in specific regions
Evolution: Deploy regional MinIO object storage with asynchronous replication of popular content to regional origins; implement geo-routing at the CDN layer to direct playback requests to the nearest origin; Kafka multi-region replication for transcoding event propagation to regional worker fleets
Migration Path
Synchronous transcoding in the upload request handler (blocking API response) → Async transcoding via Kafka topic with competing consumer workers
Upload API p99 exceeding 30 seconds due to in-process transcoding blocking the response; upload timeouts reported by client applications during large file uploads
Viewing history in PostgreSQL → Viewing history in Cassandra
PostgreSQL viewing history table exceeding 500M rows; write latency on history inserts affecting OLTP transaction throughput on the shared primary; history queries scanning large time ranges causing sequential scan pressure
Single CDN provider with no origin rate limiting → Multi-CDN with origin request coalescing and rate limiting
CDN provider incident causing total origin failover; CDN miss rate increasing as content catalog grows; origin costs growing unsustainably due to cache bypass on content updates
Operational Requirements
- Minimum team maturity: Experienced Backend Team: This scenario has high operational complexity. It is recommended for Experienced Backend Team teams or higher.
- Runbooks and alerting for high-severity risks: 5 high-severity risks identified. Each requires a documented runbook, alerting threshold, and on-call response procedure before running in production.
- Event stream operations expertise: This architecture includes event stream infrastructure (Kafka, Kinesis, or similar). Operations requires consumer group management, partition assignment, dead-letter handling, and lag monitoring.
- Cache sizing and eviction policy configuration: Redis or equivalent cache requires correct maxmemory configuration, eviction policy selection (allkeys-lru is common), and cold-start warming strategy after restarts.