# holepunchto/pear-radio architecture

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

- Interactive diagram: https://gitdiagram.com/holepunchto/pear-radio
- Repository: https://github.com/holepunchto/pear-radio

## Overview

##### Project Type and Purpose
- Pear Radio is primarily an audio player/streamer that lets users either stream their local music library or listen to streams over the network.
- It provides two main modes of operation: “streamer” mode (broadcasting music) and “listener” mode (playing the broadcast).
- The project also offers both a command-line interface (CLI) (installed globally via npm and executed with commands like “pear-radio stream” or “pear-radio listen”) and a browser-based interface (the presence of index.html, js/, and style.css).

##### Analyzing the File Structure
- Top-level files and directories:
- bin/ contains a Node module (index.mjs, package.json) which likely implements the CLI functionalities for starting the stream or listening.
- js/ with index.js, along with index.html and style.css, indicates that there’s a web front-end that may be used as an alternative interface or dashboard.
- assets/ likely contains static resource files (like a076d05399.js) used in the web interface.
- .github workflows show that there are CI setups for automated testing or deployment.
- Key configuration files such as package.json indicate Node.js usage.

##### Components

a. CLI/Backend Component (Streamer and Listener):
- CLI Interface: Represented by the executable commands (e.g., “pear run”, “pear-radio stream”, “pear-radio listen”). Illustrate this as the entry point when using the terminal.
- Streaming Engine: Within the CLI tool, there is a core module that handles the music streaming. This component is responsible for reading the local music library (for streamers), establishing a connection using Holepunch technology (for NAT traversal), and handling the audio data transfer.
- Connection Manager: Emphasize any networking layer (even if implicit) that manages the peer-to-peer connections, enabling a listener to connect to a streamer.

b. Web Frontend Component:
- Client UI: Represent the browser-based interface which consists of index.html, index.js, and style.css. This may function as a player or a dashboard to view streaming status.

c. Integration and Communication:

##### Architectural Patterns / Design Principles
- The separation between CLI and Web UI indicates a layering of presentation (front end) versus business logic (streaming engine).
- The project leverages modular design, with separate directories for static assets, CLI functionality, and client-side business logic.
- With potential use of peer-to-peer Holepunch techniques, emphasize external or custom networking services that manage NAT traversal and direct connections.

##### Relevant Technologies and Frameworks
- Node.js: Evident from the package.json files and JavaScript modules in bin/.
- Frontend Web Development: HTML, CSS, and JS directories contain the web view, likely used for rendering the streaming interface.
- Peer-to-Peer / Holepunch Logic: Though it is not elaborated on in the file structure, the README’s description signals a network layer that achieves direct connections between streamer and listener.

##### Final Advice
- Be as detailed as possible—don’t hesitate to separate the system into multiple components rather than lumping them together. Even if some connections are handled implicitly by the Node.js runtime or external libraries, showing these connections improves clarity.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "User Interfaces"
        CLI_Tool["CLI Tool (CLI Interface)"]:::frontend
        Web_Frontend["Web Frontend (Client UI)"]:::frontend
        index_html["index.html"]:::resource
        js_index["js/index.js"]:::resource
        style_css["style.css"]:::resource
        Asset_Loader["Asset Loader (Static Assets)"]:::resource
    end

    subgraph "Backend Processing"
        Streaming_Engine["Streaming Engine (Music Processing)"]:::backend
    end

    subgraph "Network and Communication"
        Connection_Manager["Connection Manager (P2P/Holepunch)"]:::network
    end

    CLI_Tool -->|"init_stream"| Streaming_Engine
    Streaming_Engine -->|"handles_NAT"| Connection_Manager
    Connection_Manager -->|"delivers_stream"| Web_Frontend

    index_html -->|"loads"| Web_Frontend
    js_index -->|"loads"| Web_Frontend
    style_css -->|"loads"| Web_Frontend
    Asset_Loader -->|"provides_assets"| Web_Frontend

    click CLI_Tool "https://github.com/holepunchto/pear-radio/blob/main/bin/index.mjs"
    click Streaming_Engine "https://github.com/holepunchto/pear-radio/tree/main/bin/"
    click Connection_Manager "https://github.com/holepunchto/pear-radio/tree/main/bin/"
    click index_html "https://github.com/holepunchto/pear-radio/blob/main/index.html"
    click js_index "https://github.com/holepunchto/pear-radio/blob/main/js/index.js"
    click style_css "https://github.com/holepunchto/pear-radio/blob/main/style.css"
    click Asset_Loader "https://github.com/holepunchto/pear-radio/tree/main/assets/"

    classDef frontend fill:#B3E5FC,stroke:#0288D1,stroke-width:2px;
    classDef backend fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef network fill:#FFECB3,stroke:#F9A825,stroke-width:2px;
    classDef resource fill:#F8BBD0,stroke:#C2185B,stroke-width:2px;
```
