# omkamra/cowbells architecture

> Architecture diagram of the GitHub repository omkamra/cowbells, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/omkamra/cowbells
- Repository: https://github.com/omkamra/cowbells

## Overview

Key Components to Include:

##### Core System Components
- FluidSynth Integration Layer (via JNR-FFI)
- Music Description Language Parser
- Sequencer Engine
- Scale Management System
- Live Looping Engine

##### Data Flow Architecture

**User Interface Layer**

**Music Description Layer**

**Core Processing Layer**

**Audio Output Layer**

Specific Instructions for Drawing:

##### Top Level (User Interface)
- It to both the Music Description Layer and Live Looping System
- Use blue coloring to indicate interactive components

##### Music Description Layer (Second Level)
- Music Description Parser
- Scale Management
- Pattern Storage
- Use green coloring for these processing components

##### Core Processing Layer (Third Level)
- Following connected components:
- Processing System
- MIDI Event Generator
- Timing Control
- Use orange coloring for core engine components

##### Bottom Level (Output)
- It to FluidSynth
- Use purple coloring for external integration components

Important Relationships to Show:

- How musical phrases flow from the REPL through the parser
- How scale information influences note processing
- Demonstrate the sequencer's control over timing and event generation
- Final path to FluidSynth through JNR-FFI

##### Control Flow
- Live looping control paths
- Scale and mode change propagation
- Demonstrate pattern reuse paths

Special Considerations:

##### Extensibility
- A note about OSC visualization possibilities

##### State Management
- A "State" component showing:
- Current scale/mode
- Active patterns
- MIDI channel settings
- Timing information

- Rectangles: Core processing components
- Rounded rectangles: Interface components
- Hexagons: External systems
- Solid: Direct data flow

Level of Detail:
- Notes about Linux compatibility and potential platform extensions

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef interface fill:#a8d1f0,stroke:#2980b9
    classDef processing fill:#a8e6cf,stroke:#2ecc71
    classDef core fill:#ffb6b6,stroke:#e74c3c
    classDef external fill:#d7bde2,stroke:#8e44ad
    classDef storage fill:#f9e79f,stroke:#f1c40f

    %% User Interface Layer
    REPL[Clojure REPL Interface]:::interface
    click REPL "https://github.com/omkamra/cowbells/blob/master/src/omkamra/cowbells.clj"

    %% Music Description Layer
    subgraph MusicLayer[Music Description Layer]
        Parser[Music Description Parser]:::processing
        ScaleMgmt[Scale Management]:::processing
        PatternStore[Pattern Storage]:::storage
        click PatternStore "https://github.com/omkamra/cowbells/tree/master/src/omkamra/cowbells/examples/"
    end

    %% Core Processing Layer
    subgraph CoreLayer[Core Processing Layer]
        SeqEngine[Sequencer Engine]:::core
        NoteProc[Note Processing System]:::core
        MIDIGen[MIDI Event Generator]:::core
        TimeCtrl[Timing Control]:::core
    end

    %% State Management
    State[(System State)]:::storage
    
    %% Output Layer
    JNRFFI[JNR-FFI Bridge]:::external
    FluidSynth[FluidSynth]:::external

    %% Live Looping System
    LiveLoop[Live Looping Engine]:::core

    %% Relationships
    REPL --> Parser
    REPL --> LiveLoop
    Parser <--> ScaleMgmt
    Parser <--> PatternStore
    ScaleMgmt <--> PatternStore
    
    Parser --> SeqEngine
    ScaleMgmt --> NoteProc
    PatternStore --> SeqEngine
    
    SeqEngine --> NoteProc
    NoteProc --> MIDIGen
    TimeCtrl --> SeqEngine
    
    MIDIGen --> JNRFFI
    JNRFFI --> FluidSynth
    
    LiveLoop --> SeqEngine
    State <--> SeqEngine
    State <--> ScaleMgmt
    
    %% Extension Points
    subgraph Extensions[Extension Points]
        OSCViz[OSC Visualization]:::interface
        PlatformExt[Platform Extensions]:::interface
    end
    
    SeqEngine -.-> Extensions

    %% Legend
    subgraph Legend
        L1[Processing Component]:::processing
        L2[Interface Component]:::interface
        L3[Core Component]:::core
        L4[External System]:::external
        L5[(Storage)]:::storage
    end

    %% Tutorial and Examples
    Tutorial[Tutorial System]:::interface
    Examples[Example Patterns]:::processing
    click Tutorial "https://github.com/omkamra/cowbells/blob/master/src/omkamra/cowbells/tutorial.clj"
    click Examples "https://github.com/omkamra/cowbells/blob/master/src/omkamra/cowbells/examples/fur_elise.clj"
    
    REPL --> Tutorial
    Tutorial --> Examples
    Examples --> PatternStore
```
