# stefodev/cliflix-cache architecture

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

- Interactive diagram: https://gitdiagram.com/stefodev/cliflix-cache
- Repository: https://github.com/stefodev/cliflix-cache

## Overview

##### Project type and purpose
- CLIFlix is a command‐line interface (CLI) tool written in TypeScript/Node.js.
- Its purpose is to let users search for a torrent by name, stream it via WebTorrent, and launch it in a local media player (e.g., VLC, mpv), optionally fetching subtitles.

##### File structure
Top‐level files and folders
- package.json, tsconfig.json – Node/TypeScript config and dependencies
- src/bin/index.ts – CLI entry point (npm “bin” target)
- src/cli.ts – Argument parsing & command dispatch (wizard, “lucky”, manual)
- src/config.ts – Loads and validates ~/.cliflix.json, merges defaults
- src/index.ts – Core orchestrator: ties search, torrent, subtitles, player
- src/utils.ts – Shared helpers (e.g., path resolution, logging)
- src/temp.ts – Manages temporary download directory or cleanup
- resources/ – Contains assets like the wizard.gif for README
- .gitignore, .editorconfig, LICENSE, README.md, .todo

##### README for additional insights
- Describes three usage modes: interactive wizard, “I’m feeling lucky” (first result), and manual streaming with a magnet URI.
- Configuration sections show how the user can customize downloads path, torrent providers, subtitle languages, WebTorrent flags, and preferred output apps.
- Relies on external libraries: WebTorrent (torrent streaming), parse-torrent (magnet parsing), OpenSubtitles API (subtitle search), child_process (to launch media players).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Modules
    subgraph "Internal Modules"
        CLI_Entry["CLI Entry (src/bin/index.ts)"]:::internal
        Arg_Parser["Arg Parser (src/cli.ts)"]:::internal
        Config_Manager["Config Manager (src/config.ts)"]:::config
        Torrent_Search["Torrent Search Module"]:::internal
        Subtitle_Search["Subtitle Search Module"]:::internal
        WebTorrent_Client["WebTorrent Client"]:::internal
        Player_Launcher["Player Launcher"]:::internal
        Temp_Storage["Temp Storage Manager (src/temp.ts)"]:::fs
        Shared_Utils["Shared Utilities (src/utils.ts)"]:::internal
    end

    %% External Services
    subgraph "External Services"
        Providers["Torrent Providers"]:::external
        Subtitles_API["OpenSubtitles API"]:::external
    end

    %% Project Files
    subgraph "Project Files"
        Assets["Assets/Resources (resources/)"]:::fs
        Package["package.json"]:::config
        TSConfig["tsconfig.json"]:::config
    end

    %% User Interaction
    User["User"]:::external
    User -->|runs CLI| CLI_Entry
    CLI_Entry -->|invokes| Arg_Parser
    Arg_Parser -->|loads| Config_Manager
    Arg_Parser -->|search query| Torrent_Search
    Torrent_Search -->|HTTP requests| Providers
    Arg_Parser -->|select torrent| WebTorrent_Client
    Arg_Parser -->|optionally fetch subtitles| Subtitle_Search
    Subtitle_Search -->|API requests| Subtitles_API
    WebTorrent_Client -->|streams to| Temp_Storage
    WebTorrent_Client -->|provides stream| Player_Launcher
    Subtitle_Search -->|sends subtitles| Player_Launcher
    Shared_Utils -.->|helpers| CLI_Entry
    Shared_Utils -.->|helpers| Arg_Parser
    Shared_Utils -.->|helpers| Config_Manager
    Shared_Utils -.->|helpers| Torrent_Search
    Shared_Utils -.->|helpers| Subtitle_Search
    Shared_Utils -.->|helpers| WebTorrent_Client
    Shared_Utils -.->|helpers| Player_Launcher
    Shared_Utils -.->|helpers| Temp_Storage

    %% Project Files Relations
    Assets -.->|used in README| CLI_Entry
    Package -.->|defines deps| CLI_Entry
    TSConfig -.->|compiles| CLI_Entry

    %% Click Events
    click CLI_Entry "https://github.com/stefodev/cliflix-cache/blob/master/src/bin/index.ts"
    click Arg_Parser "https://github.com/stefodev/cliflix-cache/blob/master/src/cli.ts"
    click Config_Manager "https://github.com/stefodev/cliflix-cache/blob/master/src/config.ts"
    click Torrent_Search "https://github.com/stefodev/cliflix-cache/blob/master/src/index.ts"
    click Subtitle_Search "https://github.com/stefodev/cliflix-cache/blob/master/src/index.ts"
    click WebTorrent_Client "https://github.com/stefodev/cliflix-cache/blob/master/src/index.ts"
    click Player_Launcher "https://github.com/stefodev/cliflix-cache/blob/master/src/index.ts"
    click Temp_Storage "https://github.com/stefodev/cliflix-cache/blob/master/src/temp.ts"
    click Shared_Utils "https://github.com/stefodev/cliflix-cache/blob/master/src/utils.ts"
    click Assets "https://github.com/stefodev/cliflix-cache/tree/master/resources/"
    click Package "https://github.com/stefodev/cliflix-cache/blob/master/package.json"
    click TSConfig "https://github.com/stefodev/cliflix-cache/blob/master/tsconfig.json"

    %% Styles
    classDef internal fill:#E0F7FA,stroke:#0288D1,stroke-width:1px
    classDef external fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px
    classDef fs fill:#F5F5F5,stroke:#9E9E9E,stroke-width:1px
    classDef config fill:#FFF3E0,stroke:#FFA000,stroke-width:1px
```
