# furey/fetchtv architecture

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

- Interactive diagram: https://gitdiagram.com/furey/fetchtv
- Repository: https://github.com/furey/fetchtv

## Overview

##### Project Type and Purpose
- fetchtv is a Node.js-based command-line interface (CLI) tool for discovering a Fetch TV server on the local network and downloading its recordings.
- It is not a web-app or microservice; it’s a single process CLI with network-I/O (UPnP/SSDP discovery + HTTP download) and file-system persistence.

##### High-Level File/Directory Analysis
– fetchtv.js: the single entrypoint that parses commands, invokes services, and displays or saves results.
– package.json + package-lock.json: defines runtime dependencies (e.g., commander or yargs for CLI parsing, SSDP/UPnP modules, HTTP clients, template engines, logging).
– Dockerfile + .dockerignore: containerizes the CLI for reproducible execution.
– .github/workflows: CI/CD pipelines for publishing to NPM and Docker Hub.
– repomix.config.json: project metadata and packaging.

##### Key Components
a. User & Shell Layer
- User’s Terminal → invokes `fetchtv` command
b. Process & CLI Layer
- Node.js Runtime → loads fetchtv.js
- Command Parser (commander/yargs) → identifies sub-commands (info, shows, recordings) and options (–ip, –port, –save, –template, –json, –debug)
c. Application Logic Layer
- Controller/Handler per Command → orchestrates discovery, fetch, filtering, formatting, and saving
- Discovery Service → uses UPnP/SSDP to locate Fetch TV device (or takes IP/port override)
- Fetch Service → issues HTTP requests to the device’s API to list shows/recordings or stream TS files
- Template Engine → formats file paths and names (`${show_title}`, `${recording_title}`, `${ext}`, etc.)
d. Persistence & I/O Layer
- Local File System Adapter → writes downloaded media to disk, respects overwrite flags
- Console Output Formatter → plain text or JSON, depending on flags
e. External System
- Fetch TV Server on LAN → UPnP discovery endpoint and HTTP API
f. Deployment & CI/CD
- Docker Build Context → runs the CLI in containers
- GitHub Actions → triggers on push to publish package and Docker image

##### Relationships and Data Flow
– User → Shell/Node.js process → Command Parser
– Parser → Controllers → Discovery Service → Fetch TV (network)
– Controllers → Fetch Service → Fetch TV (network)
– Fetch Service → File System Adapter → Disk
– Controllers → Console Formatter → Terminal
- Data flows from the Fetch TV server back through services into either the console or files.

##### Architectural Patterns & Principles
- Single-process, layered CLI architecture
- Separation of concerns: parsing, discovery, fetch, formatting, persistence
- Configurable via flags (injects IP/port, templates, output format)
- Containerized deployment for consistency

##### Essential Elements
- CLI components (parsers/controllers)
- Network services
- Persistence layers
- External systems

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & Shell Layer
    subgraph "User & Shell Layer"
        U["User Terminal"]:::external
    end

    %% Process & CLI Layer
    subgraph "Process & CLI Layer"
        N["Node.js Runtime"]:::runtime
        FTCL["fetchtv.js<br/>(Parser & Controllers)"]:::cli
        Pkg["package.json"]:::deploy
        Lock["package-lock.json"]:::deploy
        Rep["repomix.config.json"]:::deploy
    end

    %% Application Logic Layer
    subgraph "Application Logic Layer"
        CP["Command Parser<br/>(commander/yargs)"]:::cli
        Ctrl["Controllers"]:::cli
        DS["Discovery Service"]:::network
        FS["Fetch Service"]:::network
        TE["Template Engine"]:::ext
    end

    %% Persistence & I/O Layer
    subgraph "Persistence & I/O Layer"
        FSYS["File System Adapter"]:::io
        CO["Console Output Formatter"]:::io
    end

    %% External System
    E["Fetch TV Server"]:::external

    %% Deployment & CI/CD
    subgraph "Deployment & CI/CD"
        DK["Docker Build Context"]:::deploy
        DFile["Dockerfile"]:::deploy
        DI[".dockerignore"]:::deploy
        GH1["publish-docker.yml"]:::ci
        GH2["publish-npm.yml"]:::ci
    end

    %% Connections
    U -->|"enters command"| N
    N -->|"loads fetchtv.js"| FTCL
    FTCL -->|"parses"| CP
    CP -->|"invokes"| Ctrl
    Ctrl -->|"SSDP discovery"| DS
    DS -->|"response"| Ctrl
    Ctrl -->|"HTTP GET recordings"| FS
    FS -->|"TS stream"| FSYS
    FSYS -->|"write .ts file"| FSYS
    Ctrl -->|"apply template"| TE
    TE -->|"formatted paths"| FSYS
    Ctrl -->|"stdout JSON/text"| CO
    CO -->|"output"| U
    DS -->|"SSDP discovery"| E
    FS -->|"HTTP requests"| E

    DK -->|"build container"| FTCL
    GH1 -.->|"trigger"| DK
    GH2 -.->|"trigger"| Pkg

    %% Click Events
    click FTCL "https://github.com/furey/fetchtv/blob/main/fetchtv.js"
    click Pkg "https://github.com/furey/fetchtv/blob/main/package.json"
    click Lock "https://github.com/furey/fetchtv/blob/main/package-lock.json"
    click Rep "https://github.com/furey/fetchtv/blob/main/repomix.config.json"
    click DFile "https://github.com/furey/fetchtv/tree/main/Dockerfile"
    click DI "https://github.com/furey/fetchtv/blob/main/.dockerignore"
    click GH1 "https://github.com/furey/fetchtv/blob/main/.github/workflows/publish-docker.yml"
    click GH2 "https://github.com/furey/fetchtv/blob/main/.github/workflows/publish-npm.yml"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#004085
    classDef runtime fill:#cce7e8,stroke:#006759
    classDef network fill:#d4edda,stroke:#155724
    classDef io fill:#fff3cd,stroke:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d
    classDef deploy fill:#f5c6cb,stroke:#721c24
    classDef ci fill:#f8d7da,stroke:#721c24
    classDef ext fill:#e2e3e5,stroke:#6c757d
```
