# bemusic/bemuse architecture

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

- Interactive diagram: https://gitdiagram.com/bemusic/bemuse
- Repository: https://github.com/bemusic/bemuse

## Overview

- Main Game Application (Client)
- Frontend/UI Layer: This consists primarily of the React/Redux code found under bemuse/src/app and the extensive “ui” subdirectories. It handles user interactions, the display of game scenes (title, music selection, gameplay, options, etc.), and routing.
- Game Engine: Within bemuse/src/game, you have low-level game logic modules (audio, display, input, scene management, and the timing system) that drive rendering (with PixiJS), audio playback, and game state.
- Asset and Resource Management: Components such as skins, public assets, and multimedia files (images, fonts, music files) in directories like bemuse/public and public/skins.
- Auxiliary Modules: Additional features like auto-synchro, online ranking, custom song loading (e.g., in bemuse/src/custom-song-loader, bemuse/src/online) and analytics (in bemuse/src/app/analytics.js).

- Sub-Projects / Libraries (Packages)
- Parsing and File Handling Modules: Binary music sequence support is provided by packages such as “bms” and “bmson” that parse BMS and BMSON file formats.
- Utility and Tooling Packages: “bemuse-tools”, “bemuse-indexer”, and “bemuse-notechart” provide supporting functions including file packaging, indexing, and notechart loading.
- Types and Linting/Configuration: There are packages such as “bemuse-types” and “eslint-config-bemuse” that ensure consistency across the project.

- Build, Testing, and CI/CD Infrastructure:
- Build Tools: The repository shows configuration files for Rush (rush.json), gulp tasks, webpack configs, and various tsconfig files to compile and bundle the project.
- Testing and Quality: There are dedicated folders for tests within bemuse (Karma, Jest specs, e2e with Playwright) and continuous integration configurations under .github/workflows and .circleci.
- Development Environment: Also note the use of devcontainer, Gitpod, and common scripts for initializing the development environment.

- Website and Documentation:
- Website Project: The “website” folder contains the content and code (likely using a static site generator or Docusaurus) for the public-facing documentation, guides, blog posts, and demos.

##### Out the relationships and interactions
- A separation between the Client (Frontend/UI) and the underlying Game Engine that processes real-time game state, multimedia, and inputs.
- How the game engine interacts with resource loaders (custom-song-loader, keysound-cache, etc.) and how the asset pipeline manages skins, fonts, and multimedia files.
- Finally, include the website/documentation component that sits somewhat orthogonally, providing guides, demos, and external resources for users and developers.

