# hopealexis/fractalmusicgenerator architecture

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

- Interactive diagram: https://gitdiagram.com/hopealexis/fractalmusicgenerator
- Repository: https://github.com/hopealexis/fractalmusicgenerator

## Overview

1. **Project shape**
   - This is a small Python desktop application centered on generating music from fractal-based logic.
   - The repository is organized as a single-process app with a GUI, generation logic, playback, and local persistence.

2. **Entry point and orchestration**
   - `main.py` is the likely bootstrapper.
   - It probably wires together the GUI, music generation engine, library storage, and real-time playback components.

3. **User interface boundary**
   - `gui.py` is the presentation layer.
   - It likely handles user inputs such as choosing a fractal mode, selecting a scale, triggering generation, and controlling playback.
   - `themes/lavender.json` suggests the UI supports theme customization through JSON-based styling/configuration.

4. **Music generation core**
   - `music_generator.py` appears to be the main domain engine that turns inputs into musical output.
   - This is probably where the app translates fractal structures, scale rules, and possibly timing parameters into notes, sequences, or patterns.

5. **Fractal logic subsystem**
   - `fractal_handlers.py` likely contains the fractal-specific algorithms or adapters.
   - This is a distinct boundary from general music generation: it probably produces numerical/pattern data that the generator converts into musical events.

6. **Musical theory rules**
   - `musical_scales.py` looks like the repository’s scale/tonality module.
   - It likely defines supported scales, note mappings, and pitch constraints used by the generator so that fractal-derived values become musically coherent.

7. **Playback subsystem**
   - `real_time_player.py` suggests live or near-live audio output.
   - This module likely consumes generated note events or sequences and renders them through an audio backend, separating sound production from generation.

8. **Library / persistence layer**
   - `library.py` and `data/library.json` form a local storage boundary.
   - The app likely saves generated compositions, presets, or metadata in JSON rather than using a database or external service.

9. **Shared utilities**
   - `utils.py` is the common support module for reusable helpers.
   - In a repo like this, it likely contains formatting, conversions, validation, or small shared functions used across generator, GUI, and playback code.

10. **Data and configuration**
   - `data/` and `themes/` indicate the app relies on file-based configuration and assets.
   - This means the architecture is mostly local and offline: configuration, theme data, and saved library state all live inside the repository or adjacent runtime files.

11. **Likely runtime flow**
   - A user interacts with the GUI.
   - The GUI invokes the fractal/music generation pipeline.
   - Fractal handlers produce structure, musical scales constrain it, and the generator assembles playable musical data.
   - The player renders output in real time, and the library layer can persist results for later reuse.

12. **Architectural boundaries to draw**
   - Separate the app into four main blocks: **UI**, **generation logic**, **audio playback**, and **local persistence/configuration**.
   - The main directional data flow is: **GUI → fractal/generation logic → real-time player**, with **library/theme files** as supporting inputs and outputs.

