# miracatici/makambox architecture

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

- Interactive diagram: https://gitdiagram.com/miracatici/makambox
- Repository: https://github.com/miracatici/makambox

## Overview

##### Project Type and Purpose
- MakamBox is a standalone Java desktop application (not a web or full-stack service).
- It is an open-source interactive music tuition tool focused on Turkish Makam theory.
- Key functionality: real-time pitch detection, makam/tonic analysis, and visualization for user recordings vs. reference recordings.

##### High-Level Architectural Layers
A. Presentation Layer (UI)
- Package: src/graphics
- Components: About, HistogramChart, MakamChart, PitchChart, TonicChart, WaveChart, etc.
- Responsibilities: render charts, accept user input (file chooser, play/pause), display feedback in real time.
B. Application Orchestration Layer
- Package: src/applied
- Components: DataTool, HistogramExtractor, MakamBoxAnalysis, MultiAnalysis, SelectCulture, Tuner, Tuning.
- Responsibilities: coordinate user commands, select analysis routines, load cultural settings, invoke core logic.
C. Core Logic Layer
- Sub-layers:
1. Audio Processing (src/backEnd)
– Components: AudioInput (captures microphone or file), PitchDetection, Yin, PitchTracking, PitchShift, Wavefile, WaveWriter, Player, SineSynth, TemplateCreate, Histogram.
– Responsibilities: real-time audio I/O, pitch extraction, synthesis, template creation.
2. Analysis & Classification (src/analysis)
– Components: AnalysisForTonic, AnalysisForJoint, CompareForTonic, CompareForJoint, SingleMakamSoloRecordings, MBIDtoPath, TonicAnnotationMatch.
– Responsibilities: compute histograms, compare user vs. reference, classify makam/tonic.
D. Data Model Layer
- Package: src/datas
- Components: Makam, Note, Culture, Ahenk, TuningSystem, and factory classes.
- Responsibilities: hold domain objects (notes, intervals, cultural tuning data).
E. Utilities Layer
- Package: src/utilities
- Components: AudioUtilities, Plot, Write.
- Responsibilities: common helpers (file I/O, chart helpers, logging).
F. External Resources
G. External Dependencies (lib)
- TarsosDSP (Yin pitch detection), JFreeChart/JFreeSVG (charts), Commons-io/lang/math, javax.json, jl1.0.1 (MP3), etc.

