# swoogan/jbox architecture

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

- Interactive diagram: https://gitdiagram.com/swoogan/jbox
- Repository: https://github.com/swoogan/jbox

## Overview

##### Project type and purpose
- JBox is a full-stack web application: a remote MP3 jukebox server.
- The Python backend (CherryPy) provides HTTP and WebSocket APIs; the Angular/HTML/JS frontend (“site” directory) is the client UI.

##### File structure
- Top-level:
- jbox/ – Python application package
- jbox/core – core domain logic (configuration, JSON file I/O, song database, volume control)
- jbox/player – playback abstraction (song list, player wrapper)
- jbox/services – HTTP/WebSocket service layer (applications, controls, directories, mp3scan, nowplaying, songs, state, volume)
- jbox.py – CherryPy server entry point
- websocket.py & volume_thread.py – background threads for WS and volume polling
- site/ – static frontend: HTML, CSS, JS, Angular components, Gulp build, Bower dependencies
- songs.json – local song metadata store
- jbox.conf & requirements.txt – configuration & Python dependencies
- Recognize MVC-style layering:
- Model/Core (jbox/core)
- Controller/Services (jbox/services + jbox.py entry)
- View/Frontend (site/)

##### Extract insights from README
- Uses CherryPy, ws4py (WebSocket), Mutagen (MP3 metadata), vlc module (playback), amixer (Linux mixer).
- User flow: configure app locations → add directories → scan MP3 files → control playback via web UI.

