# promethiuml/justchord architecture

> Architecture diagram of the GitHub repository promethiuml/justchord, 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/justchord
- Repository: https://github.com/promethiuml/justchord

## Overview

##### Project Type and Purpose
- This is a single‐process, desktop GUI application written in Python.
- Purpose: Real-time MIDI chord recognition and visualization. Uses RtMidi for MIDI I/O and PyQt5 for GUI widgets.

##### File Structure
Top-level:
- main.py – application entry point
- requirements.txt – external dependencies (python-rtmidi, PyQt5)
- assets/ – font files, images
- JustChord/ – application package
– core/ – pure-logic layer (chord detection, harmony calculations, constants, utilities)
– gui/ – PyQt5 widget layer (app launch, windows, widgets, config viewer)

##### README for Additional Insights
- Core features: chord recognition, auto-key detection, customizable chord dictionary in core/constants.py.
- GUI: multiple draggable widgets (staff, chords, wheel, keyboard).
- External libs: RtMidi, PyQt5.

a. Main Components
1. MIDI Input Layer
– RtMidi driver (external library)
– MIDI event queue
2. Core Processing Layer
– ChordRecognizer (core/chord.py)
– HarmonyCalculator (core/some_harmony_calculator.py)
– Constants & Config (core/constants.py)
– Utilities (core/utils.py)
3. GUI Layer (PyQt5)
– App bootstrap (gui/app.py)
– Windows & Widgets:
- ChordWindow
- StaffWindow
- WheelWindow
- KeyboardWidget
- Monitor
- ConfigViewer
4. Assets & Resources
– Fonts/images under assets/
5. Entry Point
– main.py orchestrates setup of MIDI, core, and GUI

b. Relationships & Data Flow
– User or MIDI device → RtMidi → MIDI events → CoreProcessing
– CoreProcessing → Event signals (PyQt) → GUI Widgets update visuals
– GUI events (drag, right-click, wheel scroll) → ConfigViewer/CoreConstants updates
– Assets loaded by GUI for rendering fonts/images

c. Architectural Patterns & Principles
– Layered architecture: separate MIDI I/O, core logic, and GUI
– Observer/publish-subscribe via PyQt signals for event propagation
– Single responsibility: each widget handles one visualization

d. Key Technologies/Frameworks
– Python 3.6+
– python-rtmidi (RtMidi bindings)
– PyQt5 (Qt Widgets, Signals & Slots)

##### Essential Elements
- Labels on each component (e.g., “ChordRecognizer”)
- Arrowheads indicating flow direction
- External dependencies (PyQt5, RtMidi) at the edge

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "MIDI I/O Layer"
        MIDI_Device["MIDI Device"]:::external
        RtMidi["RtMidi Driver"]:::io
        MIDI_Queue["MIDI Event Queue"]:::io
    end

    subgraph "Core Processing Layer"
        ChordRecognizer["ChordRecognizer"]:::core
        HarmonyCalculator["HarmonyCalculator"]:::core
        Constants["Constants & Config"]:::config
        Utilities["Utilities"]:::core
    end

    subgraph "GUI Layer"
        GUI_App["App Bootstrap (app.py)"]:::gui
        ChordWindow["ChordWindow"]:::gui
        StaffWindow["StaffWindow"]:::gui
        WheelWindow["WheelWindow"]:::gui
        KeyboardWidget["KeyboardWidget"]:::gui
        MonitorWidget["Monitor"]:::gui
        ConfigViewer["ConfigViewer"]:::gui
    end

    subgraph "Assets & Resources"
        Assets["Fonts/Images"]:::config
    end

    Requirements["requirements.txt"]:::external

    MIDI_Device -->|sends MIDI data| RtMidi
    RtMidi -->|queues events| MIDI_Queue
    MIDI_Queue -->|dispatches events| Main
    Main["main.py"]:::core
    Main -->|initialize| ChordRecognizer
    Main -->|initialize| HarmonyCalculator
    Main -->|initialize| GUI_App

    ChordRecognizer -->|uses| Constants
    ChordRecognizer -->|uses| Utilities
    HarmonyCalculator -->|uses| Constants
    HarmonyCalculator -->|uses| Utilities

    GUI_App -->|launches| ChordWindow
    GUI_App -->|launches| StaffWindow
    GUI_App -->|launches| WheelWindow
    GUI_App -->|launches| KeyboardWidget
    GUI_App -->|launches| MonitorWidget
    GUI_App -->|launches| ConfigViewer

    ChordRecognizer -->|emits signals| ChordWindow
    HarmonyCalculator -->|emits signals| StaffWindow
    ChordRecognizer -->|emits signals| WheelWindow
    ChordRecognizer -->|emits signals| KeyboardWidget
    ChordRecognizer -->|emits signals| MonitorWidget

    ChordWindow -->|loads assets| Assets
    StaffWindow -->|loads assets| Assets
    WheelWindow -->|loads assets| Assets
    KeyboardWidget -->|loads assets| Assets
    MonitorWidget -->|loads assets| Assets
    GUI_App -->|loads assets| Assets

    ConfigViewer -->|updates| Constants
    GUI_App -->|reads| Requirements

    click Main "https://github.com/promethiuml/justchord/blob/main/main.py"
    click RtMidi "https://github.com/promethiuml/justchord/blob/main/main.py"
    click ChordRecognizer "https://github.com/promethiuml/justchord/blob/main/JustChord/core/chord.py"
    click HarmonyCalculator "https://github.com/promethiuml/justchord/blob/main/JustChord/core/some_harmony_calculator.py"
    click Constants "https://github.com/promethiuml/justchord/blob/main/JustChord/core/constants.py"
    click Utilities "https://github.com/promethiuml/justchord/blob/main/JustChord/core/utils.py"
    click GUI_App "https://github.com/promethiuml/justchord/blob/main/JustChord/gui/app.py"
    click ChordWindow "https://github.com/promethiuml/justchord/blob/main/JustChord/gui/chordwindow.py"
    click StaffWindow "https://github.com/promethiuml/justchord/blob/main/JustChord/gui/staffwindow.py"
    click WheelWindow "https://github.com/promethiuml/justchord/blob/main/JustChord/gui/wheelwindow.py"
    click KeyboardWidget "https://github.com/promethiuml/justchord/blob/main/JustChord/gui/keyboardwidget.py"
    click MonitorWidget "https://github.com/promethiuml/justchord/blob/main/JustChord/gui/monitor.py"
    click ConfigViewer "https://github.com/promethiuml/justchord/blob/main/JustChord/gui/configviewer.py"
    click Assets "https://github.com/promethiuml/justchord/tree/main/assets/Gothic_A1/"
    click Requirements "https://github.com/promethiuml/justchord/blob/main/requirements.txt"

    classDef io fill:#ADD8E6,stroke:#000
    classDef core fill:#90EE90,stroke:#000
    classDef gui fill:#FFA500,stroke:#000
    classDef config fill:#D3D3D3,stroke:#000
    classDef external fill:#EEEEEE,stroke:#000
```
