# brainflow-dev/brainflow architecture

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

- Interactive diagram: https://gitdiagram.com/brainflow-dev/brainflow
- Repository: https://github.com/brainflow-dev/brainflow

## Overview

##### Project Type and Purpose
- BrainFlow is an open-source, multi-language SDK for biosensor data acquisition and processing.
- Core functionality (written in C/C++) provides board-agnostic data acquisition, signal processing, and ML inference; bindings expose this core to Python, Java, C#, MATLAB, R, Julia, Rust, Node.js and standalone C++ examples.
- An emulator simulates hardware for integration tests and CI pipelines.

##### High-Level Components
A. C++ Core Engine (src/)
- board_controller – hardware abstraction layer (drivers for dozens of boards)
- data_handler – low-level signal processing (filters, transforms)
- ml – machine learning modules (ONNX, dynamic libs)
- utils – common utilities, networking, logging, shared types
B. Language Bindings
- python_package/ – CPython wrapper via ctypes
- java_package/ – JNI wrapper, Maven packaging
- cpp_package/ – C++ examples, CMake-based installable library
- csharp_package/, matlab_package/, r_package/, julia_package/, nodejs_package/, rust_package/ – language-specific shims calling into the compiled core
C. Emulator (emulator/brainflow_emulator)
- Python modules that emulate board output over virtual serial, UDP, etc., used by CI/CD to test all drivers
D. Third-Party Libraries (third_party/)
- Eigen, DSPFilters, ONNX Runtime, spdlog, SimpleBLE, various board SDKs
E. Build & Packaging
- CMakeLists.txt, cmake/, conanfile.py, Docker/Dockerfile, tools/ – build definitions, packaging scripts, Docker images
F. CI/CD Infrastructure
- .github/workflows/ – GitHub Actions for formatting, static analysis, unit/integration tests across platforms, deploy to PyPI/NuGet/etc.
G. Documentation & Examples
- docs/ – Sphinx/ReadTheDocs documentation and Jupyter notebooks
- examples/ in each binding package demonstrating typical usage

##### Relationships and Interactions
- Language Bindings → call into the Core Engine (board_shim, data_filter, ml_model symbols) via foreign-function interfaces (FFI/JNI/ctypes).
- Core Engine → loads drivers in board_controller and ML modules (dynamic or ONNX library).
- Core Engine → uses third_party libraries to accelerate math and hardware interfaces.
- Emulator ↔ Core Engine: emulator publishes fake streams that core’s board_controller consumes, enabling deterministic tests.
- Build & Packaging → compiles Core Engine into shared/static libraries, packages language bindings, builds Docker images for CI.
- CI/CD → orchestrates builds across OS/architectures, runs emulator-backed integration tests, deploys artifacts.

##### Architectural Patterns & Principles
- Layered Architecture: hardware abstraction → data processing → ML → API layer
- Plugin/Driver Pattern: board_controller supports plugging in new board drivers via consistent interface
- FFI Wrappers: language-agnostic core with repeatable, identical APIs across languages
- Emulation for Testability: decoupling hardware from tests
- Modular Build: CMake + Conan for flexible dependency management, Docker for reproducible environments

