[Open Source] #187 - Boxarr: Hệ thống tự động hóa thư viện phim dựa trên dữ liệu Box Office với FastAPI, Radarr API và cơ chế Movie Matching thông minh

Trong hệ sinh thái máy chủ phim ảnh (Homelab), việc quản lý thư viện thông qua Radarr thường yêu cầu người dùng phải tự tìm kiếm hoặc dựa vào các danh sách tĩnh. Boxarr ra đời như một "người môi giới dữ liệu" (Data Broker) tự động, kết nối trực tiếp xu hướng thị trường từ Box Office Mojo vào hạ tầng của bạn. Hệ thống tự động quét Top 10 phim ăn khách hàng tuần, đối soát với thư viện hiện có và tự động ra lệnh cho Radarr tải về những bộ phim còn thiếu theo các tiêu chuẩn lọc khắt khe.

Dưới góc độ kỹ thuật, Boxarr là một minh chứng xuất sắc về việc xây dựng ứng dụng Asynchronous Python, kỹ thuật Movie Matching dựa trên xử lý ngôn ngữ tự nhiên và kiến trúc Sidecar tối ưu cho Docker.

Github: https://github.com/v8u7/boxarr

🛠️ 1. Nền tảng công nghệ: Hiệu năng Async và Sự linh hoạt

Boxarr tận dụng tối đa hệ sinh thái Python hiện đại để xử lý các tác vụ I/O cường độ cao mà không làm chậm hệ thống:

• Core Engine (FastAPI): Sử dụng FastAPI để tận dụng tốc độ xử lý bất đồng bộ (async/await). Điều này cực kỳ quan trọng khi ứng dụng phải thực hiện đồng thời việc cào dữ liệu từ web và gọi hàng loạt API tới Radarr/TMDB.
• Data Scraper (httpx & BeautifulSoup4): Thay vì dùng requests truyền thống gây nghẽn mạch (blocking), Boxarr sử dụng httpx để thực hiện các yêu cầu mạng non-blocking, kết hợp với bộ máy phân tích cú pháp HTML mạnh mẽ để trích xuất dữ liệu doanh thu thời gian thực.
• Task Orchestration (APScheduler): Tích hợp sẵn bộ máy lập lịch tác vụ chuyên nghiệp, cho phép người dùng cấu hình các chu kỳ quét (Cron) linh hoạt ngay trên giao diện web.
• Validation Layer (Pydantic): Toàn bộ dữ liệu từ API và tệp cấu hình được kiểm soát chặt chẽ bởi Pydantic, đảm bảo tính toàn vẹn dữ liệu trước khi thực hiện các hành động ghi vào Radarr.

🏗️ 2. Trụ cột kiến trúc: Service-Oriented và Stateless Persistence

Kiến trúc của Boxarr được thiết kế theo tư duy module hóa cao độ, dễ dàng mở rộng và bảo trì:

• Decoupled Services: Hệ thống chia nhỏ logic thành các Service chuyên biệt:
  • RadarrService: Chuyên trách giao tiếp API và quản lý trạng thái tải về.
  • BoxOfficeService: Quản lý logic bóc tách dữ liệu từ internet.
  • MovieMatcher: "Bộ não" xử lý thuật toán so khớp tiêu đề.
• File-based Persistence: Để giữ cho ứng dụng nhẹ nhất có thể (Lightweight), Boxarr không sử dụng cơ sở dữ liệu quan hệ (SQL). Thay vào đó, nó sử dụng các tệp JSON để lưu trữ lịch sử hàng tuần và YAML cho cấu hình. Cách tiếp cận này giúp việc sao lưu và di chuyển ứng dụng (Portable) trở nên cực kỳ đơn giản.
• Dynamic Reload Architecture: Hệ thống hỗ trợ "Hot-reload" cấu hình. Khi người dùng thay đổi tham số lọc trên UI, Backend tự động cập nhật lại các instance Service và Scheduler mà không cần khởi động lại container.

🔄 3. Workflow: Vòng đời tự động hóa từ Xu hướng đến Thư viện (Sequence Diagram)

Sơ đồ mô tả quy trình Boxarr điều phối dữ liệu giữa internet và máy chủ Radarr:

⚡ 4. Các kỹ thuật "Pro-level" trong mã nguồn

1. Movie Title Normalization Algorithm: Một trong những phần khó nhất là so khớp phim (ví dụ: "John Wick: Chapter 4" vs "John Wick 4"). Boxarr xử lý qua nhiều lớp: loại bỏ ký tự đặc biệt, chuyển đổi số La Mã sang số Thường, xử lý chữ số thành chữ viết (4 -> four) và cắt bỏ phụ đề sau dấu hai chấm.
2. Genre Priority Mapping: Để giải quyết vấn đề một phim có nhiều thể loại (Action, Sci-Fi, Adventure), Boxarr cho phép thiết lập "Độ ưu tiên thư mục". Hệ thống tự động phân tích và đưa phim vào đúng ổ cứng chuyên biệt (Root Folder) dựa trên thể loại có trọng số cao nhất.
3. Metadata Enrichment via Proxy: Mặc dù phim có thể chưa tồn tại trong Radarr, Boxarr vẫn thực hiện một bước "TMDB Lookup" thông qua Radarr API để lấy Poster URL và tóm tắt nội dung, giúp giao diện người dùng luôn chuyên nghiệp và đầy đủ thông tin.
4. Multi-stage Docker Optimization: Dự án sử dụng Docker build nhiều giai đoạn, chỉ giữ lại những runtime cần thiết, giúp Image cuối cùng cực nhỏ và tối ưu cho các thiết bị như Raspberry Pi hoặc Synology NAS.

⚖️ 5. So sánh chiến lược

✅ Kết luận: Tại sao Boxarr là mảnh ghép hoàn hảo cho Media Server?

Boxarr chứng minh rằng sức mạnh của tự động hóa nằm ở việc tinh lọc dữ liệu. Thay vì tải về hàng nghìn bộ phim rác, dự án này tập trung vào những giá trị thực của thị trường điện ảnh. Việc kết hợp giữa kỹ thuật cào dữ liệu bền bỉ và bộ máy so khớp thông minh đã biến Boxarr thành một công cụ không thể thiếu cho bất kỳ ai muốn sở hữu một thư viện phim "luôn luôn mới".

Đối với các kỹ sư Backend, nghiên cứu Boxarr giúp bạn hiểu sâu về:

• Kỹ thuật điều phối Async API requests quy mô lớn.
• Cách xây dựng Movie Matching logic thực tế.
• Tư duy thiết kế Sidecar App trong hệ sinh thái Docker.