How fx64b/video-archiver works
Project Type and Purpose
• This is a full-stack, self-hosted YouTube video archiver. Its purpose is to download, manage, and organize YouTube videos locally.
• The backend (located at /services/backend) implements the video download, queue management, WebSocket updates, and database operations.
• The frontend (located in /web) is built with Next.js and shadcn/ui, serving a modern UI for managing downloads and monitoring progress in real time.
Analyzing the File Structure
• The repository is clearly divided into services and web. The “services/backend” directory shows a modular Go backend with well-organized subdirectories:
• cmd/api: the entry point for the API.
• internal/api/handlers: REST/WebSocket handlers.
• internal/domain, repositories (with SQLite repositories), and specific internal/services (download, metadata) which indicate separation of concerns.
• The “web” directory contains a Next.js frontend with routes, API endpoints (for example: web/app/api/info), React components, and state management (Zustand under /web/store) for real-time interactions.
• Supplementary files such as Docker-related files (docker-compose.yml, Dockerfile in both backend and web) indicate containerization for easy deployment.
a. Main Components to Represent:
• Client (Web Browser / User Interface): Represents the Next.js-based web application.
• Frontend Service: The Next.js application’s components.
• Backend Service: The Go backend which comprises API endpoints, business logic (queue management, video downloading), internal services (download progress, metadata handling), and repository access.
• Database: SQLite database used by the backend for persistent storage.
• Docker & Deployment: Containers orchestrated with docker-compose include both frontend and backend.
b. Interactions and Data Flow:
• The front end communicates with the backend through HTTP API calls (and potentially WebSocket connections for real-time download progress).
• The backend interacts with the SQLite database through its repository layer.
• The WebSocket service (within the backend’s download service) pushes real-time updates to the frontend.
• External services (like YouTube) are invoked indirectly through libraries (e.g., via yt-dlp) when processing download requests.
• Docker containers encapsulate both services, with the docker-compose file coordinating their startup and network configuration.
c. Architectural Patterns & Design Principles:
• Separation of Concerns: Clear separation between the client-side (Next.js) and backend (Go service) responsibilities.
• Modular Design: The backend is modularized into command, internal API handlers, configuration, domain, repositories, and services.
• Real-Time Communication: Use of WebSocket for immediate download progress updates.
• Containerization: Docker-based deployment leveraging docker-compose for an isolated and replicable environment.
• Use of MVC-like principles in the backend /services structure (Handlers for controllers, domain models, repository for data access).
d. Technologies, Frameworks, and Libraries:
• Backend: Go (v1.23), Chi router, and a SQLite data store.
• Frontend: Next.js (v15) in TypeScript, shadcn/ui for modern UI components, Zustand for state management.
• Real-Time: WebSocket for live download progress updates.
• Deployment/CI: Docker, Docker Compose, GitHub Actions workflows (in .github/workflows).