# blackblazent/blackmusic architecture

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

- Interactive diagram: https://gitdiagram.com/blackblazent/blackmusic
- Repository: https://github.com/blackblazent/blackmusic

## Overview

##### Project type and purpose
- This is a cross-platform desktop music player built on Electron (Node.js + Chromium) with a React/TypeScript renderer.
- Its goal is to integrate a vast catalog of music, manage local data (themes, languages, metadata, playlists, etc.), and support native extensions/plugins for audio conversion or other low-level tasks.

##### File structure
- **Top-level build & config**
- .babelrc, tsconfig.json, webpack.config.js → compile/transpile pipeline for renderer and main code
- Dockerfile & docker-compose.yml → optional containerized dev/test environments
- package.json & install/update/uninstall scripts → dependency management and lifecycle hooks
- **Electron entrypoints**
- src/index.tsx (renderer bootstrap)
- src/App.tsx (React root component)
- src/preload.js (safe IPC bridge via contextBridge)
- src/renderer.js (renderer process utilities)
- **Plugin/extension system**
- .app-registry/… → JSON/JS registry of commands, modules & native_app submodule (with binding.gyp, C++ converter)
- app-registry dependencies/commands → JS and Python workers exposed via the registry
- **Persistent data**
- AppData/… → Version manifest, core/data (Ads, Themes, Languages, Storage, etc.)
- AppData/…/*.db and backup.sqlite → local SQLite databases for user settings, history, metadata
- **Legacy/archived code**
- AppData/bmusic/forbidden and embedded/… → archived server, embedded platform code (Ada, Julia, Perl, Python, Ruby, FFmpeg, etc.)
- These can be shown as “archived modules” or simply omitted if out of scope
- **Public assets**
- public/… photos, videos, presentations (served to web or packaged in the app)

##### README for additional insights
- Confirms Electron+React: references HTML/CSS in src, UI galleries
- Mentions deep integration (catalog, superior playback) but no online APIs listed → it’s primarily local with possible extensions for streaming

a. Main components
1. **Electron Main Process**
– Bootstraps the app, loads native modules, manages plugin registry, orchestrates IPC
2. **Preload Bridge**
– Exposes a limited, secure API (`window.api`) to the Renderer
3. **Renderer Process (React UI)**
– UI components (App.tsx, pages, controls)
– Dispatches commands via IPC to Main
4. **Plugin/Module Loader**
– Reads `.app-registry`, dynamically loads JS/Python/Native modules
5. **Native Addons**
– E.g., `native_app/configuration/convert.cpp` compiled via node-gyp for audio transcoding
6. **Local Storage**
– File system hierarchy under AppData (JSON, XML, DB files)
– SQLite DBs for history, settings, metadata, backups
7. **(Optional) External Services**
– Firebase SDK, remote endpoints if any streaming or analytics are integrated
8. **CI/CD & Packaging**
– GitHub Actions workflows, Docker-based tests, packaging via Electron Builder (implied)
b. Relationships and interactions
– UI → IPC → Main Process → Plugin Loader → Native Addon or File System
– Main Process ↔ File System (read/write AppData folder & SQLite)
– Renderer → HTTP/HTTPS (if web requests for catalog or remote modules)
– CI/CD pipelines trigger Docker build → run tests → publish packages
c. Architectural patterns / design principles
– **Layered Architecture**: separation of concerns between UI, business logic (Main), and persistence
– **Plugin Architecture**: `.app-registry` drives a modular system for commands & extensions
– **Secure IPC**: exposing only necessary APIs via preload
– **Cross-platform abstraction**: native modules and embedded code for Windows/macOS/Linux
d. Key technologies
– Electron, Node.js, React, TypeScript, Webpack, Babel
– SQLite (via node-sqlite3 or similar)
– node-gyp for native addons (C++)
– Docker, GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Renderer Process (React UI)" 
        R1["src/index.tsx"] 
        R2["src/App.tsx"]
        R3["src/global.css"]
        R4["src/index.css"]
        R5["src/black-music-home.css"]
        R6["src/black-music-home.html"]
    end

    subgraph "Preload Bridge"
        P["src/preload.js"]
    end

    subgraph "Electron Main Process"
        M1["src/index.js"]
        M2["src/renderer.js"]
    end

    subgraph "Plugin/Module Loader"
        PL1[".app-registry/app-tx.js"]
        PL2[".app-registry/dependencies/commands/worker.js"]
        PL3[".app-registry/dependencies/commands/command.py"]
        PL4[".app-registry/systems/modules"]
    end

    subgraph "Native Addons"
        N1["binding.gyp"]
        N2["convert.cpp"]
        N3["convert.h"]
    end

    subgraph "Persistence (AppData)"
        D1["version-manifest.txt"]
        subgraph "core/data"
            C1["Ads: ads.txt, ads.xml"]
            C2["Languages: *.lng"]
            C3["Themes/default: *.themes"]
            C4["Metadata: metadata.xml"]
        end
        subgraph "backup"
            B1["backup.db"]
            B2["backup.sqlite"]
        end
    end

    subgraph "CI/CD & Packaging"
        CI1[".github/workflows/npm-grunt.yml"]
        CI2[".github/bmusic.yml"]
        CI3["Dockerfile"]
        CI4["docker-compose.yml"]
    end

    subgraph "Build & Transpile Config"
        B5[".babelrc"]
        B6["tsconfig.json"]
        B7["webpack.config.js"]
        B8["package.json"]
        B9["package-lock.json"]
    end

    R1 --> P
    R2 --> P
    R6 --> P
    P --> M1
    M1 --> PL1
    PL1 --> N1
    PL1 --> N2
    PL1 --> N3
    M1 --> D1
    CI1 --> B5
    CI2 --> B5

    click R1 "https://github.com/blackblazent/blackmusic/blob/main/src/index.tsx"
    click R2 "https://github.com/blackblazent/blackmusic/blob/main/src/App.tsx"
    click R3 "https://github.com/blackblazent/blackmusic/blob/main/src/global.css"
    click R4 "https://github.com/blackblazent/blackmusic/blob/main/src/index.css"
    click R5 "https://github.com/blackblazent/blackmusic/blob/main/src/black-music-home.css"
    click R6 "https://github.com/blackblazent/blackmusic/blob/main/src/black-music-home.html"
    click P "https://github.com/blackblazent/blackmusic/blob/main/src/preload.js"
    click M1 "https://github.com/blackblazent/blackmusic/blob/main/src/index.js"
    click M2 "https://github.com/blackblazent/blackmusic/blob/main/src/renderer.js"
    click PL1 "https://github.com/blackblazent/blackmusic/blob/main/.app-registry/app-tx.js"
    click PL2 "https://github.com/blackblazent/blackmusic/blob/main/.app-registry/dependencies/commands/worker.js"
    click PL3 "https://github.com/blackblazent/blackmusic/blob/main/.app-registry/dependencies/commands/command.py"
    click PL4 "https://github.com/blackblazent/blackmusic/tree/main/.app-registry/systems/modules"
    click N1 "https://github.com/blackblazent/blackmusic/blob/main/.app-registry/systems/modules/native_app/binding.gyp"
    click N2 "https://github.com/blackblazent/blackmusic/blob/main/.app-registry/systems/modules/native_app/configuration/convert.cpp"
    click N3 "https://github.com/blackblazent/blackmusic/blob/main/.app-registry/systems/modules/native_app/configuration/convert.h"
    click D1 "https://github.com/blackblazent/blackmusic/blob/main/AppData/1.1.01.001.0001/version-manifest.txt"
    click C1 "https://github.com/blackblazent/blackmusic/blob/main/AppData/bmusic/core/data/Ads/ads.txt"
    click C2 "https://github.com/blackblazent/blackmusic/tree/main/AppData/bmusic/core/data/Languages"
    click C3 "https://github.com/blackblazent/blackmusic/tree/main/AppData/bmusic/core/data/Themes/default"
    click C4 "https://github.com/blackblazent/blackmusic/blob/main/AppData/bmusic/core/data/Metadata/metadata.xml"
    click B1 "https://github.com/blackblazent/blackmusic/blob/main/AppData/bmusic/backup/backup.db"
    click B2 "https://github.com/blackblazent/blackmusic/blob/main/AppData/bmusic/backup/backup.sqlite"
    click CI1 "https://github.com/blackblazent/blackmusic/blob/main/.github/workflows/npm-grunt.yml"
    click CI2 "https://github.com/blackblazent/blackmusic/blob/main/.github/bmusic.yml"
    click CI3 "https://github.com/blackblazent/blackmusic/tree/main/Dockerfile"
    click CI4 "https://github.com/blackblazent/blackmusic/blob/main/docker-compose.yml"
    click B5 "https://github.com/blackblazent/blackmusic/blob/main/.babelrc"
    click B6 "https://github.com/blackblazent/blackmusic/blob/main/tsconfig.json"
    click B7 "https://github.com/blackblazent/blackmusic/blob/main/webpack.config.js"
    click B8 "https://github.com/blackblazent/blackmusic/blob/main/package.json"
    click B9 "https://github.com/blackblazent/blackmusic/blob/main/package-lock.json"

    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef business fill:#90EE90,stroke:#000,stroke-width:1px
    classDef plugin fill:#FFFF99,stroke:#000,stroke-width:1px
    classDef native fill:#FFD700,stroke:#000,stroke-width:1px
    classDef persistence fill:#D2B48C,stroke:#000,stroke-width:1px
    classDef devops fill:#D3D3D3,stroke:#000,stroke-width:1px

    class R1,R2,R3,R4,R5,R6 frontend
    class P,M1,M2 business
    class PL1,PL2,PL3,PL4 plugin
    class N1,N2,N3 native
    class D1,C1,C2,C3,C4,B1,B2 persistence
    class CI1,CI2,CI3,CI4,B5,B6,B7,B8,B9 devops
```
