# algora-io/tv architecture

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

- Interactive diagram: https://gitdiagram.com/algora-io/tv
- Repository: https://github.com/algora-io/tv

## Overview

##### Main System Components

a) Frontend Layer:
- Phoenix LiveView components (under lib/algora_web/live)
- Static assets (JavaScript, CSS, images)
- Web components and layouts

b) Backend Services:
- Authentication system (GitHub OAuth)
- Video processing pipeline
- Chat system
- Advertisement system
- User management
- Content management

c) Storage Systems:
- PostgreSQL database
- Tigris object storage
- Cache layer

d) External Services Integration:
- GitHub OAuth
- Tigris storage
- FFmpeg for video processing

##### Detailed Architecture Representation

**Client Layer**
- Web Interface (Phoenix LiveView)
- OBS Studio Integration
- Video Player Interface

**API/Web Layer**
- Phoenix Controllers
- LiveView Handlers
- WebSocket Channels
- API Endpoints

**Core Services Layer**
- Account Management
- User, Identity, Entity management
- Video Pipeline
- RTMP Server
- HLS Processing
- Video Processing Workers
- Chat System
- Message Processing
- Presence Tracking
- Advertisement System
- Ad Management
- Analytics
- Content Management
- Shows
- Channels
- Videos

**Storage Layer**
- PostgreSQL Database
- Tigris Object Storage
- Cache System

**External Services**
- GitHub OAuth
- FFmpeg
- ImageMagick

##### Data Flow Representation

a) Livestreaming Flow:
**Streamer → RTMP → Pipeline Processing → HLS → Tigris Storage → Viewers**

b) Video Upload Flow:
**Upload → Processing Pipeline → Storage → Distribution**

c) Authentication Flow:
**User → GitHub OAuth → Account System → Session Management**

##### Special Focus Areas

- Real-time aspects (WebSocket, LiveView)
- Advertisement integration points
- Demonstrate the scaling points (Fly.io deployment)

##### Additional Elements

- Monitoring and telemetry components
- Error handling paths
- Backup and recovery flows
- Scaling points and load balancing

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and classes
    classDef frontend fill:#e1f5fe,stroke:#01579b
    classDef backend fill:#e8f5e9,stroke:#1b5e20
    classDef storage fill:#fff3e0,stroke:#e65100
    classDef external fill:#f3e5f5,stroke:#4a148c
    classDef pipeline fill:#fbe9e7,stroke:#bf360c
    classDef chat fill:#e0f2f1,stroke:#004d40

    %% Client Layer
    subgraph ClientLayer["Client Layer"]
        WebUI["Web Interface"]:::frontend
        OBS["OBS Studio"]:::external
        VideoPlayer["Video Player"]:::frontend
    end

    %% API/Web Layer
    subgraph WebLayer["API/Web Layer"]
        LiveView["Phoenix LiveView"]:::frontend
        Controllers["Controllers"]:::backend
        WebSockets["WebSocket Channels"]:::backend
        APIEndpoints["API Endpoints"]:::backend
    end

    %% Core Services Layer
    subgraph CoreServices["Core Services Layer"]
        AccountMgmt["Account Management"]:::backend
        VideoPipeline["Video Pipeline"]:::pipeline
        ChatSystem["Chat System"]:::chat
        AdSystem["Advertisement System"]:::backend
        ContentMgmt["Content Management"]:::backend
    end

    %% Storage Layer
    subgraph StorageLayer["Storage Layer"]
        PostgreSQL[(PostgreSQL)]:::storage
        TigrisStorage[(Tigris Storage)]:::storage
        Cache[(Cache System)]:::storage
    end

    %% External Services
    subgraph ExternalServices["External Services"]
        GitHub["GitHub OAuth"]:::external
        FFmpeg["FFmpeg"]:::external
        ImageMagick["ImageMagick"]:::external
    end

    %% Streaming Pipeline
    subgraph StreamingPipeline["Streaming Pipeline"]
        RTMP["RTMP Server"]:::pipeline
        HLSProcessor["HLS Processing"]:::pipeline
        VideoWorkers["Video Workers"]:::pipeline
    end

    %% Relationships
    OBS --> RTMP
    RTMP --> HLSProcessor
    HLSProcessor --> VideoWorkers
    VideoWorkers --> TigrisStorage
    TigrisStorage --> VideoPlayer

    WebUI --> LiveView
    LiveView --> Controllers
    LiveView --> WebSockets
    Controllers --> APIEndpoints

    WebSockets --> ChatSystem
    ChatSystem --> PostgreSQL
    
    AccountMgmt --> GitHub
    AccountMgmt --> PostgreSQL
    
    VideoPipeline --> FFmpeg
    VideoPipeline --> TigrisStorage
    
    ContentMgmt --> PostgreSQL
    ContentMgmt --> TigrisStorage
    
    AdSystem --> PostgreSQL
    Cache --> PostgreSQL

    %% Click events for component mapping
    click LiveView "https://github.com/algora-io/tv/tree/main/lib/algora_web/live/"
    click Controllers "https://github.com/algora-io/tv/blob/main/lib/algora_web/controllers/github_controller.ex"
    click WebSockets "https://github.com/algora-io/tv/blob/main/lib/algora_web/websockets/chat_socket.ex"
    click AccountMgmt "https://github.com/algora-io/tv/tree/main/lib/algora/accounts/"
    click VideoPipeline "https://github.com/algora-io/tv/tree/main/lib/algora/pipeline/"
    click ChatSystem "https://github.com/algora-io/tv/tree/main/lib/algora/chat/"
    click AdSystem "https://github.com/algora-io/tv/tree/main/lib/algora/ads/"
    click ContentMgmt "https://github.com/algora-io/tv/tree/main/lib/algora/library/"
    click PostgreSQL "https://github.com/algora-io/tv/blob/main/lib/algora/repo.ex"
    click TigrisStorage "https://github.com/algora-io/tv/blob/main/lib/algora/storage.ex"
    click Cache "https://github.com/algora-io/tv/blob/main/lib/algora/cache.ex"
    click GitHub "https://github.com/algora-io/tv/blob/main/lib/algora/github.ex"
    click RTMP "https://github.com/algora-io/tv/blob/main/lib/algora/pipeline/source_bin.ex"
    click HLSProcessor "https://github.com/algora-io/tv/tree/main/lib/algora/pipeline/hls/"
    click VideoWorkers "https://github.com/algora-io/tv/blob/main/lib/algora/workers/hls_transmuxer.ex"

    %% Legend
    subgraph Legend["Legend"]
        Frontend["Frontend Component"]:::frontend
        Backend["Backend Service"]:::backend
        Storage["Storage System"]:::storage
        External["External Service"]:::external
        Pipeline["Pipeline Component"]:::pipeline
        ChatComp["Chat Component"]:::chat
    end
```