##### Component Relationships & Data Flow
- User → UI: selects reference and live audio.
- UI → Application Orchestration: submits “analyze” commands.
- Orchestration → Audio Processing: starts AudioInput, PitchDetection, Yin.
- AudioProcessing → Data Model: produces streams of pitch/time data records.
- Orchestration → Analysis: passes pitch streams and reference templates.
- Analysis → Data Model: computes histograms, classification results.
- Analysis → Utilities: writes results to “results” folder.
- UI ← Analysis: fetches results to render in dynamic charts.
- Data Model ↔ Data Resources: loads tuning/makam definitions from makams/* and settings/*.ser.

##### Architectural Patterns & Principles
- Layered architecture (Presentation, Orchestration, Core Logic, Data).
- MVC-like separation: graphics = view, applied = controller, datas = model.
- Modular packages for testability (src/test).
- Pluggable data: external makam files and settings allow extensibility.
- Real-time stream processing pipeline for audio.

##### Essential Elements
- Notes on real-time stream vs. batch analysis paths.
- Grouping of “src” packages to reveal the MVC pattern.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer (UI)
    subgraph "Presentation Layer (UI)"
        direction TB
        About["About"]:::presentation
        HistogramChart["HistogramChart"]:::presentation
        MakamChart["MakamChart"]:::presentation
        PitchChart["PitchChart"]:::presentation
        TonicChart["TonicChart"]:::presentation
        WaveChart["WaveChart"]:::presentation
    end

    %% Application Orchestration Layer
    subgraph "Application Orchestration Layer" 
        direction TB
        DataTool["DataTool"]:::orchestration
        HistogramExtractor["HistogramExtractor"]:::orchestration
        MakamBoxAnalysis["MakamBoxAnalysis"]:::orchestration
        MultiAnalysis["MultiAnalysis"]:::orchestration
        SelectCulture["SelectCulture"]:::orchestration
        Tuner["Tuner"]:::orchestration
        Tuning["Tuning"]:::orchestration
    end

    %% Core Logic Layer
    subgraph "Core Logic Layer"
        direction TB
        subgraph "Audio Processing"
            direction TB
            AudioInput["AudioInput"]:::core
            PitchDetection["PitchDetection"]:::core
            Yin["Yin"]:::core
            PitchTracking["PitchTracking"]:::core
            PitchShift["PitchShift"]:::core
            Wavefile["Wavefile"]:::core
            WaveWriter["WaveWriter"]:::core
            Player["Player"]:::core
            SineSynth["SineSynth"]:::core
            TemplateCreate["TemplateCreate"]:::core
            HistogramCore["Histogram"]:::core
        end
        subgraph "Analysis & Classification"
            direction TB
            AnalysisForTonic["AnalysisForTonic"]:::core
            AnalysisForJoint["AnalysisForJoint"]:::core
            CompareForTonic["CompareForTonic"]:::core
            CompareForJoint["CompareForJoint"]:::core
            SingleMakamSoloRecordings["SingleMakamSoloRecordings"]:::core
            MBIDtoPath["MBIDtoPath"]:::core
            TonicAnnotationMatch["TonicAnnotationMatch"]:::core
        end
    end

    %% Data Model Layer
    subgraph "Data Model Layer"
        direction TB
        Makam["Makam"]:::data
        Note["Note"]:::data
        Culture["Culture"]:::data
        Ahenk["Ahenk"]:::data
        TuningSystem["TuningSystem"]:::data
        CultureCreate["CultureCreate"]:::data
        TuningSystemCreate["TuningSystemCreate"]:::data
    end

    %% Utilities Layer
    subgraph "Utilities Layer"
        direction TB
        AudioUtilities["AudioUtilities"]:::util
        Plot["Plot"]:::util
        Write["Write"]:::util
    end

    %% External Resources
    subgraph "External Resources"
        direction TB
        Makams["makams/*"]:::extRes
        Settings["settings/*.ser"]:::extRes
        Results["results/*"]:::extRes
        Image["image/*"]:::extRes
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        TarsosDSP["TarsosDSP-2.3.jar"]:::extDep
        JFreeChart["jfreechart-1.0.19.jar"]:::extDep
        CommonsIO["commons-io-2.4.jar"]:::extDep
        MP3["jl1.0.1.jar"]:::extDep
        JSONLib["javax.json-1.0-b06.jar"]:::extDep
    end

    %% User interaction
    User((User)):::external
    User -->|"selects audio"| About

    %% Flow UI -> Orchestration
    About -->|"analyze"| DataTool
    HistogramChart --> DataTool
    MakamChart --> DataTool
    PitchChart --> DataTool
    TonicChart --> DataTool
    WaveChart --> DataTool

    %% Orchestration -> Core Audio
    DataTool -->|"start audio stream"| AudioInput
    HistogramExtractor --> AudioInput
    MakamBoxAnalysis --> AudioInput
    MultiAnalysis --> AudioInput

    %% Audio Processing pipeline
    AudioInput -->|"audio stream"| PitchDetection
    PitchDetection -->|"pitch data"| Yin
    Yin -->|"refined pitch"| PitchTracking
    PitchTracking -->|"tracked pitch"| HistogramCore

    %% Orchestration -> Analysis
    DataTool -->|"pitch data"| AnalysisForTonic
    DataTool --> AnalysisForJoint
    HistogramExtractor --> CompareForTonic
    HistogramExtractor --> CompareForJoint

    %% Analysis -> Data Model
    AnalysisForTonic -->|"classification result"| Makam
    CompareForTonic --> Makam
    AnalysisForJoint --> Note
    CompareForJoint --> Note

    %% Analysis -> Utilities -> Results
    SingleMakamSoloRecordings --> Write
    MBIDtoPath --> Write
    TonicAnnotationMatch --> Write
    Write -->|"writes files"| Results

    %% Results -> UI
    Results -->|"load results"| HistogramChart
    Results --> MakamChart
    Results --> TonicChart

    %% Data Model loads resources
    Makams --> Culture
    Settings --> TuningSystem

    %% External Dependencies integration
    AudioInput --> TarsosDSP
    HistogramChart --> JFreeChart
    MakamChart --> JFreeChart
    Plot --> CommonsIO
    Write --> CommonsIO
    AudioUtilities --> MP3
    AudioUtilities --> JSONLib

    %% Click Events
    click About "https://github.com/miracatici/makambox/blob/master/src/graphics/About.java"
    click HistogramChart "https://github.com/miracatici/makambox/blob/master/src/graphics/HistogramChart.java"
    click MakamChart "https://github.com/miracatici/makambox/blob/master/src/graphics/MakamChart.java"
    click PitchChart "https://github.com/miracatici/makambox/blob/master/src/graphics/PitchChart.java"
    click TonicChart "https://github.com/miracatici/makambox/blob/master/src/graphics/TonicChart.java"
    click WaveChart "https://github.com/miracatici/makambox/blob/master/src/graphics/WaveChart.java"
    click DataTool "https://github.com/miracatici/makambox/blob/master/src/applied/DataTool.java"
    click HistogramExtractor "https://github.com/miracatici/makambox/blob/master/src/applied/HistogramExtractor.java"
    click MakamBoxAnalysis "https://github.com/miracatici/makambox/blob/master/src/applied/MakamBoxAnalysis.java"
    click MultiAnalysis "https://github.com/miracatici/makambox/blob/master/src/applied/MultiAnalysis.java"
    click SelectCulture "https://github.com/miracatici/makambox/blob/master/src/applied/SelectCulture.java"
    click Tuner "https://github.com/miracatici/makambox/blob/master/src/applied/Tuner.java"
    click Tuning "https://github.com/miracatici/makambox/blob/master/src/applied/Tuning.java"
    click AudioInput "https://github.com/miracatici/makambox/blob/master/src/backEnd/AudioInput.java"
    click PitchDetection "https://github.com/miracatici/makambox/blob/master/src/backEnd/PitchDetection.java"
    click Yin "https://github.com/miracatici/makambox/blob/master/src/backEnd/Yin.java"
    click PitchTracking "https://github.com/miracatici/makambox/blob/master/src/backEnd/PitchTracking.java"
    click PitchShift "https://github.com/miracatici/makambox/blob/master/src/backEnd/PitchShift.java"
    click Wavefile "https://github.com/miracatici/makambox/blob/master/src/backEnd/Wavefile.java"
    click WaveWriter "https://github.com/miracatici/makambox/blob/master/src/backEnd/WaveWriter.java"
    click Player "https://github.com/miracatici/makambox/blob/master/src/backEnd/Player.java"
    click SineSynth "https://github.com/miracatici/makambox/blob/master/src/backEnd/SineSynth.java"
    click TemplateCreate "https://github.com/miracatici/makambox/blob/master/src/backEnd/TemplateCreate.java"
    click HistogramCore "https://github.com/miracatici/makambox/blob/master/src/backEnd/Histogram.java"
    click AnalysisForTonic "https://github.com/miracatici/makambox/blob/master/src/analysis/AnalysisForTonic.java"
    click AnalysisForJoint "https://github.com/miracatici/makambox/blob/master/src/analysis/AnalysisForJoint.java"
    click CompareForTonic "https://github.com/miracatici/makambox/blob/master/src/analysis/CompareForTonic.java"
    click CompareForJoint "https://github.com/miracatici/makambox/blob/master/src/analysis/CompareForJoint.java"
    click SingleMakamSoloRecordings "https://github.com/miracatici/makambox/blob/master/src/analysis/SingleMakamSoloRecordings.java"
    click MBIDtoPath "https://github.com/miracatici/makambox/blob/master/src/analysis/MBIDtoPath.java"
    click TonicAnnotationMatch "https://github.com/miracatici/makambox/blob/master/src/analysis/TonicAnnotationMatch.java"
    click Makam "https://github.com/miracatici/makambox/blob/master/src/datas/Makam.java"
    click Note "https://github.com/miracatici/makambox/blob/master/src/datas/Note.java"
    click Culture "https://github.com/miracatici/makambox/blob/master/src/datas/Culture.java"
    click Ahenk "https://github.com/miracatici/makambox/blob/master/src/datas/Ahenk.java"
    click TuningSystem "https://github.com/miracatici/makambox/blob/master/src/datas/TuningSystem.java"
    click CultureCreate "https://github.com/miracatici/makambox/blob/master/src/datas/CultureCreate.java"
    click TuningSystemCreate "https://github.com/miracatici/makambox/blob/master/src/datas/TuningSystemCreate.java"
    click AudioUtilities "https://github.com/miracatici/makambox/blob/master/src/utilities/AudioUtilities.java"
    click Plot "https://github.com/miracatici/makambox/blob/master/src/utilities/Plot.java"
    click Write "https://github.com/miracatici/makambox/blob/master/src/utilities/Write.java"

    %% Styles
    classDef presentation fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef orchestration fill:#C8E6C9,stroke:#43A047,color:#1B5E20
    classDef core fill:#A5D6A7,stroke:#388E3C,color:#1B5E20
    classDef data fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef util fill:#E1BEE7,stroke:#8E24AA,color:#4A148C
    classDef extRes fill:#ECEFF1,stroke:#90A4AE,color:#455A64
    classDef extDep fill:#CFD8DC,stroke:#607D8B,color:#263238
    classDef external fill:#FFFFFF,stroke:#000000,color:#000000	               
    class User external
```
