# otaviootavio/custom-hls architecture

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

- Interactive diagram: https://gitdiagram.com/otaviootavio/custom-hls
- Repository: https://github.com/otaviootavio/custom-hls

## Overview

##### Project type and purpose
- This is a multi‑component, decentralized video‑streaming platform with micropayments. It consists of four sub‑projects orchestrated by Docker Compose:
- eth‑payword: Ethereum smart contract (Hardhat) + React dApp
- extension: Browser extension for hash‑chain management
- mp4‑to‑hls: Command‑line utility to convert MP4 to HLS segments
- my‑hls‑app: Next.js frontend+API for streaming HLS with PayWord payments

##### High‑level component breakdown
- Ethereum Blockchain: Runs the PayWord smart contract
- Hardhat (eth‑payword/hardhat): Local dev/test node, contracts, tests, deployment scripts
- dApp Frontend (eth‑payword/frontend): React/TS UI for contract interaction
- Browser Extension (extension/src): React/TS popup, background, content scripts to manage and inject hash‑chains
- Video Conversion Utility (mp4‑to‑hls): Node.js script producing .m3u8 and .ts files
- Streaming App (my‑hls‑app): Next.js SSR/CSR pages, API routes, Prisma schema, HLS player
- Storage Layer: Local folder or S3 bucket for HLS segments
- Orchestration: docker‑compose for services (blockchain node, possibly IPFS or local file server)
- External Services: Ethereum node (Infura or local), Package registry (pnpm), CI/CD

##### Relationships and data‑flow
- User’s browser → my‑hls‑app UI → requests video playlist (.m3u8) & segments (.ts)
- my‑hls‑app → (optionally) fetches/updates payment state via its API routes → interacts with PayWord smart contract over web3
- dApp (eth‑payword/frontend) → direct contract interactions: open/close channels, issue hash‑chain
- Browser Extension → maintains local hash‑chain, injects it into dApp or my‑hls‑app pages, signs micropayment tokens
- mp4‑to‑hls utility → pre‑processes source videos into HLS assets stored in playlist directory or bucket
- Docker Compose → spins up blockchain node, streaming app, and any other services for local dev

##### Architectural patterns and design principles
- Monorepo style with clearly separated sub‑projects
- Frontend‑backend separation: Next.js for SSR + API, standalone React dApp, React extension UI
- Microservices / utility: mp4 converter as isolated CLI service
- Payment channel pattern: off‑chain hash‑chain generation, on‑chain settlement
- Context providers & hooks in React for global state (HashChainProvider, Wagmi, Zod schema validation)

##### Technologies & frameworks
- Smart contracts: Solidity, Hardhat, TypeScript
- Frontends & extension: React, TypeScript, Vite, Next.js, Tailwind CSS, Zod
- Storage & API: Prisma (PostgreSQL or other), Next.js API routes, local filesystem or S3
- Blockchain interaction: ethers.js, wagmi
- Orchestration & packaging: Docker Compose, pnpm, vite, tsconfig

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph: Ethereum & Hardhat
    subgraph "Ethereum & Hardhat" 
        direction TB
        HLN["Hardhat Local Node"]:::blockchain
        SC["PayWord.sol (Smart Contract)"]:::blockchain
        Tests["Hardhat Tests & Scripts"]:::backend
    end

    %% Subgraph: dApp Frontend
    subgraph "eth-payword dApp" 
        direction TB
        DAppUI["React dApp UI"]:::frontend
    end

    %% Subgraph: Browser Extension
    subgraph "Browser Extension" 
        direction TB
        ExtUI["Popup UI & Content Scripts"]:::frontend
        ExtBG["Background Script & IndexedDB"]:::backend
    end

    %% Subgraph: Video Conversion CLI
    subgraph "mp4-to-hls Utility" 
        direction TB
        CLI["MP4→HLS Converter"]:::backend
    end

    %% Subgraph: Streaming App
    subgraph "my-hls-app" 
        direction TB
        NextPages["Next.js SSR/CSR Pages"]:::frontend
        API["Next.js API Routes"]:::backend
        PrismaDB["Prisma Schema & DB"]:::backend
        HLSStore["HLS Assets Storage"]:::storage
    end

    %% Orchestration & External Services
    subgraph "Orchestration & External" 
        direction TB
        Compose["Docker Compose"]:::backend
        ExtNode["Ethereum RPC (Infura/local)"]:::blockchain
        Reg["Package Registry (pnpm)"]:::backend
    end

    %% User Browser
    Browser["User Browser"]:::external

    %% Data Flows
    Browser -->|plays video| NextPages
    NextPages -->|HTTP: fetch .m3u8/.ts| HLSStore
    NextPages -->|API call| API
    API -->|Query/Update Payment| PrismaDB
    API -->|RPC call| ExtNode
    ExtNode -->|OpenChannel/Settle| SC
    DAppUI -->|RPC call| ExtNode
    ExtNode -->|deploy/interact| SC
    ExtUI -->|inject hash-chain| DAppUI
    ExtUI -->|sign micropayment| ExtBG
    CLI -->|outputs .m3u8/.ts| HLSStore
    Compose -->|orchestrates services| HLN
    Compose -->|orchestrates services| NextPages
    Compose -->|orchestrates services| CLI

    %% Click Events
    click HLN "https://github.com/otaviootavio/custom-hls/blob/main/eth-payword/hardhat/hardhat.config.ts"
    click SC "https://github.com/otaviootavio/custom-hls/tree/main/eth-payword/hardhat/contracts"
    click Tests "https://github.com/otaviootavio/custom-hls/tree/main/eth-payword/hardhat/test"
    click Tests "https://github.com/otaviootavio/custom-hls/tree/main/eth-payword/hardhat/ignition"
    click DAppUI "https://github.com/otaviootavio/custom-hls/tree/main/eth-payword/frontend/src"
    click ExtUI "https://github.com/otaviootavio/custom-hls/tree/main/debug-web-extension/src"
    click CLI "https://github.com/otaviootavio/custom-hls/blob/main/mp4-to-hls/convert.js"
    click NextPages "https://github.com/otaviootavio/custom-hls/tree/main/my-hls-app/src"
    click HLSStore "https://github.com/otaviootavio/custom-hls/tree/main/my-hls-app/hls"
    click API "https://github.com/otaviootavio/custom-hls/tree/main/my-hls-app/src/pages/api"
    click PrismaDB "https://github.com/otaviootavio/custom-hls/blob/main/my-hls-app/prisma/schema.prisma"
    click Compose "https://github.com/otaviootavio/custom-hls/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,stroke-width:2px
    classDef backend fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef blockchain fill:#ffe5b4,stroke:#ff9933,stroke-width:2px
    classDef storage fill:#e2e3e5,stroke:#6c757d,stroke-width:2px
    classDef external fill:#f8d7da,stroke:#dc3545,stroke-width:2px
```
