# dadziek/vibemusician architecture

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

- Interactive diagram: https://gitdiagram.com/dadziek/vibemusician
- Repository: https://github.com/dadziek/vibemusician

## Overview

VibeMusician is a Flask application for controllable, autoregressive classical MIDI generation. A user selects a MIDI seed and generation parameters in the web interface; the API normalizes the request, the generator samples events with the trained Transformer, and MIDI export produces a downloadable file. The README also documents a separate model-training workflow. Generator internals are only partially sampled, so the graph omits uncertain internal calls; the training relationship follows README documentation.

Main entry points: [`routes/music.py`](https://github.com/dadziek/vibemusician/blob/main/routes/music.py) (Music API routes), [`main.py`](https://github.com/dadziek/vibemusician/blob/main/main.py) (Flask application), [`services/music_generator.py`](https://github.com/dadziek/vibemusician/blob/main/services/music_generator.py) (Controlled generator), [`templates/index.html`](https://github.com/dadziek/vibemusician/blob/main/templates/index.html) (Generation interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_ui["Generation interface<br/>[index.html]"]
  node_app["Flask application<br/>[main.py]"]
  node_routes["Music API routes<br/>[music.py]"]
end

subgraph group_generation["Music generation"]
  node_config["Generation config"]
  node_generator["Controlled generator<br/>[music_generator.py]"]
  node_model["Transformer model<br/>[music_model.py]"]
  node_exporter["MIDI exporter<br/>[midi_exporter.py]"]
  node_midi_files["Generated MIDI files"]
end

subgraph group_training["Model training"]
  node_training["V4 training notebook"]
end

node_user(("User"))
node_checkpoint["Trained checkpoint"]
node_seedbank["MIDI seed bank"]
node_dataset["Classical MIDI dataset"]

node_user -->|"uses"| node_ui
node_ui -->|"submits parameters"| node_routes
node_app -->|"registers routes"| node_routes
node_app -->|"initializes"| node_generator
node_app -->|"loads"| node_checkpoint
node_app -->|"loads"| node_seedbank
node_routes -->|"normalizes request"| node_config
node_routes -->|"requests generation"| node_generator
node_generator -->|"runs inference"| node_model
node_generator -->|"exports events"| node_exporter
node_exporter -->|"writes MIDI"| node_midi_files
node_routes -->|"serves download"| node_midi_files
node_dataset -.->|"provides training data"| node_training
node_training -.->|"exports model"| node_checkpoint

click node_ui "https://github.com/dadziek/vibemusician/blob/main/templates/index.html"
click node_app "https://github.com/dadziek/vibemusician/blob/main/main.py"
click node_routes "https://github.com/dadziek/vibemusician/blob/main/routes/music.py"
click node_config "https://github.com/dadziek/vibemusician/blob/main/services/generation_config.py"
click node_generator "https://github.com/dadziek/vibemusician/blob/main/services/music_generator.py"
click node_model "https://github.com/dadziek/vibemusician/blob/main/models/music_model.py"
click node_exporter "https://github.com/dadziek/vibemusician/blob/main/services/midi_exporter.py"
click node_training "https://github.com/dadziek/vibemusician/blob/main/training/vibemusican_v4.ipynb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui,node_app,node_routes,node_user toneBlue
class node_config,node_generator,node_model,node_exporter,node_midi_files toneAmber
class node_training toneMint
class node_checkpoint,node_seedbank,node_dataset toneIndigo
```

## Components

### Web application

- [Generation interface](https://github.com/dadziek/vibemusician/blob/main/templates/index.html): `templates/index.html`
- [Flask application](https://github.com/dadziek/vibemusician/blob/main/main.py): `main.py`
- [Music API routes](https://github.com/dadziek/vibemusician/blob/main/routes/music.py): `routes/music.py`

### Music generation

- [Generation config](https://github.com/dadziek/vibemusician/blob/main/services/generation_config.py): `services/generation_config.py`
- [Controlled generator](https://github.com/dadziek/vibemusician/blob/main/services/music_generator.py): `services/music_generator.py`
- [Transformer model](https://github.com/dadziek/vibemusician/blob/main/models/music_model.py): `models/music_model.py`
- [MIDI exporter](https://github.com/dadziek/vibemusician/blob/main/services/midi_exporter.py): `services/midi_exporter.py`
- **Generated MIDI files**

### Model training

- [V4 training notebook](https://github.com/dadziek/vibemusician/blob/main/training/vibemusican_v4.ipynb): `training/vibemusican_v4.ipynb`

### Other components

- **User**
- **Trained checkpoint**
- **MIDI seed bank**
- **Classical MIDI dataset**

## Connections

- User → Generation interface: uses
- Generation interface → Music API routes: submits parameters
- Flask application → Music API routes: registers routes
- Flask application → Controlled generator: initializes
- Flask application → Trained checkpoint: loads
- Flask application → MIDI seed bank: loads
- Music API routes → Generation config: normalizes request
- Music API routes → Controlled generator: requests generation
- Controlled generator → Transformer model: runs inference
- Controlled generator → MIDI exporter: exports events
- MIDI exporter → Generated MIDI files: writes MIDI
- Music API routes → Generated MIDI files: serves download
- Classical MIDI dataset → V4 training notebook: provides training data
- V4 training notebook → Trained checkpoint: exports model