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¶

Level 2 - Container Diagram¶

Level 3 - Component Diagram (Backend)¶

Deployment Diagram¶

Deployment process (Current CICD)¶

Gitops Continuous Deployment Process (Future improvement)¶

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
.jarandWithSpanon service methods - ✅ Metrics collected via
CacheStatsServicefor 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
AppCacheabstraction - 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