Main entry points: [`music_generator.py`](https://github.com/hopealexis/fractalmusicgenerator/blob/main/music_generator.py) (Music engine), [`gui.py`](https://github.com/hopealexis/fractalmusicgenerator/blob/main/gui.py) (GUI), [`main.py`](https://github.com/hopealexis/fractalmusicgenerator/blob/main/main.py) (Main), [`library.py`](https://github.com/hopealexis/fractalmusicgenerator/blob/main/library.py) (Library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_main["Main<br/>bootstrap<br/>[main.py]"]
  node_gui["GUI<br/>presentation<br/>[gui.py]"]
end

subgraph group_gen["Generation"]
  node_generator["Music engine<br/>domain engine<br/>[music_generator.py]"]
  node_fractals{{"Fractals<br/>pattern logic"}}
  node_scales["Scales<br/>theory rules<br/>[musical_scales.py]"]
  node_utils["Utilities<br/>shared helpers<br/>[utils.py]"]
end

subgraph group_playback["Playback"]
  node_player(("Player<br/>audio runtime"))
end

subgraph group_storage["Storage"]
  node_theme["Lavender theme<br/>ui theme<br/>[lavender.json]"]
  node_library[("Library<br/>persistence layer<br/>[library.py]")]
  node_library_data["Library data<br/>json store<br/>[library.json]"]
end

node_main -->|"launches"| node_gui
node_main -->|"wires"| node_generator
node_main -->|"wires"| node_player
node_main -->|"wires"| node_library
node_gui -->|"requests"| node_generator
node_gui -->|"controls"| node_player
node_gui -->|"manages"| node_library
node_gui -.->|"styles"| node_theme
node_generator -->|"derives from"| node_fractals
node_generator -->|"constrains by"| node_scales
node_generator -.->|"uses"| node_utils
node_generator -->|"emits"| node_player
node_library -->|"reads/writes"| node_library_data
node_library -.->|"uses"| node_utils

click node_main "https://github.com/hopealexis/fractalmusicgenerator/blob/main/main.py"
click node_gui "https://github.com/hopealexis/fractalmusicgenerator/blob/main/gui.py"
click node_theme "https://github.com/hopealexis/fractalmusicgenerator/blob/main/themes/lavender.json"
click node_generator "https://github.com/hopealexis/fractalmusicgenerator/blob/main/music_generator.py"
click node_fractals "https://github.com/hopealexis/fractalmusicgenerator/blob/main/fractal_handlers.py"
click node_scales "https://github.com/hopealexis/fractalmusicgenerator/blob/main/musical_scales.py"
click node_utils "https://github.com/hopealexis/fractalmusicgenerator/blob/main/utils.py"
click node_player "https://github.com/hopealexis/fractalmusicgenerator/blob/main/real_time_player.py"
click node_library "https://github.com/hopealexis/fractalmusicgenerator/blob/main/library.py"
click node_library_data "https://github.com/hopealexis/fractalmusicgenerator/blob/main/data/library.json"

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_main,node_gui toneBlue
class node_generator,node_fractals,node_scales,node_utils toneAmber
class node_player toneMint
class node_theme,node_library,node_library_data toneRose
```

## Components

### App shell

Bootstrap and user-facing interface

- [Main](https://github.com/hopealexis/fractalmusicgenerator/blob/main/main.py): bootstrap · Starts the desktop app and wires subsystems · `main.py`
- [GUI](https://github.com/hopealexis/fractalmusicgenerator/blob/main/gui.py): presentation · User interface for controls and feedback · `gui.py`

### Generation

Fractal-driven music creation

- [Music engine](https://github.com/hopealexis/fractalmusicgenerator/blob/main/music_generator.py): domain engine · Turns fractal and scale inputs into musical structures · `music_generator.py`
- [Fractals](https://github.com/hopealexis/fractalmusicgenerator/blob/main/fractal_handlers.py): pattern logic · Produces fractal-derived numerical or structural patterns · `fractal_handlers.py`
- [Scales](https://github.com/hopealexis/fractalmusicgenerator/blob/main/musical_scales.py): theory rules · Defines pitch sets and tonal constraints · `musical_scales.py`
- [Utilities](https://github.com/hopealexis/fractalmusicgenerator/blob/main/utils.py): shared helpers · Common helper functions used across modules · `utils.py`

### Playback

Real-time audio output

- [Player](https://github.com/hopealexis/fractalmusicgenerator/blob/main/real_time_player.py): audio runtime · Renders generated music in real time · `real_time_player.py`

### Storage

Local persistence and assets

- [Lavender theme](https://github.com/hopealexis/fractalmusicgenerator/blob/main/themes/lavender.json): ui theme · JSON theme configuration for the interface · `themes/lavender.json`
- [Library](https://github.com/hopealexis/fractalmusicgenerator/blob/main/library.py): persistence layer · Saves and loads local compositions or presets · `library.py`
- [Library data](https://github.com/hopealexis/fractalmusicgenerator/blob/main/data/library.json): json store · On-disk saved library state · `data/library.json`

## Connections

- Main → GUI: launches · Bootstraps the user interface
- Main → Music engine: wires · Connects the app shell to the generation engine
- Main → Player: wires · Connects startup flow to audio playback
- Main → Library: wires · Initializes local persistence
- GUI → Music engine: requests · Triggers generation from user actions
- GUI → Player: controls · Sends play and stop commands
- GUI → Library: manages · Loads or saves user compositions
- GUI → Lavender theme: styles · Uses theme configuration for presentation
- Music engine → Fractals: derives from · Converts fractal structures into musical material
- Music engine → Scales: constrains by · Maps output into valid tonal sets
- Music engine → Utilities: uses · Shares helpers for transformation and formatting
- Music engine → Player: emits · Produces playable note or sequence data
- Library → Library data: reads/writes · Persists library state as JSON
- Library → Utilities: uses · Shares common data handling helpers
