# fx64b/video-archiver architecture

> Architecture diagram of the GitHub repository fx64b/video-archiver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fx64b/video-archiver
- Repository: https://github.com/fx64b/video-archiver

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Frontend
    A["User / Web Client"]:::frontend
    subgraph "Next.js Frontend"
        B1["API Routes"]:::frontend
        B2["UI Components"]:::frontend
        B3["State Management"]:::frontend
    end
    A -->|"Browses"| B2
    B1 ---|"Handles API calls"| B2

    %% Frontend to Backend Communication
    B1 -->|"REST/WebSocket"| C

    %% Backend Service and its Modules
    subgraph "Go Backend Service"
        C["Backend Service (Go API)"]:::backend
        C -->|"Routes request"| C1["API Handlers"]:::backend
        C -->|"Triggers download"| C2["Download Service"]:::backend
        C -->|"Manages metadata"| C3["Metadata Service"]:::backend
        C -->|"Data access"| C4["Repository Layer"]:::backend
    end

    %% Repository Layer and Database
    C4 -->|"Queries"| D["SQLite Database"]:::database
    D -->|"Uses schema"| E["Database Schema"]:::database

    %% External YouTube Integration
    C2 -->|"yt-dlp call"| F["External YouTube Service"]:::external

    %% Docker & Containerization
    subgraph "Docker & Containerization"
        F1["docker-compose.yml"]:::docker
        F2["Backend Dockerfile"]:::docker
        F3["Frontend Dockerfile"]:::docker
    end
    F1 ---|"Orchestrates"| C
    F1 ---|"Orchestrates"| B1

    %% Click Events for Frontend Components
    click A "https://github.com/fx64b/video-archiver/tree/main/web/"
    click B1 "https://github.com/fx64b/video-archiver/tree/main/web/app"
    click B2 "https://github.com/fx64b/video-archiver/tree/main/web/components"
    click B3 "https://github.com/fx64b/video-archiver/tree/main/web/store"

    %% Click Events for Backend Components
    click C "https://github.com/fx64b/video-archiver/tree/main/services/backend/cmd/api"
    click C1 "https://github.com/fx64b/video-archiver/blob/main/services/backend/internal/api/handlers/handlers.go"
    click C2 "https://github.com/fx64b/video-archiver/tree/main/services/backend/internal/services/download"
    click C3 "https://github.com/fx64b/video-archiver/blob/main/services/backend/internal/services/metadata/metadata.go"
    click C4 "https://github.com/fx64b/video-archiver/tree/main/services/backend/internal/repositories/sqlite"
    click E "https://github.com/fx64b/video-archiver/blob/main/services/backend/db/schema.sql"

    %% Click Events for Docker Components
    click F1 "https://github.com/fx64b/video-archiver/blob/main/docker-compose.yml"
    click F2 "https://github.com/fx64b/video-archiver/tree/main/services/backend/Dockerfile"
    click F3 "https://github.com/fx64b/video-archiver/tree/main/web/Dockerfile"

    %% Styles
    classDef frontend fill:#aaddff,stroke:#000,stroke-width:2px;
    classDef backend fill:#ccffcc,stroke:#000,stroke-width:2px;
    classDef database fill:#ffd699,stroke:#000,stroke-width:2px;
    classDef external fill:#cccccc,stroke:#000,stroke-width:2px;
    classDef docker fill:#e0bbff,stroke:#000,stroke-width:2px;
```
