# vicwomg/pikaraoke architecture

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

- Interactive diagram: https://gitdiagram.com/vicwomg/pikaraoke
- Repository: https://github.com/vicwomg/pikaraoke

## Overview

Based on our analysis of the provided file tree and README, this project is a Python-based web application called “Pikaraoke” that provides a full-stack solution for a KTV-style karaoke system. It includes a web server (with multiple route endpoints for functions like song searching, queuing, administration, etc.), multimedia playback controls, integration with external services (such as FFmpeg for media processing, YouTube download, VLC or OMX client for playback, and potential automation with Selenium), as well as static assets for the UI (templates, CSS, JavaScript). It also supports deployment through Docker and is tailored to run on multiple environments (e.g., Raspberry Pi, Windows, OSX, Linux).

##### Main Components
- Web Frontend & Client Interface:
– Represents the web-based UI accessed via smartphones, computers, and TVs.
– Includes assets served from the “pikaraoke/templates” and “pikaraoke/static” directories.
– Connection access is enabled via QR code display for quick client joining.
- Application Server / Backend:
– The Python server (main app file: “pikaraoke/app.py”) that handles incoming HTTP requests.
– Contains multiple route modules (found in “pikaraoke/routes”) covering functionalities such as home page, search, admin, queue management, file browsing, etc.
- Service/Logic Layer:
– Python modules under “pikaraoke/lib” that encapsulate distinct business logic, such as managing FFmpeg interactions (ffmpeg.py), VLC/OMX client communication, file resolution, current application context, and others.
– These modules handle tasks like interfacing with multimedia components (transcoding, playback, and track retrieval) and integrating with external systems like YouTube (via youtube_dl.py) and Chrome for headless operations.
- Translation & Internationalization:
– Managed under “pikaraoke/translations” with various language directories. This component ensures the UI can support multiple languages using Babel configuration.
- Static Assets Management:
– CSS, JavaScript, images, fonts in “pikaraoke/static” to support theming (e.g., dark mode styling with bulma-dark.css) and interactive functionality on the front end.
- External Integrations & Deployment:
– Docker and related deployment configurations (Dockerfile, docker-compose examples) for containerized deployment.
– CI/CD workflows (within .github/workflows) and code quality tools (found in the “code_quality” directory) indicate automated testing and style checks that support the development lifecycle.

##### Relationships and Interactions
- Users access the system via their browsers or devices. Their requests hit the Web Server, which is responsible for rendering HTML templates.
- The web server routes requests (via endpoints defined in “pikaraoke/routes”) to the backend logic.
- The backend delegates tasks to service modules (in “pikaraoke/lib”), such as invoking FFmpeg operations, controlling media players (VLC, OMX), or downloading content via YouTube DL.
- All user interactions may trigger updates in the song queue and playback controls, which are then reflected back on the front-end interface.
- The translation modules interact with the templates to localize text and messages.
- Docker and deployment scripts containerize the whole application, ensuring that dependencies such as FFmpeg, Chrome, or Chromium are appropriately managed.
- Continuous integration pipelines ensure code quality and smooth release processes.

##### Notable Architectural Patterns & Design Principles
- Modular design: The separation into “routes”, “lib”, and “static/templates” folders suggests a clear separation of concerns, following web MVC-like patterns.
- Service abstraction: Media playback and external communications are abstracted inside dedicated modules (e.g., ffmpeg.py, vlcclient.py), enhancing maintainability.
- Extensibility & configuration: Localization and customizable UI through themes indicate a design that accommodates varied user preferences.

##### Technologies and Frameworks
- Python 3.9+, dependency and environment management (Poetry).
- Web technologies (HTML, CSS, JavaScript) for the front end.
- External tools: FFmpeg for media processing, VLC/OMX for playback, Selenium for browser control, and youtube_dl for fetching videos.
- Docker for containerized deployment and CI/CD integration through GitHub Workflows.

- Application Server in the middle, subdividing it into route controllers and business logic modules (as per the “routes” and “lib” directories).
- Static/web assets branch feeding into the UI rendering.
- Layer below the core logic the external multimedia processing dependencies (FFmpeg, VLC/OMX, Selenium, youtube_dl) and note how these interact with the logic modules.
- Localization as a cross-cutting concern that interfaces with the UI layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface Layer"
        A["Web Client (Smartphone/Desktop)"]:::client
    end

    subgraph "Presentation Layer"
        B["Templates (UI)"]:::asset
        C["Static Assets (UI)"]:::asset
    end

    subgraph "Application Server"
        D["Main Application (pikaraoke/app.py)"]:::backend
        E["Route Handlers (pikaraoke/routes)"]:::backend
        F["Service Modules (Media Processing)"]:::service
        D -->|"handles"| E
        E -->|"delegates"| F
        F -->|"returns"| D
    end

    subgraph "Translation & Internationalization"
        G["Translations"]:::translation
        H["Babel Config"]:::translation
    end

    subgraph "Deployment & Integrations"
        I["Docker Configurations"]:::deploy
        J["Docker Compose Example"]:::deploy
        K["Build Script"]:::deploy
        L["CI/CD Pipelines"]:::deploy
        M["Code Quality Tools"]:::deploy
    end

    A -->|"HTTP_request"| D
    D -->|"renders"| B
    D -->|"serves"| C
    D -->|"integrates"| G
    D -->|"integrates"| H
    G -->|"localizes"| B
    H -->|"configures"| B
    I -.->|"containers"| D
    J -.-> I
    K -.-> I
    L -.-> I
    M -.-> I

    classDef client fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef asset fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef service fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef translation fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef deploy fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;

    click B "https://github.com/vicwomg/pikaraoke/tree/master/pikaraoke/templates"
    click C "https://github.com/vicwomg/pikaraoke/tree/master/pikaraoke/static"
    click D "https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/app.py"
    click E "https://github.com/vicwomg/pikaraoke/tree/master/pikaraoke/routes"
    click F "https://github.com/vicwomg/pikaraoke/tree/master/pikaraoke/lib"
    click G "https://github.com/vicwomg/pikaraoke/tree/master/pikaraoke/translations"
    click H "https://github.com/vicwomg/pikaraoke/blob/master/pikaraoke/babel.cfg"
    click I "https://github.com/vicwomg/pikaraoke/tree/master/Dockerfile"
    click J "https://github.com/vicwomg/pikaraoke/blob/master/docker/docker-compose.yml.example"
    click K "https://github.com/vicwomg/pikaraoke/blob/master/docker/build_arm64_amd64.sh"
    click L "https://github.com/vicwomg/pikaraoke/tree/master/.github/workflows"
    click M "https://github.com/vicwomg/pikaraoke/tree/master/code_quality"
```
