# mersenne-sister/mmlxr architecture

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

- Interactive diagram: https://gitdiagram.com/mersenne-sister/mmlxr
- Repository: https://github.com/mersenne-sister/mmlxr

## Overview

##### Main System Components

- Frontend/UI Layer
- This includes everything rendered in the browser using HTML (compiled from Pug templates in src/views), CSS (Stylus files in src/style), and JavaScript.
- Key interactive components are the code editor (integrated via Ace Editor files under src/js/ace), the piano roll, track tab, file management UI, and other modal dialogs.
- A front-end framework is visually enhanced by Semantic UI (both the provided Semantic-UI directory and related assets in docs).

- MML Compiler/Processing Engine (Worker Thread)
- Core music processing modules reside in src/mmlxr. This is where the MML is compiled, macros, comments, repeats, and groups are processed, and events are created.
- A dedicated PEG.js parser (in src/peg) extracts grammar for the MML language.
- This engine is responsible for “compiling” the user’s input MML, preparing events for playback, and carrying out the audio synthesis logic.

- Communication Infrastructure
- A two-thread architecture is in place. The main thread handles UI and audio node management with Web Audio while a background worker thread handles heavy processing tasks.
- The README play sequence illustrates clearly the message passing between the worker thread and the main thread (using messages such as COM_PLAY, COM_PLAYSOUND, COM_BUFFER, and COM_STOPSOUND).

- Audio Engine
- Utilizes the Web Audio API. The main thread sets up audio nodes (ScriptProcessor or audio callbacks) to receive buffers produced by the worker thread.
- Modules within src/mmlxr (e.g., wave_generator.ts) work in tandem with the audio engine to convert compiled events into sound.

- Build and Configuration Environment
- Tools like gulp (gulpfile.js), webpack (webpack.config.js), and package.json indicate a modern build process.
- Configuration files (config.yml, tsconfig.json, etc.) set up the environment for both development and production.

##### Determining the Relationships and Interactions

- Data Flow and Control Path:
- The user interacts with the UI in the browser (e.g., entering MML code, using the editor’s autocompletion) which is then sent to the worker thread.
- The worker thread processes the MML code by calling various submodules (like the parser, macro processor, note tab processor, etc.) and compiles it into a sequence of events.
- Once compiled, the worker sends data back (as buffer chunks) to the main thread where the Web Audio API picks up these buffers to play sound.
- There is bidirectional communication: control commands (e.g., stopping sound) flow from the UI to the worker, and playback data flows from the worker back to the UI.

- Inter-module interactions:
- The MML compilation workflow touches various logical modules (flmml_analyzer, file_manager, mixer, etc. in src/mmlxr) and interacts with the audio engine.
- The Peg parser (for MML syntax) is integrated as part of this pipeline.

##### Architectural Patterns & Design Principles

- Separation of Concerns:
- Clear division between UI (handling rendering and user interaction) and background processing (compiling MML, generating audio data).

- Asynchronous Communication:
- Use of Web Worker for heavy compute ensures that the UI remains responsive.
- The detailed play sequence in the README illustrates how command messages traverse between main and worker threads.

- Modular Design:
- The numerous TypeScript modules under src/mmlxr indicate well-organized components for each feature (editor, keyboard, piano roll, etc.).
- The presence of distinct folders (src/js for editor support, src/style for styling, src/views for templating, etc.) reinforces this modularity.

