Skip to content

Video Streaming System Architecture

Date: 2025-07-04
Status: Accepted
Authors: Canh
Deciders: canh-labs
Supersedes: -
Superseded-by: -

Context and Problem Statement

We are building a video streaming system where users can browse and watch videos on demand. The system must handle streaming efficiently, support video metadata management, in-memory caching, background download jobs, and telemetry for monitoring.

We adopt the C4 Model to document our software architecture in 3 levels: System Context, Container, and Component (for Backend).


Decision Drivers

  • Efficient video streaming with support for chunked responses
  • Clear separation between frontend/backend/database
  • Future-proof design with Redis integration and observability
  • Developer onboarding and system clarity

Considered Options

  • Express + Node.js (not chosen)
  • Monolithic Spring Boot with embedded Tomcat and Virtual Threads ✅
  • CDN-based architecture (planned in future)

Decision Outcome

Adopt Spring Boot monolith with clearly defined layers and caching mechanism, and monitor it via OpenTelemetry and Grafana Cloud.


Architecture Overview (C4 Model)

Level 1 - System Context

img.png


Level 2 - Container Diagram

img_1.png


Level 3 - Component Diagram (Backend)

img_2.png


Deployment Diagram

Deployment.png


Deployment process (Current CICD)

CiCd-Deployment.png


Gitops Continuous Deployment Process (Future improvement)

Gitops-arch.png


Consequences

  • Easy to scale the backend horizontally
  • Clear layering improves maintainability
  • Video chunk caching can be switched from Guava to Redis later
  • Monitoring is decoupled and aligned with observability standards

✨ Optimizations

  • ✅ Uses virtual threads for controller to handle concurrent streams efficiently
  • ✅ Uses Guava cache abstraction to allow future swap to Redis
  • ✅ OTEL-compatible tracing enabled via agent .jar and WithSpan on service methods
  • ✅ Metrics collected via CacheStatsService for total hits, misses, and per-file stats

Future Improvements

  • Switch to HLS or DASH for adaptive bitrate
  • Upload background jobs to warm cache by pre-fetching popular videos
  • Support Redis-based distributed cache with same AppCache abstraction
  • Use async Netty-based streaming for ultimate IO scalability

Notes

  • Virtual Threads are used in Backend for efficient streaming
  • In-memory cache with Guava used until Redis is integrated
  • CronJob handles background downloading and database update

Architecture Decision Records (ADR)

The following ADRs record the key decisions made for this system. Each links to the full decision document including context, options considered, and consequences. Status mirrors tracking.md.

ADR Title Status
ADR-0001 Use Relational Database (PostgreSQL) for Core Data Accepted
ADR-0002 Use Layered Spring Boot Architecture with Virtual Threads Accepted
ADR-0003 Use Guava Cache Initially, with Planned Migration to Redis Accepted
ADR-0004 Use Vanilla JS + Bootstrap with Planned Migration to React Accepted (superseded by 0008)
ADR-0005 Use LRU Cache for Video Streaming Accepted
ADR-0007 Admin Dashboard — Content & Account Management Accepted
ADR-0008 Migrate Frontend to React with Vite Accepted
ADR-0009 Unified Video List API for UI Display Proposed
ADR-0010 Add Trivy Dependency & Filesystem Scanning to CI Accepted
ADR-0011 Hot Video Priority Scoring Accepted
ADR-0012 Bookmark Feature — Collections-first Storage and API Accepted
ADR-0013 Watch History — Recording, Cap, and Re-watch Superseded by 0021
ADR-0014 Watch History — Recording, Storage, and Ownership Superseded by 0021
ADR-0015 Bitwise Permission System — Fine-Grained Method Authorization Accepted
ADR-0016 User Settings — Storage, API Shape, and Account Deletion Accepted
ADR-0017 User Notifications Accepted
ADR-0018 Optional Email + Password Login Accepted
ADR-0019 Admin Video Import (YouTube / Facebook → Google Drive) Accepted
ADR-0020 Internationalization (Vietnamese + English) Accepted
ADR-0021 Watch History Accepted

Decision Map

The diagram below groups the ADRs by architectural layer. A solid arrow means "builds on"; a dashed arrow means "superseded by". Superseded ADRs are greyed out and Proposed ADRs have a dashed border.

graph TD
    subgraph "Data Layer"
        ADR1[ADR-0001<br/>PostgreSQL]
        ADR3[ADR-0003<br/>Guava Cache → Redis]
        ADR5[ADR-0005<br/>LRU Cache for Streaming]
    end

    subgraph "Backend Platform"
        ADR2[ADR-0002<br/>Spring Boot + Virtual Threads]
        ADR9[ADR-0009<br/>Unified Video List API]
        ADR11[ADR-0011<br/>Hot Video Priority]
        ADR10[ADR-0010<br/>Trivy CI Scanning]
    end

    subgraph "Security & Access"
        ADR15[ADR-0015<br/>Bitwise Permissions]
        ADR18[ADR-0018<br/>Password Login Option]
    end

    subgraph "Admin"
        ADR7[ADR-0007<br/>Admin Dashboard]
        ADR19[ADR-0019<br/>Admin Video Import]
    end

    subgraph "User Features"
        ADR12[ADR-0012<br/>Bookmarks → Collections]
        ADR13[ADR-0013<br/>Watch History v1]
        ADR14[ADR-0014<br/>Watch History v1 Opus]
        ADR21[ADR-0021<br/>Watch History]
        ADR16[ADR-0016<br/>User Settings]
        ADR17[ADR-0017<br/>Notifications]
    end

    subgraph "Frontend"
        ADR4[ADR-0004<br/>Vanilla JS + Bootstrap]
        ADR8[ADR-0008<br/>React + Vite]
        ADR20[ADR-0020<br/>i18n VI / EN]
    end

    ADR2 --> ADR1
    ADR3 --> ADR2
    ADR5 --> ADR3
    ADR9 --> ADR2
    ADR9 --> ADR5
    ADR11 --> ADR5
    ADR10 --> ADR2
    ADR15 --> ADR2
    ADR7 --> ADR2
    ADR7 --> ADR15
    ADR19 --> ADR7
    ADR19 --> ADR17
    ADR12 --> ADR9
    ADR12 --> ADR11
    ADR16 --> ADR15
    ADR17 --> ADR3
    ADR17 --> ADR16
    ADR18 --> ADR16
    ADR21 --> ADR20
    ADR20 --> ADR8
    ADR4 -.-> ADR8
    ADR13 -.-> ADR21
    ADR14 -.-> ADR21

    classDef proposed stroke-dasharray: 5 5
    classDef superseded fill:#eee,color:#888,stroke:#bbb
    class ADR9 proposed
    class ADR4,ADR13,ADR14 superseded