# vihan89/musicgn architecture

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

- Interactive diagram: https://gitdiagram.com/vihan89/musicgn
- Repository: https://github.com/vihan89/musicgn

## Overview

##### Project type and purpose
- This is a full-stack machine-learning application for music generation. It combines:
- A data preprocessing pipeline that ingests MIDI files
- An LSTM-based training module to produce neural network models
- A generation/inference module exposed via both CLI and a Flask-based web UI
- Storage for raw & processed data, trained model artifacts, and generated outputs

##### File structure
- Top-level directories:
- data/ (raw and processed MIDI sequences)
- models/ (saved LSTM models and mapping files)
- src/ (core Python packages: preprocessing, models, utils, web)
- templates/ (HTML for the web UI)
- Key scripts:
- src/train.py & quick_train.py / simple_train.py (model training)
- src/generate.py & src/web/app.py (inference via CLI & web)
- src/preprocessing/ (data_loader.py, midi_processor.py)
- src/models/ (lstm_model.py, music_generator.py)
- src/utils/ (audio/music utility functions)
- Config and setup: config.py, requirements.txt, setup.py

##### README for additional insights
- Describes a typical ML workflow: place MIDI in data/, run train, then generate either via CLI or web
- Mentions outputs (generated_midi, generated_audio) and real-time generation

##### Elements
- Related components in containers (e.g., a “src” boundary)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Training Pipeline
    subgraph "Training Pipeline"
        direction TB
        rawData["Raw MIDI Files"]:::storage
        midiProc["MIDI Processor"]:::compute
        dataLoader["Data Loader"]:::compute
        subgraph "Processed Data"
            direction TB
            procSeq1["processed_sequences.pkl"]:::storage
            procSeq2["sequences.npy"]:::storage
            procSeq3["note_mappings.pkl"]:::storage
        end
        trainingScripts["Training Scripts\n(src/train.py,\nquick_train.py,\nsimple_train.py)"]:::compute
        lstmTrainer["LSTM Trainer"]:::compute
        subgraph "Model Store"
            direction TB
            model1["latest_model.h5"]:::storage
            model2["simple_model.h5"]:::storage
            mappings["note_mappings.npz"]:::storage
        end
    end

    %% Inference Pipeline
    subgraph "Inference Pipeline"
        direction TB
        subgraph "CLI Inference"
            direction TB
            cliGen["CLI Generator\n(src/generate.py)"]:::compute
            musicGenCLI["Music Generator\n(src/models/music_generator.py)"]:::compute
            genOutCLI["Generated MIDI/Audio\n(outputs)"]:::storage
        end
        subgraph "Web Inference"
            direction TB
            browser["Browser"]:::external
            flaskApp["Flask App\n(src/web/app.py)"]:::compute
            webView["Web UI\n(templates/index.html)"]:::external
            musicGenWeb["Music Generator\n(src/models/music_generator.py)"]:::compute
            genOutWeb["Generated MIDI/Audio\n(outputs)"]:::storage
        end
    end

    %% Utilities & Configuration
    subgraph "Utilities & Configuration"
        direction TB
        utilsAudio["Audio Utils\n(src/utils/audio_utils.py)"]:::compute
        utilsMusic["Music Utils\n(src/utils/music_utils.py)"]:::compute
        config["Config\n(config.py)"]:::data
    end

    %% Flow Connections
    rawData -->|ingest| midiProc
    midiProc -->|process| dataLoader
    dataLoader -->|output| procSeq1
    dataLoader -->|output| procSeq2
    dataLoader -->|output| procSeq3
    procSeq1 --> trainingScripts
    procSeq2 --> trainingScripts
    procSeq3 --> trainingScripts
    trainingScripts --> lstmTrainer
    lstmTrainer --> model1
    lstmTrainer --> model2
    lstmTrainer --> mappings

    model1 --> cliGen
    model2 --> cliGen
    mappings --> cliGen
    cliGen --> musicGenCLI
    musicGenCLI --> genOutCLI

    model1 --> flaskApp
    model2 --> flaskApp
    mappings --> flaskApp
    browser -->|HTTP| flaskApp
    flaskApp --> webView
    flaskApp --> musicGenWeb
    musicGenWeb --> genOutWeb

    %% Config & Utils usage
    config --> midiProc
    config --> dataLoader
    config --> trainingScripts
    config --> lstmTrainer
    config --> cliGen
    config --> flaskApp
    utilsAudio --> midiProc
    utilsMusic --> midiProc
    utilsAudio --> musicGenCLI
    utilsMusic --> musicGenCLI
    utilsAudio --> musicGenWeb
    utilsMusic --> musicGenWeb

    %% Click Events
    click midiProc "https://github.com/vihan89/musicgn/blob/master/src/preprocessing/midi_processor.py"
    click dataLoader "https://github.com/vihan89/musicgn/blob/master/src/preprocessing/data_loader.py"
    click procSeq1 "https://github.com/vihan89/musicgn/blob/master/data/processed/processed_sequences.pkl"
    click procSeq2 "https://github.com/vihan89/musicgn/blob/master/data/processed/sequences.npy"
    click procSeq3 "https://github.com/vihan89/musicgn/blob/master/data/processed/note_mappings.pkl"
    click trainingScripts "https://github.com/vihan89/musicgn/blob/master/src/train.py"
    click trainingScripts "https://github.com/vihan89/musicgn/blob/master/quick_train.py"
    click trainingScripts "https://github.com/vihan89/musicgn/blob/master/simple_train.py"
    click lstmTrainer "https://github.com/vihan89/musicgn/blob/master/src/models/lstm_model.py"
    click model1 "https://github.com/vihan89/musicgn/blob/master/models/saved_models/latest_model.h5"
    click model2 "https://github.com/vihan89/musicgn/blob/master/models/saved_models/simple_model.h5"
    click mappings "https://github.com/vihan89/musicgn/blob/master/models/saved_models/note_mappings.npz"
    click cliGen "https://github.com/vihan89/musicgn/blob/master/src/generate.py"
    click musicGenCLI "https://github.com/vihan89/musicgn/blob/master/src/models/music_generator.py"
    click flaskApp "https://github.com/vihan89/musicgn/blob/master/src/web/app.py"
    click webView "https://github.com/vihan89/musicgn/blob/master/templates/index.html"
    click utilsAudio "https://github.com/vihan89/musicgn/blob/master/src/utils/audio_utils.py"
    click utilsMusic "https://github.com/vihan89/musicgn/blob/master/src/utils/music_utils.py"
    click config "https://github.com/vihan89/musicgn/blob/master/config.py"

    %% Styles
    classDef data fill:#EBF5FB,stroke:#3498DB
    classDef compute fill:#E9F7EF,stroke:#27AE60
    classDef storage fill:#FDEDEC,stroke:#E74C3C
    classDef external fill:#FEF9E7,stroke:#F1C40F
```
