# ideoforms/signalflow architecture

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

- Interactive diagram: https://gitdiagram.com/ideoforms/signalflow
- Repository: https://github.com/ideoforms/signalflow

## Overview

##### Project type and purpose
- SignalFlow is an open-source sound synthesis framework. It exposes a Python API for interactive audio graph construction in Jupyter or scripts, with a high-performance C++11 core engine.
- The README makes clear it provides an AudioGraph of interconnected Nodes, a modular library of synthesis and processing units, Python bindings (pybind11), cross-platform audio I/O, and a pip-installable package.

##### File structure
- Top-level directories:
- `source/` – C++ core engine, split into `include/` (public headers) and `src/` (implementation), with subtrees for `core`, `node` (analysis, buffer, envelope, FFT, IO, operators, oscillators, processors, sequencing, stochastic), `patch`, and `python` (pybind11 wrappers).
- `auxiliary/` – build helpers, extra Python stub libs, CLI, examples.
- `tests/` – Python unit tests exercising the Python API and graph behavior.
- `examples/` – Python scripts and Jupyter notebooks for end users.
- `docs/` and `mkdocs.yml` – documentation website content.
- Build/config: `CMakeLists.txt` for C++ build, `setup.py`/`pyproject.toml`/`setup.cfg` for Python packaging, GitHub Actions workflows in `.github/workflows/`.

##### README for additional insights
- The README describes the layered architecture: client scripts → Python API → C++ engine → audio device.
- It lists the Node class library categories, confirming the modular design of nodes (oscillators, filters, envelopes, etc.).

##### Key components
a. Frontend (Python layer):
- User scripts / Jupyter notebooks (`examples/`), installed Python package `signalflow`
- `signalflow.python` module (pybind11 wrappers)
b. Binding layer:
- pybind11 integration in `source/src/python/` → exposes C++ classes and functions to Python
c. Core engine (C++):
- `core` subsystem: graph scheduler, config, renderer, utilities
- `node` subsystem: Node registry and each category (analysis, buffer, envelope, FFT, I/O, operators, oscillators, processors, sequencing, stochastic)
- `patch` subsystem: patch specification and execution
d. External libraries:
- `pybind11` (embedded under `source/lib/pybind11`)
- `json11` for JSON parsing (patches)
- `miniaudio` or dummy audio driver (`source/include/signalflow/node/io/…`) for cross-platform audio I/O
e. Build & packaging:
- CMake to generate native library (.so/.pyd/.dll)
- `setup.py` / `pyproject.toml` to wrap the native library into a Python wheel
- CI workflows for build and wheel publishing
f. Documentation & Examples
- mkdocs-driven docs site (`docs/`)
- `examples/` and auxiliary scripts for generating wheels or examples

##### Relationships and interactions
- Within C++ engine, show compositional relationships:
- Graph scheduler calls NodeFactory/Registry → instantiates Node subclasses
- Nodes exchange audio buffers (shared memory objects in `buffer/`)
- I/O nodes interface with `miniaudio` layer → OS audio stack
- Patch subsystem serializes/deserializes graphs via JSON (json11)
- Build chain: CMake config → compiles C++ → links pybind11 → outputs native extension → Python packaging wraps it → pip wheel

##### Architectural patterns and principles
- Layered architecture (UI → binding → engine → hardware)
- Composite pattern for AudioGraph and Node tree
- Factory/Registry for dynamic Node instantiation
- Modular subsystem separation by functionality (analysis, oscillator, filter, etc.)
- Platform abstraction for I/O (abstract input/output interfaces with multiple backends)
- Clear separation of concerns:
- C++ core (performance)
- Python API (usability)
- Build/Packing (distribution)
- Documentation (user onboarding)