##### Architectural patterns and design principles
- Monorepo and Modular Design: Emphasize the division into independent, reusable modules (sub-projects) managed under packages and the main “bemuse” application.
- Separation of Concerns: Illustrate clearly how the UI, game logic, resource management, and external services are each isolated into their own components.
- Client-Side Rendering and Event-Driven Programming: Note the use of React/Redux for state management and PixiJS for game rendering.
- Continuous Integration/Deployment Pipeline: Represent the integration of tools such as Rush, CircleCI, GitHub Actions, and various configuration files that support a robust development workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Main Game Application (Client)"
        UI["Frontend/UI Layer"]:::frontend
        GE["Game Engine"]:::gameEngine
        subgraph "Asset & Resource Management"
            PA["Public Assets"]:::assets
            SK["Skins"]:::assets
        end
        subgraph "Auxiliary Modules"
            CSL["Custom Song Loader"]:::aux
            ANL["Analytics"]:::aux
            ONL["Online Features"]:::aux
        end
        subgraph "UI Subcomponents"
            UIS["UI Subdirectories"]:::frontend
        end
    end

    subgraph "Sub-Projects / Libraries"
        BMS["BMS Parser"]:::lib
        BMSON["BMSON Parser"]:::lib
        TOOLS["Bemuse Tools"]:::lib
        INDEXER["Bemuse Indexer"]:::lib
        NOTECHART["Bemuse Notechart"]:::lib
        TYPES["Bemuse Types"]:::lib
        ESLINT["ESLint Config"]:::lib
    end

    subgraph "Build, Testing, and CI/CD Infrastructure"
        subgraph "Build Tools"
            RUSH["Rush Config"]:::build
            BUILDCONF["Webpack & Gulp Config"]:::build
            GULP["Gulpfile.js"]:::build
        end
        subgraph "Testing & CI/CD"
            GHW["GitHub Workflows"]:::ci
            CIRCLE["CircleCI"]:::ci
            E2E["E2E Tests"]:::ci
            UNIT["Unit Tests"]:::ci
        end
    end

    subgraph "Website & Documentation"
        DOCS["Website & Documentation"]:::docs
    end

    %% Relationships
    UI -->|"sendsInput"| GE
    UI -->|"updatesView"| UIS
    GE -->|"loadsAssets"| PA
    GE -->|"loadsAssets"| SK
    GE -->|"callsAux"| CSL
    GE -->|"callsAux"| ANL
    GE -->|"callsAux"| ONL
    GE -->|"dependsOn"| BMS
    GE -->|"dependsOn"| BMSON
    GE -->|"dependsOn"| TOOLS
    GE -->|"dependsOn"| INDEXER
    GE -->|"dependsOn"| NOTECHART
    GE -->|"dependsOn"| TYPES
    GE -->|"dependsOn"| ESLINT
    RUSH -->|"builds"| UI
    BUILDCONF -->|"bundles"| UI
    GULP -->|"bundles"| UI
    GHW -->|"tests"| UI
    CIRCLE -->|"tests"| UI
    E2E -->|"tests"| UI
    UNIT -->|"tests"| UI
    UI -->|"showsDocs"| DOCS

    %% Click Events
    click UI "https://github.com/bemusic/bemuse/tree/master/bemuse/src/app"
    click UIS "https://github.com/bemusic/bemuse/tree/master/bemuse/src/app/ui"
    click GE "https://github.com/bemusic/bemuse/tree/master/bemuse/src/game"
    click PA "https://github.com/bemusic/bemuse/tree/master/bemuse/public"
    click SK "https://github.com/bemusic/bemuse/tree/master/public/skins"
    click CSL "https://github.com/bemusic/bemuse/tree/master/bemuse/src/custom-song-loader"
    click ANL "https://github.com/bemusic/bemuse/blob/master/bemuse/src/app/analytics.js"
    click ONL "https://github.com/bemusic/bemuse/tree/master/bemuse/src/online"
    click BMS "https://github.com/bemusic/bemuse/tree/master/packages/bms"
    click BMSON "https://github.com/bemusic/bemuse/tree/master/packages/bmson"
    click TOOLS "https://github.com/bemusic/bemuse/tree/master/packages/bemuse-tools"
    click INDEXER "https://github.com/bemusic/bemuse/tree/master/packages/bemuse-indexer"
    click NOTECHART "https://github.com/bemusic/bemuse/tree/master/packages/bemuse-notechart"
    click TYPES "https://github.com/bemusic/bemuse/tree/master/packages/bemuse-types"
    click ESLINT "https://github.com/bemusic/bemuse/tree/master/packages/eslint-config-bemuse"
    click RUSH "https://github.com/bemusic/bemuse/blob/master/rush.json"
    click BUILDCONF "https://github.com/bemusic/bemuse/tree/master/bemuse/config"
    click GULP "https://github.com/bemusic/bemuse/blob/master/bemuse/gulpfile.js"
    click GHW "https://github.com/bemusic/bemuse/tree/master/.github/workflows"
    click CIRCLE "https://github.com/bemusic/bemuse/blob/master/.circleci"
    click E2E "https://github.com/bemusic/bemuse/tree/master/e2e"
    click UNIT "https://github.com/bemusic/bemuse/tree/master/bemuse/src/test"
    click DOCS "https://github.com/bemusic/bemuse/tree/master/website"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef gameEngine fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef assets fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef aux fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef lib fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef build fill:#F08080,stroke:#000,stroke-width:2px;
    classDef ci fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef docs fill:#87CEFA,stroke:#000,stroke-width:2px;
```