- Intermediary steps in the Web Worker where the MML code flows through parsing (PEG.js), macro/comment and note processing, and then compilation into events.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser / UI Layer
    subgraph "Browser / UI Layer"
        UI_HTML["HTML Templates (Pug)"]:::ui
        UI_CSS["CSS/Stylus Files"]:::ui
        UI_Ace["MML Editor (Ace-based)"]:::ui
        UI_Piano["Piano Roll (src/mmlxr/piano_roll.ts)"]:::ui
        UI_Track["Track Tab (src/mmlxr/track_tab.ts)"]:::ui
        UI_File["File Manager (src/mmlxr/file_manager.ts)"]:::ui
        UI_Modal["Modal Dialog (_modal.pug)"]:::ui
        UI_Modal_About["About Modal (_modal_about.pug)"]:::ui
    end

    %% Worker Thread / MML Compiler
    subgraph "Worker Thread / MML Compiler"
        Compiler_Core["Core Compiler Modules (src/mmlxr)"]:::compiler
        Compiler_PEG["PEG.js Parser (src/peg)"]:::compiler
        Compiler_Wave["Audio Processing & Event Generation"]:::compiler
        Worker_Msg["Worker Message Handling (docs/js/flmmlworker.js)"]:::compiler
    end

    %% Audio Engine
    subgraph "Audio Engine (Web Audio API)"
        Audio_Engine["Audio Engine (Web Audio API)"]:::audio
    end

    %% Build & Configuration
    subgraph "Build & Configuration"
        Build_Gulp["Gulp Build (gulpfile.js)"]:::build
        Build_Webpack["Webpack Bundling (webpack.config.js)"]:::build
        Build_Config["Configuration Files (config.yml, tsconfig.json, package.json)"]:::build
    end

    %% Data Flow and Communication
    UI_Ace -->|"SubmitMML"| Compiler_Core
    UI_Ace -->|"ControlMsg"| Worker_Msg
    Compiler_Core -->|"ParseAndCompile"| Compiler_PEG
    Compiler_Core -->|"GenerateEvents"| Compiler_Wave
    Compiler_Wave -->|"SendAudioBuffer"| Audio_Engine
    Audio_Engine -->|"PlaySound"| UI_Ace

    %% Build System Integration
    Build_Gulp -->|"BundleHTML"| UI_HTML
    Build_Webpack -->|"BundleModules"| Compiler_Core
    Build_Config -->|"LoadAssets"| UI_CSS

    %% Click Events for UI Layer
    click UI_HTML "https://github.com/mersenne-sister/mmlxr/tree/master/src/views"
    click UI_CSS "https://github.com/mersenne-sister/mmlxr/tree/master/src/style"
    click UI_Ace "https://github.com/mersenne-sister/mmlxr/tree/master/src/js/ace"
    click UI_Piano "https://github.com/mersenne-sister/mmlxr/blob/master/src/mmlxr/piano_roll.ts"
    click UI_Track "https://github.com/mersenne-sister/mmlxr/blob/master/src/mmlxr/track_tab.ts"
    click UI_File "https://github.com/mersenne-sister/mmlxr/blob/master/src/mmlxr/file_manager.ts"
    click UI_Modal "https://github.com/mersenne-sister/mmlxr/blob/master/src/views/_modal.pug"
    click UI_Modal_About "https://github.com/mersenne-sister/mmlxr/blob/master/src/views/_modal_about.pug"

    %% Click Events for Worker Thread / Compiler
    click Compiler_Core "https://github.com/mersenne-sister/mmlxr/tree/master/src/mmlxr"
    click Compiler_PEG "https://github.com/mersenne-sister/mmlxr/blob/master/src/peg/flmml-parser.pegjs"
    click Compiler_Wave "https://github.com/mersenne-sister/mmlxr/blob/master/src/mmlxr/wave_generator.ts"
    click Worker_Msg "https://github.com/mersenne-sister/mmlxr/blob/master/docs/js/flmmlworker.js"

    %% Click Events for Build & Configuration
    click Build_Gulp "https://github.com/mersenne-sister/mmlxr/blob/master/gulpfile.js"
    click Build_Webpack "https://github.com/mersenne-sister/mmlxr/blob/master/webpack.config.js"
    click Build_Config "https://github.com/mersenne-sister/mmlxr/blob/master/config.yml"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef compiler fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef audio fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef build fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
