# volerus/offline-yt architecture

> Architecture diagram of the GitHub repository volerus/offline-yt, 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/volerus/offline-yt
- Repository: https://github.com/volerus/offline-yt

## Overview

##### Main Components
- Backend Server:
- FastAPI application (app/main.py) that handles API endpoints.
- API modules under app/api, which include routes (and possibly dependencies) and are responsible for exposing endpoints like videos, channels, and settings.
- Database integration with SQLite (configured via SQLAlchemy in app/database).
- Services such as YouTube integration (app/services/youtube.py) and database operations.
- Pydantic schemas for data validation (app/schemas).
- Configuration values (e.g., DOWNLOAD_DIR, DATABASE_URL) that control behavior.
- Frontend Application:
- React-based user interface found in the frontend directory.
- Components (e.g., video cards, channel cards, layout components) that provide the interactive UI.
- Pages and routing (e.g., HomePage, ChannelsPage, DownloadsPage, SettingsPage).
- State management via React context and hooks.
- API service layer (frontend/src/services/api.js) that communicates with the backend.
- External Dependencies:
- yt-dlp for video processing and download management.
- SQLite as a lightweight database.
- Additional tools like ESLint and Webpack for frontend build tooling.
- Packaging & Deployment Components (optional based on future roadmap):
- Electron or py2app for creating standalone desktop apps.
- Docker containerization for local server hosting.
- Reverse proxy (Nginx/Caddy) for HTTPS and network security.

##### Relationships and Interactions
- Within the Backend, the API layer (app/api) interacts with:
- The Database layer (app/database/setup and models) for persistent storage and retrieval.
- Service layers (app/services/youtube.py and database.py) that encapsulate business logic for video processing and channel management using external libraries such as yt-dlp.
- The Database (SQLite) is accessed via SQLAlchemy ORM, forming the bridge between stored data (channels, videos, user settings) and the API.
- Configuration and environment files (e.g., frontend/.env, app/config.py) guide both the client and server behavior.
- Interactions for packaging where the backend startup (using run.py) might be wrapped by a desktop wrapper or managed inside a Docker container.

##### Architectural Patterns and Principles
- Clear separation of concerns (frontend versus backend).
- Use of RESTful API principles: endpoints for videos, channels, settings with operations like GET, POST, DELETE.
- Strict modularization in the backend – controllers (routes), models, schemas, and services are separately organized.
- Emphasis on reusability and scalability through the separation of components and clear service boundaries.
- The security and error handling strategies (FastAPI’s built-in security, custom error responses) should be noted.

- Clear labels for each component (Frontend, Backend API, Database, External Services).
- External services such as yt-dlp and deployment options (another distinct style).
- Any code or configuration snippet highlights, if needed, to tie specific files to architecture (e.g., linking app/api/routes.py to API endpoints).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FEApp["React UI"]:::frontend
        FEComponents["UI Components"]:::frontend
        FEPages["Pages"]:::frontend
        FEAPI["API Service"]:::frontend
        FEState["State Management"]:::frontend
        FEHooks["Hooks"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        FastAPI["FastAPI Application"]:::backend
        APIEndpoints["API Endpoints"]:::backend
        Pydantic["Pydantic Schemas"]:::backend
        YouTubeService["YouTube Video Processing Service"]:::backend
        DBService["Database Operations Service"]:::backend
    end

    %% Database Layer
    subgraph "Database Layer"
        DBSetup["Database Setup"]:::database
        DBModels["Database Models"]:::database
    end

    %% External Services
    subgraph "External Services"
        YtDlp["yt-dlp"]:::external
        Docker["Docker Container (Future)"]:::external
        Electron["Electron Wrapper (Future)"]:::external
        ReverseProxy["Reverse Proxy (Future)"]:::external
    end

    %% Frontend Internal Connections
    FEApp --> FEComponents
    FEApp --> FEPages
    FEApp --> FEState
    FEState --> FEHooks

    %% Frontend to Backend Interaction
    FEAPI -->|"HTTP_Request"| APIEndpoints
    FEApp --> FEAPI

    %% Backend Internal Connections
    APIEndpoints -->|"validates"| Pydantic
    APIEndpoints -->|"calls_service"| YouTubeService
    APIEndpoints -->|"calls_service"| DBService

    %% Backend to External and Database
    YouTubeService -->|"invokes"| YtDlp
    DBService -->|"queries"| DBSetup
    DBService -->|"queries"| DBModels

    %% Click Events
    click FastAPI "https://github.com/volerus/offline-yt/blob/main/app/main.py"
    click APIEndpoints "https://github.com/volerus/offline-yt/blob/main/app/api/routes.py"
    click DBSetup "https://github.com/volerus/offline-yt/blob/main/app/database/setup.py"
    click DBModels "https://github.com/volerus/offline-yt/blob/main/app/models/models.py"
    click Pydantic "https://github.com/volerus/offline-yt/blob/main/app/schemas/schemas.py"
    click YouTubeService "https://github.com/volerus/offline-yt/blob/main/app/services/youtube.py"
    click DBService "https://github.com/volerus/offline-yt/blob/main/app/services/database.py"
    click FEApp "https://github.com/volerus/offline-yt/blob/main/frontend/src/App.js"
    click FEComponents "https://github.com/volerus/offline-yt/tree/main/frontend/src/components/"
    click FEPages "https://github.com/volerus/offline-yt/tree/main/frontend/src/pages/"
    click FEAPI "https://github.com/volerus/offline-yt/blob/main/frontend/src/services/api.js"
    click FEState "https://github.com/volerus/offline-yt/blob/main/frontend/src/context/SettingsContext.js"
    click FEHooks "https://github.com/volerus/offline-yt/tree/main/frontend/src/hooks/"

    %% Styles
    classDef frontend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef backend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef database fill:#ABEBC6,stroke:#1D8348,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