##### Detail level
- Essential architectural elements: Python CLI/UI, API binding, engine subsystems (core, node categories, patch), I/O abstraction, build & packaging, docs.
- Don’t attempt to illustrate every single node class; instead group them by category.
- Flow of control (calls) and data (audio buffers, JSON patches) distinctly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend & Docs
    subgraph "Frontend & Docs"
        U["User Scripts & Examples"]:::frontend
        D["Documentation Website"]:::frontend
    end

    %% Python Binding Layer
    subgraph "Python Binding Layer"
        PBIND_SRC["Bindings Source (pybind11 wrappers)"]:::frontend
        PBIND_HDR["Python Headers"]:::frontend
    end

    %% C++ Core Engine
    subgraph "C++ Core Engine"
        subgraph "Core Subsystem"
            CoreImp["Core Implementation"]:::cpp
            CoreHdr["Core Public Headers"]:::cpp
        end
        subgraph "Node Subsystem"
            NodeImp["Node Implementation"]:::cpp
            NodeHdr["Node Public Headers"]:::cpp
        end
        subgraph "Patch Subsystem"
            PatchImp["Patch Implementation"]:::cpp
            PatchHdr["Patch Public Headers"]:::cpp
        end
        subgraph "I/O Subsystem"
            IOImp["I/O Implementation"]:::cpp
            IOHdr["I/O Public Headers"]:::cpp
        end
    end

    %% External Libraries
    subgraph "External Libraries"
        PB["pybind11"]:::ext
        JSON["json11"]:::ext
        MA["miniaudio"]:::ext
    end

    %% Build & CI
    subgraph "Build & CI"
        CMAKE["CMake"]:::tools
        NATIVE["Native Extension (.so/.pyd/.dll)"]:::tools
        WHEEL["Python Wheel Packaging"]:::tools
        CI["CI Workflows"]:::tools
    end

    %% Relationships
    U -->|"imports"| PBIND_SRC
    PBIND_SRC -->|"exposes API to Python"| CoreImp
    PBIND_SRC -->|"includes headers"| PBIND_HDR

    CoreImp --> CoreHdr
    NodeImp --> NodeHdr
    PatchImp --> PatchHdr
    IOImp --> IOHdr

    PBIND_SRC -->|"calls"| CoreImp
    CoreImp -->|"uses"| CoreHdr

    CoreImp -->|"uses"| NodeImp
    NodeImp -->|"registered by"| NodeHdr

    CoreImp -->|"uses"| PatchImp
    PatchImp -->|"serializes via"| JSON

    NodeImp -->|"I/O nodes use"| IOImp
    IOImp -->|"interfaces with"| MA

    CMAKE -->|"builds"| NATIVE
    NATIVE -->|"packaged by"| WHEEL
    WHEEL -->|"published to"| U

    CI -->|"runs"| CMAKE
    CI -->|"runs"| WHEEL

    D -->|"serves docs from"| D

    %% Click Events
    click U "https://github.com/ideoforms/signalflow/tree/master/examples/"
    click D "https://github.com/ideoforms/signalflow/tree/master/docs/"
    click PBIND_SRC "https://github.com/ideoforms/signalflow/tree/master/source/src/python/"
    click PBIND_HDR "https://github.com/ideoforms/signalflow/tree/master/source/include/signalflow/python/"
    click CoreImp "https://github.com/ideoforms/signalflow/tree/master/source/src/core/"
    click CoreHdr "https://github.com/ideoforms/signalflow/tree/master/source/include/signalflow/core/"
    click NodeImp "https://github.com/ideoforms/signalflow/tree/master/source/src/node/"
    click NodeHdr "https://github.com/ideoforms/signalflow/tree/master/source/include/signalflow/node/"
    click PatchImp "https://github.com/ideoforms/signalflow/tree/master/source/src/patch/"
    click PatchHdr "https://github.com/ideoforms/signalflow/tree/master/source/include/signalflow/patch/"
    click IOImp "https://github.com/ideoforms/signalflow/tree/master/source/src/node/io/"
    click IOHdr "https://github.com/ideoforms/signalflow/tree/master/source/include/signalflow/node/io/"
    click PB "https://github.com/ideoforms/signalflow/tree/master/source/lib/pybind11/"
    click JSON "https://github.com/ideoforms/signalflow/tree/master/source/lib/json11/"
    click CMAKE "https://github.com/ideoforms/signalflow/blob/master/CMakeLists.txt"
    click NATIVE "https://github.com/ideoforms/signalflow/blob/master/source/src/CMakeLists.txt"
    click WHEEL "https://github.com/ideoforms/signalflow/blob/master/setup.py"
    click WHEEL "https://github.com/ideoforms/signalflow/blob/master/pyproject.toml"
    click WHEEL "https://github.com/ideoforms/signalflow/blob/master/setup.cfg"
    click CI "https://github.com/ideoforms/signalflow/blob/master/.github/workflows/build.yml"
    click CI "https://github.com/ideoforms/signalflow/blob/master/.github/workflows/wheels.yml"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef cpp fill:#90EE90,stroke:#333,stroke-width:1px
    classDef ext fill:#FFA500,stroke:#333,stroke-width:1px
    classDef tools fill:#D3D3D3,stroke:#333,stroke-width:1px
```
