# holepunchto/pear-radio-backend architecture

> Architecture diagram of the GitHub repository holepunchto/pear-radio-backend, 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-backend
- Repository: https://github.com/holepunchto/pear-radio-backend

## Overview

##### Main Components
- User API Module – Handles user information retrieval and sync requests. (Defined in lib/user.js; used to get public key, name, description, and tags.)
- Listener Component – Manages receiving streams from remote users/streamers. (Defined in lib/listener.js)
- Streamer Component – Handles audio data streaming alongside metadata. (Defined in lib/streamer.js)
- MP3 Read Utilities – Offers methods to read MP3 files and extract ID3 tags, providing local and remote streams. (Defined in lib/mp3-read-stream.js)
- HTTP Audio Streamer – Exposes an HTTP server to serve audio streams for local consumption. (Defined in lib/http-audio-streamer.js)
- PearRadioConfiguration – Provides a Hyperbee-backed configuration store for user information. (Defined in lib/config.js, possibly via PearRadioConfiguration abstraction)
- TagManager – Uses Hyperswarm to enable tag-based discovery of users/streamers. (Defined in lib/tag-manager.js)

##### Understand the Interaction/Relationships
- The User component is foundational—it exposes methods for retrieving user/streamer info and synchronizing playback details.
- The Listener and Streamer are complementary: while the Streamer pushes audio and metadata outward, the Listener receives and processes incoming audio streams starting from a specified block (each block representing roughly one second of audio).
- The MP3 Read Stream module is a utility leveraged by the HTTP Audio Streamer to convert MP3 files into streams and extract track metadata.
- The HTTP Audio Streamer acts as a bridge to expose MP3 streams on a local HTTP server.
- The Configuration component serves as a central persistent store for Pear Radio user information, ensuring that user details are stored and retrievable.
- The TagManager leverages Hyperswarm to facilitate a decentralized mechanism for discovery; it announces itself on a common tag channel (the “#all” topic) and listens for incoming connections/searches.

##### Architectural Patterns & Design Principles
- Modularity: Each functional unit is encapsulated in its own module within the lib folder, ensuring separation of concerns.
- Asynchronous operations: The use of async/await (as shown in API examples) implies that the system is built around non-blocking, event-driven patterns.
- Service-oriented components: While not microservices per se, each component (user, listener, streamer, etc.) is designed as an independent, interoperable service.
- Testability: The dedicated tests in the tests directory for each component underscore a commitment to unit testing and quality assurance.

##### Tech Stack & Dependencies
- Node.js environment, evident from the package.json and JavaScript module patterns.
- Hyperbee for configuration storage, Hyperswarm for decentralized connectivity, and Node.js streams for handling audio.
- Likely uses standard Node.js libraries for reading files (fs) and handling HTTP requests (possibly via an embedded server implementation in HttpAudioStreamer).

## Diagram (Mermaid)

```mermaid
graph TD
    %% User and Configuration Layer
    subgraph "User and Configuration Layer"
        UserApi["User API Module"] 
        Configuration["PearRadioConfiguration"]
    end

    %% Streaming Modules
    subgraph "Streaming Modules"
        Listener["Listener Component"]
        Streamer["Streamer Component"]
        MP3ReadStream["MP3 Read Utilities"]
        HTTPAudioStreamer["HTTP Audio Streamer"]
    end

    %% Discovery Layer
    subgraph "Discovery Layer"
        TagManager["TagManager"]
    end

    %% External Systems
    AudioClient["Audio Client"]
    Hyperswarm["Hyperswarm Network"]

    %% Connections
    UserApi -->|"syncRequest"| Listener
    UserApi -->|"syncRequest"| Streamer
    UserApi -->|"configLookup"| Configuration
    Streamer -->|"extractMetadata"| MP3ReadStream
    MP3ReadStream -->|"readTrack"| HTTPAudioStreamer
    HTTPAudioStreamer -->|"serveAudio"| AudioClient
    TagManager -->|"discoverPeers"| UserApi
    TagManager -->|"connect"| Hyperswarm

    %% Classes
    classDef userConfig fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef streaming fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef discovery fill:#f08080,stroke:#000,stroke-width:2px;
    classDef external fill:#ffe4b5,stroke:#000,stroke-width:2px;

    class UserApi,Configuration userConfig;
    class Listener,Streamer,MP3ReadStream,HTTPAudioStreamer streaming;
    class TagManager discovery;
    class AudioClient,Hyperswarm external;

    %% Click Events
    click UserApi "https://github.com/holepunchto/pear-radio-backend/blob/main/lib/user.js"
    click Listener "https://github.com/holepunchto/pear-radio-backend/blob/main/lib/listener.js"
    click Streamer "https://github.com/holepunchto/pear-radio-backend/blob/main/lib/streamer.js"
    click MP3ReadStream "https://github.com/holepunchto/pear-radio-backend/blob/main/lib/mp3-read-stream.js"
    click HTTPAudioStreamer "https://github.com/holepunchto/pear-radio-backend/blob/main/lib/http-audio-streamer.js"
    click Configuration "https://github.com/holepunchto/pear-radio-backend/blob/main/lib/config.js"
    click TagManager "https://github.com/holepunchto/pear-radio-backend/blob/main/lib/tag-manager.js"
```