##### Main components & interactions
a. Components:
1. Web Browser (Angular SPA)
2. CherryPy HTTP API
3. CherryPy WebSocket endpoint
4. Service Layer (jbox/services modules)
5. Core Engine (jbox/core modules)
6. Player Layer (jbox/player + VLC Python bindings)
7. songs.json (song metadata store)
8. Local filesystem (MP3 directories)
9. System mixer (amixer)
10. Volume thread
b. Data flows & interactions:
- Browser ⇄ HTTP API: REST calls to /applications, /directories, /songs, /state
- Browser ⇄ WebSocket: real-time updates (now playing, volume changes)
- HTTP API → Service Layer → Core Engine → songs.json / filesystem / VLC
- Core Engine triggers Player Layer for play/pause/skip via VLC
- Volume Thread polls ALSA mixer (amixer) and pushes updates via WebSocket
c. Architectural patterns:
- Layered (Controller → Service → Core → Infrastructure)
- Event-driven (WebSocket push for real-time)
- Modular services (one service module per resource)
d. Key technologies:
- Python 3 + CherryPy + ws4py + Mutagen + python-vlc
- AngularJS + Bower + Gulp on frontend
- JSON file store (songs.json)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph "Client (Angular SPA)" 
        direction TB
        Browser["Web Browser (Angular SPA)"]:::frontend
        AngularComponents["Angular Components (routes, services)"]:::frontend
        ApplicationsView["Application Views & Controllers"]:::frontend
        DirectoriesView["Directory Views & Controllers"]:::frontend
        MP3ScanView["MP3 Scan View"]:::frontend
        PlayerView["Player View & Controller"]:::frontend
        ConfigView["Configuration View & Controller"]:::frontend
        MainShell["Main Shell & Assets"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        HTTPAPI["CherryPy HTTP API"]:::server
        WS["CherryPy WebSocket Endpoint"]:::server
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        AppService["Applications Service"]:::server
        CtrlService["Controls Service"]:::server
        DirService["Directories Service"]:::server
        MP3ScanService["MP3 Scan Service"]:::server
        NowPlayingService["Now Playing Service"]:::server
        SongsService["Songs Service"]:::server
        StateService["State Service"]:::server
        VolumeService["Volume Service"]:::server
    end

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        CoreConfig["Configuration"]:::server
        CoreJSON["JSON File I/O"]:::server
        CoreSongDB["Song Database"]:::server
        CoreVolumeLogic["Volume Logic"]:::server
    end

    %% Player Layer
    subgraph "Player Layer"
        direction TB
        PlayerWrapper["Player Wrapper"]:::server
        SongList["Song List Abstraction"]:::server
    end

    %% Volume Thread
    VolumeThread["Volume Polling Thread"]:::server

    %% Data Stores & External
    DB[(songs.json)]:::data
    FileSystem["Local File System (MP3 dirs)"]:::external
    VLC["VLC (python-vlc)"]:::external
    AMixer["ALSA Mixer (amixer)"]:::external
    Mutagen["Mutagen (MP3 metadata)"]:::external

    %% Connections
    Browser -->|REST API Calls| HTTPAPI
    Browser -->|WS Connect| WS
    AngularComponents --> Browser
    ApplicationsView --> AngularComponents
    DirectoriesView --> AngularComponents
    MP3ScanView --> AngularComponents
    PlayerView --> AngularComponents
    ConfigView --> AngularComponents
    MainShell --> Browser

    HTTPAPI -->|routes to| AppService
    HTTPAPI --> CtrlService
    HTTPAPI --> DirService
    HTTPAPI --> MP3ScanService
    HTTPAPI --> NowPlayingService
    HTTPAPI --> SongsService
    HTTPAPI --> StateService
    HTTPAPI --> VolumeService

    WS -->|push events| NowPlayingService
    VolumeThread -->|push volume updates| WS

    AppService --> CoreConfig
    CtrlService --> CoreSongDB
    DirService --> CoreJSON
    MP3ScanService --> CoreSongDB
    MP3ScanService --> Mutagen
    NowPlayingService --> CoreSongDB
    SongsService --> CoreSongDB
    StateService --> CoreVolumeLogic
    VolumeService --> CoreVolumeLogic

    CoreConfig --> CoreJSON
    CoreJSON --> DB
    CoreSongDB --> DB
    CoreSongDB --> FileSystem
    CoreVolumeLogic --> AMixer

    PlayerWrapper --> VLC
    SongList --> CoreSongDB
    PlayerWrapper --> SongList

    %% Click Events
    click Browser "https://github.com/swoogan/jbox/tree/master/site/"
    click AngularComponents "https://github.com/swoogan/jbox/tree/master/site/components/"
    click ApplicationsView "https://github.com/swoogan/jbox/tree/master/site/applications/"
    click DirectoriesView "https://github.com/swoogan/jbox/tree/master/site/directories/"
    click MP3ScanView "https://github.com/swoogan/jbox/tree/master/site/mp3scan/"
    click PlayerView "https://github.com/swoogan/jbox/tree/master/site/player/"
    click ConfigView "https://github.com/swoogan/jbox/tree/master/site/config/"
    click MainShell "https://github.com/swoogan/jbox/blob/master/site/index.html"
    click HTTPAPI "https://github.com/swoogan/jbox/blob/master/jbox.py"
    click WS "https://github.com/swoogan/jbox/blob/master/jbox/websocket.py"
    click VolumeThread "https://github.com/swoogan/jbox/blob/master/jbox/volume_thread.py"
    click AppService "https://github.com/swoogan/jbox/blob/master/jbox/services/applications.py"
    click CtrlService "https://github.com/swoogan/jbox/blob/master/jbox/services/controls.py"
    click DirService "https://github.com/swoogan/jbox/blob/master/jbox/services/directories.py"
    click MP3ScanService "https://github.com/swoogan/jbox/blob/master/jbox/services/mp3scan.py"
    click NowPlayingService "https://github.com/swoogan/jbox/blob/master/jbox/services/nowplaying.py"
    click SongsService "https://github.com/swoogan/jbox/blob/master/jbox/services/songs.py"
    click StateService "https://github.com/swoogan/jbox/blob/master/jbox/services/state.py"
    click VolumeService "https://github.com/swoogan/jbox/blob/master/jbox/services/volume.py"
    click CoreConfig "https://github.com/swoogan/jbox/blob/master/jbox/core/config.py"
    click CoreJSON "https://github.com/swoogan/jbox/blob/master/jbox/core/jsonfile.py"
    click CoreSongDB "https://github.com/swoogan/jbox/blob/master/jbox/core/songdb.py"
    click CoreVolumeLogic "https://github.com/swoogan/jbox/blob/master/jbox/core/volume.py"
    click PlayerWrapper "https://github.com/swoogan/jbox/blob/master/jbox/player/player.py"
    click SongList "https://github.com/swoogan/jbox/blob/master/jbox/player/songlist.py"
    click DB "https://github.com/swoogan/jbox/blob/master/songs.json"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:1px
    classDef server fill:#90ee90,stroke:#000,stroke-width:1px
    classDef external fill:#ffcc99,stroke:#000,stroke-width:1px
    classDef data fill:#ffe4b5,stroke:#000,stroke-width:1px
```
