# promethiuml/chordprogressor architecture

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

- Interactive diagram: https://gitdiagram.com/promethiuml/chordprogressor
- Repository: https://github.com/promethiuml/chordprogressor

## Overview

##### Project type and purpose
- This is a standalone Python-based musical tool (“Chord Progressor”) that computes smooth chord‐to‐chord voice leadings and plays them back instantly via audio backends.
- It’s not a web app or microservice—it’s a CLI/desktop utility focused on music theory and sound playback.

##### File structure
- Top level modules:
- progressor.py – the main entrypoint/CLI demo
- chord.py, note.py – core domain models (Chord, Note)
- chord_transforms.py, voice_leading.py – algorithms that manipulate/optimize chords
- sound_engine.py – central dispatcher for producing sound
- pygame_output.py, media_output.py – pluggable audio backends
- constants.py, utils.py – shared definitions & helper functions
- sounds/ – file store of pre-rendered note‐samples (.wav) addressed by index/name
- requirements.txt – lists external dependencies (pygame, playsound)

##### Extract README insights
- Uses pygame or playsound to output audio
- Core class hierarchy: Note → Chord → progression via connect_to()
- Future refactors: external chord symbol parser; improved voicing algorithm

##### Main components
A. CLI Application Layer
- progressor.py: parses user invocation, selects demo or custom progression
B. Music Core Layer
- Module (note.py, constants.py)
- Chord Module (chord.py, chord_transforms.py)
- Voice-Leading Module (voice_leading.py)
- Utilities (utils.py)
C. Sound Engine Layer
- sound_engine.py: orchestrates mapping Note/Chord → sample frames
D. Audio Backend Layer (Strategy Pattern)
- pygame_output.py
- media_output.py
E. File System / Sample Store
- sounds/*.wav

##### Relationships and data flows
1. User runs progressor.py → instantiates Note and Chord objects
2. Chord.connect_to() invokes voice_leading.py → returns optimized voicing (interval sets)
3. progressor.py calls sound_engine.play(chords)
4. sound_engine consults Audio Backend Factory → selects either pygame_output or media_output
5. Chord→Note events passed to backend → backend loads .wav samples from sounds/ → audio sent to OS sound API

##### Architectural patterns & principles
- Strategy pattern for pluggable backends (pygame vs. playsound)
- Single Responsibility: each module handles one aspect (parsing, transformation, playback)
- Data‐flow emphasis: immutable Note/Chord objects feed pure transformation functions → playback

##### Technologies & frameworks
- Python 3.x
- pygame (direct sound buffer scheduling)
- playsound (simple media layer)
- WAV sample library (44.1 kHz pre-rendered notes)

##### Capturing essential elements
- Do not collapse distinct modules: show chord_transforms and voice_leading separately
- Sample store with “Indexed .wav files named by pitch index” to highlight lookup logic

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Application Layer"
        Progressor["progressor.py"]:::cli
    end

    %% Music Core Layer
    subgraph "Music Core Layer"
        direction TB
        Constants["constants.py"]:::core
        Note["note.py"]:::core
        Chord["chord.py"]:::core
        Transforms["chord_transforms.py"]:::core
        VoiceLeading["voice_leading.py"]:::core
        Utils["utils.py"]:::core
    end

    %% Plugin Extension Point
    subgraph "Plugin Extension Point" style dashed
        ParserPlugin["ChordParserPlugin"]:::plugin
    end

    %% Sound Engine Layer
    SoundEngine["sound_engine.py"]:::engine

    %% Audio Backend Layer
    subgraph "Audio Backend Layer"
        direction TB
        Pygame["pygame_output.py"]:::backend
        Media["media_output.py"]:::backend
    end

    %% File Store Layer
    Samples["sounds/\\nIndexed .wav files named by pitch index"]:::store
    OSAudio["OS Audio System"]:::store

    %% Relationships
    Progressor --> Note
    Progressor --> Constants
    Progressor --> Chord
    ParserPlugin -.-> Chord
    Chord --> Transforms
    Chord --> VoiceLeading
    Progressor --> SoundEngine
    SoundEngine -->|Strategy selection| Pygame
    SoundEngine -->|Strategy selection| Media
    Pygame --> Samples
    Media --> Samples
    Samples --> OSAudio

    %% Click Events
    click Progressor "https://github.com/promethiuml/chordprogressor/blob/master/progressor.py"
    click Note "https://github.com/promethiuml/chordprogressor/blob/master/note.py"
    click Constants "https://github.com/promethiuml/chordprogressor/blob/master/constants.py"
    click Chord "https://github.com/promethiuml/chordprogressor/blob/master/chord.py"
    click Transforms "https://github.com/promethiuml/chordprogressor/blob/master/chord_transforms.py"
    click VoiceLeading "https://github.com/promethiuml/chordprogressor/blob/master/voice_leading.py"
    click Utils "https://github.com/promethiuml/chordprogressor/blob/master/utils.py"
    click SoundEngine "https://github.com/promethiuml/chordprogressor/blob/master/sound_engine.py"
    click Pygame "https://github.com/promethiuml/chordprogressor/blob/master/pygame_output.py"
    click Media "https://github.com/promethiuml/chordprogressor/blob/master/media_output.py"
    click Samples "https://github.com/promethiuml/chordprogressor/tree/master/sounds/"

    %% Styles
    classDef cli fill:#D6EAF8,stroke:#1B4F72;
    classDef core fill:#D5F5E3,stroke:#196F3D;
    classDef engine fill:#FAD7A0,stroke:#B9770E;
    classDef backend fill:#FCF3CF,stroke:#B7950B;
    classDef store fill:#E5E8E8,stroke:#616A6B;
    classDef plugin fill:#FDEDEC,stroke:#C0392B;
```