- Clear, descriptive labels on every component
- Capturing all essential architectural elements without over-fragmentation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Third-Party Libraries
    subgraph "Third-Party Libraries"
        TPL["Third-Party Libraries"]:::db
    end

    %% Core Engine
    subgraph "C++ Core Engine"
        BC["board_controller"]:::core
        DH["data_handler"]:::core
        ML["ml"]:::core
        UT["utils"]:::core
    end

    %% Language Bindings
    subgraph "Language Bindings"
        PY_pkg["Python Binding"]:::binding
        PY_ex["Python Examples & Tests"]:::binding
        JV_pkg["Java Binding"]:::binding
        CPPC_src["C++ Binding"]:::binding
        CPPC_ex["C++ Examples"]:::binding
        CS_pkg["C# Binding"]:::binding
        CS_ex["C# Examples"]:::binding
        MA_pkg["MATLAB Binding"]:::binding
        MA_ex["MATLAB Examples"]:::binding
        R_pkg["R Binding"]:::binding
        R_ex["R Examples"]:::binding
        JU_src["Julia Binding"]:::binding
        JU_test["Julia Tests"]:::binding
        ND_pkg["Node.js Binding"]:::binding
        ND_test["Node.js Tests"]:::binding
        RS_src["Rust Binding"]:::binding
        RS_ex["Rust Examples"]:::binding
    end

    %% Emulator Service
    subgraph "Emulator Service"
        EM["Emulator"]:::service
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        CMake["CMake Definitions"]:::infra
        Conan["Conan"]:::infra
        Docker["Docker Images"]:::infra
        Tools["Helper Scripts"]:::infra
    end

    %% CI/CD Infrastructure
    subgraph "CI/CD"
        CI["CI/CD Workflows"]:::infra
    end

    %% Deployment Targets
    CL["DockerHub/PyPI/NuGet/etc"]:::cloud

    %% Data & Control Flows
    TPL -->|"used by"| BC
    TPL -->|"used by"| DH
    TPL -->|"used by"| ML
    TPL -->|"used by"| UT

    BC -->|"sensor data"| DH
    DH -->|"filtered data"| ML
    ML -->|"results"| CL

    PY_pkg -->|"FFI"| BC
    PY_ex -->|"FFI"| BC
    JV_pkg -->|"FFI"| BC
    CPPC_src -->|"FFI"| BC
    CPPC_ex -->|"FFI"| BC
    CS_pkg -->|"FFI"| BC
    CS_ex -->|"FFI"| BC
    MA_pkg -->|"FFI"| BC
    MA_ex -->|"FFI"| BC
    R_pkg -->|"FFI"| BC
    R_ex -->|"FFI"| BC
    JU_src -->|"FFI"| BC
    JU_test -->|"FFI"| BC
    ND_pkg -->|"FFI"| BC
    ND_test -->|"FFI"| BC
    RS_src -->|"FFI"| BC
    RS_ex -->|"FFI"| BC

    EM -->|"test streams"| BC

    CI -->|triggers build| CMake
    CI -->|triggers build| Conan
    CI -->|triggers build| Docker
    CI -->|triggers build| Tools
    CI -->|runs emulator tests| EM
    CI -->|deploys artifacts| CL

    %% Click Events
    click BC "https://github.com/brainflow-dev/brainflow/tree/master/src/board_controller"
    click DH "https://github.com/brainflow-dev/brainflow/tree/master/src/data_handler"
    click ML "https://github.com/brainflow-dev/brainflow/tree/master/src/ml"
    click UT "https://github.com/brainflow-dev/brainflow/tree/master/src/utils"
    click PY_pkg "https://github.com/brainflow-dev/brainflow/tree/master/python_package/brainflow"
    click PY_ex "https://github.com/brainflow-dev/brainflow/tree/master/python_package/examples"
    click JV_pkg "https://github.com/brainflow-dev/brainflow/tree/master/java_package/brainflow/src/main/java/brainflow"
    click CPPC_src "https://github.com/brainflow-dev/brainflow/tree/master/cpp_package/src"
    click CPPC_ex "https://github.com/brainflow-dev/brainflow/tree/master/cpp_package/examples"
    click CS_pkg "https://github.com/brainflow-dev/brainflow/tree/master/csharp_package/brainflow/brainflow"
    click CS_ex "https://github.com/brainflow-dev/brainflow/tree/master/csharp_package/brainflow/examples"
    click MA_pkg "https://github.com/brainflow-dev/brainflow/tree/master/matlab_package/brainflow"
    click MA_ex "https://github.com/brainflow-dev/brainflow/tree/master/matlab_package/brainflow/examples"
    click R_pkg "https://github.com/brainflow-dev/brainflow/tree/master/r_package/brainflow"
    click R_ex "https://github.com/brainflow-dev/brainflow/tree/master/r_package/examples"
    click JU_src "https://github.com/brainflow-dev/brainflow/tree/master/julia_package/brainflow/src"
    click JU_test "https://github.com/brainflow-dev/brainflow/tree/master/julia_package/brainflow/test"
    click ND_pkg "https://github.com/brainflow-dev/brainflow/tree/master/nodejs_package/brainflow"
    click ND_test "https://github.com/brainflow-dev/brainflow/tree/master/nodejs_package/tests"
    click RS_src "https://github.com/brainflow-dev/brainflow/tree/master/rust_package/brainflow/src"
    click RS_ex "https://github.com/brainflow-dev/brainflow/tree/master/rust_package/brainflow/examples"
    click EM "https://github.com/brainflow-dev/brainflow/tree/master/emulator/brainflow_emulator"
    click TPL "https://github.com/brainflow-dev/brainflow/tree/master/third_party/"
    click CMake "https://github.com/brainflow-dev/brainflow/blob/master/CMakeLists.txt"
    click Conan "https://github.com/brainflow-dev/brainflow/blob/master/conanfile.py"
    click Docker "https://github.com/brainflow-dev/brainflow/tree/master/Docker/Dockerfile"
    click Tools "https://github.com/brainflow-dev/brainflow/tree/master/tools/"
    click CI "https://github.com/brainflow-dev/brainflow/tree/master/.github/workflows/"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:1px
    classDef binding fill:#bbf,stroke:#333,stroke-width:1px
    classDef db fill:#fee,stroke:#333,stroke-width:1px
    classDef service fill:#dfd,stroke:#333,stroke-width:1px
    classDef infra fill:#ffd,stroke:#333,stroke-width:1px
    classDef cloud fill:#cff,stroke:#333,stroke-width:1px
```
