# mathenz/goffy architecture

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

- Interactive diagram: https://gitdiagram.com/mathenz/goffy
- Repository: https://github.com/mathenz/goffy

## Overview

##### Main Components
- CLI/Entry Point: Represented by main.go, which handles command-line argument parsing and serves as the application’s entry point.
- Spotify URL Handler: With functionality likely encapsulated in spotify.go, this component parses Spotify URLs and determines whether a playlist, album, track, or multiple tracks (from a text file) are requested.
- YouTube Download Module: Found in youtube.go, this part is responsible for locating and downloading the actual music content from YouTube.
- Download Orchestration: The downloader.go and template.go files manage the download process. They likely coordinate between parsing, fetching media from YouTube, formatting outputs, and integrating metadata.
- Utility Functions: utils.go contains supportive routines and helper functions that facilitate processing across the modules.
- Configuration & Release Configurations: The presence of .goreleaser.yaml (along with go.mod and go.sum) indicates build/release procedures important for distribution, though these are more peripheral to runtime architecture.

##### Relationships and Interactions
- User Input flows into the CLI component (main.go) where the command-line arguments (like -p, -a, -t, -f, -m, and -d options) are parsed.
- The appropriate download flow is then triggered:
- For a track/album/playlist, the downloader logic (downloader.go) orchestrates the process.
- It calls the YouTube Download Module (youtube.go) to query for matching content on YouTube.
- Downloaded content is then processed (possibly involving metadata addition via FFmpeg) and saved:
- Either directly to a local directory (using the provided -d flag) or...
- Temporarily stored and compressed for mobile device transfer (triggered by the -m flag), with a temporary HTTP server hosting the files on port 8080.
- Utility functions (from utils.go) support parsing, error-handling, logging, or any repeated tasks throughout these components.

##### Architectural Patterns and Technologies
- Modular design: The project cleanly separates concerns by dividing tasks among distinct modules (CLI, URL parsing, downloading, utility functions).
- Command-line interface design: The tool’s design emphasizes handling several command-line options that dictate control flow.
- External dependencies: The README notes the need for FFmpeg (for metadata processing), indicating an external service integration.
- Lightweight, no-official API approach: Despite dealing with Spotify URLs, the project avoids official APIs, instead using its own “unofficial API” logic.
- Temporary Web Server: An interesting design element is the mobile mode, which temporarily serves the downloaded content via an HTTP endpoint to facilitate mobile device access.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Peripheral Nodes
    User["User (Command-line Input)"]:::user
    LocalStorage["Local Storage (Local Directory)"]:::storage
    Mobile["Mobile Delivery (Temp HTTP Server)"]:::storage
    FFmpeg["FFmpeg (External)"]:::external
    BuildConfig["Build/Release Config (.goreleaser.yaml, go.mod, go.sum)"]:::config
    Examples["Example Usage (examples)"]:::config

    %% Application Core Subgraph
    subgraph "Application Core"
        CLI["CLI / Main (main.go)"]:::cli
        Spotify["Spotify URL Handler (spotify.go)"]:::handler
        %% Download Orchestration Split into two parts for clarity
        DM1["Download Orchestration: Downloader (downloader.go)"]:::manager
        DM2["Download Orchestration: Template (template.go)"]:::manager
        YT["YouTube Downloader (youtube.go)"]:::downloader
        Utils["Utility Functions (utils.go)"]:::utility
    end

    %% Data Flow Connections
    User -->|"Provides Command-line Args"| CLI
    CLI -->|"Parses Input"| Spotify
    Spotify -->|"Determines Content Type"| DM1
    DM1 -->|"Coordinates Orchestration"| DM2
    DM2 -->|"Requests Download"| YT
    YT -->|"Returns Media"| DM2
    DM2 -->|"Saves File"| LocalStorage
    DM2 -->|"Triggers-MobileMode"| Mobile
    DM2 -->|"Processes-Metadata"| FFmpeg

    %% Utility support (dashed lines)
    Utils -.->|"Supports CLI"| CLI
    Utils -.->|"Supports URL Parsing"| Spotify
    Utils -.->|"Supports Download Flow"| DM1
    Utils -.->|"Supports Orchestration"| DM2
    Utils -.->|"Supports Downloading"| YT

    %% Peripheral Associations (dashed lines)
    BuildConfig -.->|"Used-for-Build"| CLI
    Examples -.->|"Demonstrates-Usage"| CLI

    %% Click Events
    click CLI "https://github.com/mathenz/goffy/blob/main/main.go"
    click Spotify "https://github.com/mathenz/goffy/blob/main/spotify.go"
    click DM1 "https://github.com/mathenz/goffy/blob/main/downloader.go"
    click DM2 "https://github.com/mathenz/goffy/blob/main/template.go"
    click YT "https://github.com/mathenz/goffy/blob/main/youtube.go"
    click Utils "https://github.com/mathenz/goffy/blob/main/utils.go"
    click BuildConfig "https://github.com/mathenz/goffy/blob/main/.goreleaser.yaml"
    click Examples "https://github.com/mathenz/goffy/tree/main/examples"

    %% Styles
    classDef user fill:#fce3a4,stroke:#b57200,stroke-width:2px;
    classDef cli fill:#c2f0fc,stroke:#01919b,stroke-width:2px;
    classDef handler fill:#d7fdd7,stroke:#119911,stroke-width:2px;
    classDef manager fill:#fdd7d7,stroke:#b51111,stroke-width:2px;
    classDef downloader fill:#d7cdfd,stroke:#6622aa,stroke-width:2px;
    classDef utility fill:#fff2cc,stroke:#b58900,stroke-width:2px;
    classDef storage fill:#ffefdb,stroke:#e67e22,stroke-width:2px;
    classDef external fill:#ead1dc,stroke:#d33682,stroke-width:2px;
    classDef config fill:#dbe9f6,stroke:#3572b0,stroke-width:2px;
```
