# sentriz/gonic architecture

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

- Interactive diagram: https://gitdiagram.com/sentriz/gonic
- Repository: https://github.com/sentriz/gonic

## Overview

##### Main Components Identification

The system should be represented with these key components:

a) Core Server Components:
- HTTP Server Layer (handles both admin and Subsonic API endpoints)
- Scanner Service (music file scanning and monitoring)
- Transcoding Service (audio format conversion)
- Jukebox Service (server-side playback)
- Database Layer (SQLite storage)

b) External Services Integration:
- Last.fm API Integration
- ListenBrainz Integration
- TagLib Integration (for audio metadata)
- FFmpeg Integration (for transcoding)

##### Component Relationships

**[Music Files Storage] → [Scanner Service] → [Database]**
- ↓
**[HTTP Server] → [Router] → [Admin Controller]**
- ↘ [Subsonic API Controller] → [Transcoding Service]
- → [Jukebox Service]
- → [Playlist Manager]
- → [Podcast Manager]
- ↓
**[External Services] ← [Integration Layer] ← [Scrobbling Service]**

##### Specific Implementation Details

Key architectural elements:
- File system watchers for real-time music updates
- Cache management for transcoded files
- Multi-user support with separate configurations
- Multiple music folder support with aliasing
- Plugin-style architecture for transcoding backends

##### Technical Stack Indicators

Highlight:
- Go as the primary language
- SQLite as the database
- TagLib for metadata parsing
- FFmpeg for transcoding
- MPV for jukebox functionality

##### Configuration Components

Show:
- Environment variable configuration
- Command-line arguments
- File-based configuration
- Admin UI configuration interface

- Clear separation between API implementations (Subsonic vs Admin)
- Pluggable external service integrations
- Flexible file system handling
- Caching and optimization mechanisms

This architecture reflects Gonic's design as a lightweight but feature-rich music streaming server with emphasis on compatibility and performance.

## Diagram (Mermaid)

```mermaid
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '16px'}}}%%
flowchart TB
    subgraph Core["Core Server Components"]
        direction TB
        HTTP[HTTP Server Layer]
        Router[Router Layer]
        AdminCtrl[Admin Controller]
        SubsonicCtrl[Subsonic API Controller]
        Scanner[Scanner Service]
        Trans[Transcoding Service]
        Juke[Jukebox Service]
        DB[(Database Layer)]
        Cache[Cache Management]
        FSUtil[File System Utilities]
        Playlist[Playlist Manager]
        Podcast[Podcast Manager]
        Scrobble[Scrobbling Service]
    end

    subgraph External["External Integrations"]
        direction TB
        LastFM[Last.fm API]
        ListenBrainz[ListenBrainz API]
        TagLib[TagLib Integration]
        FFmpeg[FFmpeg Integration]
    end

    subgraph UI["User Interfaces"]
        direction TB
        AdminUI[Admin UI]
        APIEndpoints[API Endpoints]
    end

    %% Core Component Relationships
    HTTP --> Router
    Router --> AdminCtrl
    Router --> SubsonicCtrl
    Scanner --> DB
    SubsonicCtrl --> Trans
    SubsonicCtrl --> Juke
    SubsonicCtrl --> Playlist
    SubsonicCtrl --> Podcast
    SubsonicCtrl --> Scrobble

    %% External Integration Relationships
    Scrobble --> LastFM
    Scrobble --> ListenBrainz
    Scanner --> TagLib
    Trans --> FFmpeg

    %% UI Relationships
    AdminCtrl --> AdminUI
    SubsonicCtrl --> APIEndpoints

    %% Storage and Cache
    Cache --> Trans
    FSUtil --> Scanner

    %% Click Events
    click HTTP "https://github.com/sentriz/gonic/tree/master/server"
    click Scanner "https://github.com/sentriz/gonic/blob/master/scanner/scanner.go"
    click Trans "https://github.com/sentriz/gonic/blob/master/transcode/transcode.go"
    click Juke "https://github.com/sentriz/gonic/blob/master/jukebox/jukebox.go"
    click DB "https://github.com/sentriz/gonic/blob/master/db/db.go"
    click LastFM "https://github.com/sentriz/gonic/blob/master/lastfm/client.go"
    click ListenBrainz "https://github.com/sentriz/gonic/blob/master/listenbrainz/listenbrainz.go"
    click TagLib "https://github.com/sentriz/gonic/blob/master/tags/taglib/taglib.go"
    click FFmpeg "https://github.com/sentriz/gonic/blob/master/transcode/transcoder_ffmpeg.go"
    click AdminCtrl "https://github.com/sentriz/gonic/blob/master/server/ctrladmin/ctrl.go"
    click SubsonicCtrl "https://github.com/sentriz/gonic/blob/master/server/ctrlsubsonic/ctrl.go"
    click Playlist "https://github.com/sentriz/gonic/blob/master/playlist/playlist.go"
    click Podcast "https://github.com/sentriz/gonic/blob/master/podcast/podcast.go"
    click Cache "https://github.com/sentriz/gonic/blob/master/infocache/albuminfocache/albuminfocache.go"
    click AdminUI "https://github.com/sentriz/gonic/tree/master/server/ctrladmin/adminui"
    click FSUtil "https://github.com/sentriz/gonic/blob/master/fileutil/fileutil.go"
    click Scrobble "https://github.com/sentriz/gonic/blob/master/scrobble/scrobble.go"

    %% Styling
    classDef core fill:#a8d1ff,stroke:#2270c1
    classDef external fill:#ffd7a8,stroke:#c17022
    classDef ui fill:#d7ffa8,stroke:#70c122
    
    class HTTP,Router,AdminCtrl,SubsonicCtrl,Scanner,Trans,Juke,DB,Cache,FSUtil,Playlist,Podcast,Scrobble core
    class LastFM,ListenBrainz,TagLib,FFmpeg external
    class AdminUI,APIEndpoints ui
```
